[deliverable/linux.git] / Documentation / linux_tv / media / dvb / fe-read-status.rst

.. -*- coding: utf-8; mode: rst -*-

.. _FE_READ_STATUS:

********************
ioctl FE_READ_STATUS
********************

NAME
====

FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device

SYNOPSIS
========

.. cpp:function:: int ioctl( int fd, int request, unsigned int *status )


ARGUMENTS
=========

``fd``
    File descriptor returned by :ref:`open() <frontend_f_open>`.

``request``
    FE_READ_STATUS

``status``
    pointer to a bitmask integer filled with the values defined by enum
    :ref:`fe_status <fe-status>`.


DESCRIPTION
===========

All DVB frontend devices support the ``FE_READ_STATUS`` ioctl. It is
used to check about the locking status of the frontend after being
tuned. The ioctl takes a pointer to an integer where the status will be
written.

NOTE: the size of status is actually sizeof(enum fe_status), with
varies according with the architecture. This needs to be fixed in the
future.


RETURN VALUE
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


.. _fe-status-t:

int fe_status
=============

The fe_status parameter is used to indicate the current state and/or
state changes of the frontend hardware. It is produced using the enum
:ref:`fe_status <fe-status>` values on a bitmask


.. _fe-status:

.. flat-table:: enum fe_status
    :header-rows:  1
    :stub-columns: 0


    -  .. row 1

       -  ID

       -  Description

    -  .. row 2

       -  .. _`FE-HAS-SIGNAL`:

	  ``FE_HAS_SIGNAL``

       -  The frontend has found something above the noise level

    -  .. row 3

       -  .. _`FE-HAS-CARRIER`:

	  ``FE_HAS_CARRIER``

       -  The frontend has found a DVB signal

    -  .. row 4

       -  .. _`FE-HAS-VITERBI`:

	  ``FE_HAS_VITERBI``

       -  The frontend FEC inner coding (Viterbi, LDPC or other inner code)
	  is stable

    -  .. row 5

       -  .. _`FE-HAS-SYNC`:

	  ``FE_HAS_SYNC``

       -  Synchronization bytes was found

    -  .. row 6

       -  .. _`FE-HAS-LOCK`:

	  ``FE_HAS_LOCK``

       -  The DVB were locked and everything is working

    -  .. row 7

       -  .. _`FE-TIMEDOUT`:

	  ``FE_TIMEDOUT``

       -  no lock within the last about 2 seconds

    -  .. row 8

       -  .. _`FE-REINIT`:

	  ``FE_REINIT``

       -  The frontend was reinitialized, application is recommended to
	  reset DiSEqC, tone and parameters
Commit	Line	Data
	1	.. -- coding: utf-8; mode: rst --
	2
	3	.. _FE_READ_STATUS:
	4
	5	********************
	6	ioctl FE_READ_STATUS
	7	********************
	8
	9	NAME
	10	====
	11
	12	FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device
	13
	14	SYNOPSIS
	15	========
	16
	17	.. cpp:function:: int ioctl( int fd, int request, unsigned int *status )
	18
	19
	20	ARGUMENTS
	21	=========
	22
	23	``fd``
	24	File descriptor returned by :ref:`open() <frontend_f_open>`.
	25
	26	``request``
	27	FE_READ_STATUS
	28
	29	``status``
	30	pointer to a bitmask integer filled with the values defined by enum
	31	:ref:`fe_status <fe-status>`.
	32
	33
	34	DESCRIPTION
	35	===========
	36
	37	All DVB frontend devices support the ``FE_READ_STATUS`` ioctl. It is
	38	used to check about the locking status of the frontend after being
	39	tuned. The ioctl takes a pointer to an integer where the status will be
	40	written.
	41
	42	NOTE: the size of status is actually sizeof(enum fe_status), with
	43	varies according with the architecture. This needs to be fixed in the
	44	future.
	45
	46
	47	RETURN VALUE
	48	============
	49
	50	On success 0 is returned, on error -1 and the ``errno`` variable is set
	51	appropriately. The generic error codes are described at the
	52	:ref:`Generic Error Codes <gen-errors>` chapter.
	53
	54
	55	.. _fe-status-t:
	56
	57	int fe_status
	58	=============
	59
	60	The fe_status parameter is used to indicate the current state and/or
	61	state changes of the frontend hardware. It is produced using the enum
	62	:ref:`fe_status <fe-status>` values on a bitmask
	63
	64
	65	.. _fe-status:
	66
	67	.. flat-table:: enum fe_status
	68	:header-rows: 1
	69	:stub-columns: 0
	70
	71
	72	- .. row 1
	73
	74	- ID
	75
	76	- Description
	77
	78	- .. row 2
	79
	80	- .. _`FE-HAS-SIGNAL`:
	81
	82	``FE_HAS_SIGNAL``
	83
	84	- The frontend has found something above the noise level
	85
	86	- .. row 3
	87
	88	- .. _`FE-HAS-CARRIER`:
	89
	90	``FE_HAS_CARRIER``
	91
	92	- The frontend has found a DVB signal
	93
	94	- .. row 4
	95
	96	- .. _`FE-HAS-VITERBI`:
	97
	98	``FE_HAS_VITERBI``
	99
	100	- The frontend FEC inner coding (Viterbi, LDPC or other inner code)
	101	is stable
	102
	103	- .. row 5
	104
	105	- .. _`FE-HAS-SYNC`:
	106
	107	``FE_HAS_SYNC``
	108
	109	- Synchronization bytes was found
	110
	111	- .. row 6
	112
	113	- .. _`FE-HAS-LOCK`:
	114
	115	``FE_HAS_LOCK``
	116
	117	- The DVB were locked and everything is working
	118
	119	- .. row 7
	120
	121	- .. _`FE-TIMEDOUT`:
	122
	123	``FE_TIMEDOUT``
	124
	125	- no lock within the last about 2 seconds
	126
	127	- .. row 8
	128
	129	- .. _`FE-REINIT`:
	130
	131	``FE_REINIT``
	132
	133	- The frontend was reinitialized, application is recommended to
	134	reset DiSEqC, tone and parameters