Commit 9a721b9b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

media: dvb uAPI docs: adjust return value ioctl descriptions

There are several issues on the return value for ioctls:

- Text is confusing;
- Some error codes don't exist;
- The non-generic error codes should come before the text
  that points to the generic error codes;
- Tables don't contain column size hints;
- Some references are not marked as such.

Correct them.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 4e3b0cab
......@@ -34,13 +34,10 @@ This system call closes a previously opened CA device.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
- .. row 1
- ``EBADF``
- fd is not a valid open file descriptor.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -66,33 +66,11 @@ the device in this mode will fail, and an error code will be returned.
Return Value
------------
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``ENODEV``
- Device driver not loaded/available.
- .. row 2
- ``EINTERNAL``
- Internal error.
- .. row 3
- ``EBUSY``
- Device or resource busy.
- .. row 4
On success 0 is returned.
- ``EINVAL``
On error -1 is returned, and the ``errno`` variable is set
appropriately.
- Invalid argument.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -40,5 +40,7 @@ Return Value
On success 0 is returned and :c:type:`ca_caps` is filled.
On error, -1 is returned and the ``errno`` variable is set
appropriately. The generic error codes are described at the
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -49,6 +49,11 @@ Description
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -43,7 +43,15 @@ On success 0 is returned, and :c:type:`ca_slot_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
If the slot is not available, ``errno`` will contain ``-EINVAL``.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``ENODEV``
- the slot is not available.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -35,6 +35,10 @@ be called before start using the CA hardware.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -38,6 +38,10 @@ Description
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -48,6 +48,10 @@ Description
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -40,6 +40,10 @@ DMX_OUT_TSDEMUX_TAP.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -35,13 +35,10 @@ previously allocated via the open() call.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
On success 0 is returned.
On error, -1 is returned and the ``errno`` variable is set
appropriately.
- .. row 1
- ``EBADF``
- fd is not a valid open file descriptor.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -69,31 +69,20 @@ using the F_SETFL command of the fcntl system call.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``ENODEV``
- Device driver not loaded/available.
On success 0 is returned.
- .. row 2
On error -1 is returned, and the ``errno`` variable is set
appropriately.
- ``EINVAL``
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
- Invalid argument.
- .. row 3
- ``EMFILE``
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``EMFILE``
- “Too many open files”, i.e. no more filters available.
- .. row 4
- ``ENOMEM``
- The driver failed to allocate enough memory.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -41,54 +41,33 @@ implied by count.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- - ``EWOULDBLOCK``
- No data to return and ``O_NONBLOCK`` was specified.
- .. row 1
- ``EWOULDBLOCK``
- No data to return and O_NONBLOCK was specified.
- .. row 2
- ``EBADF``
- fd is not a valid open file descriptor.
- .. row 3
- ``ECRC``
- Last section had a CRC error - no data returned. The buffer is
flushed.
- .. row 4
- ``EOVERFLOW``
-
- .. row 5
-
- - ``EOVERFLOW``
- The filtered data was not read from the buffer in due time,
resulting in non-read data being lost. The buffer is flushed.
- .. row 6
- ``ETIMEDOUT``
- The section was not loaded within the stated timeout period. See
ioctl DMX_SET_FILTER for how to set a timeout.
- - ``ETIMEDOUT``
- The section was not loaded within the stated timeout period.
See ioctl :ref:`DMX_SET_FILTER` for how to set a timeout.
- .. row 7
- - ``EFAULT``
- The driver failed to write to the callers buffer due to an
invalid \*buf pointer.
- ``EFAULT``
- The driver failed to write to the callers buffer due to an invalid
\*buf pointer.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -44,32 +44,29 @@ The amount of data to be transferred is implied by count.
Return Value
------------
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- .. row 1
- ``EWOULDBLOCK``
- No data was written. This might happen if O_NONBLOCK was
- - ``EWOULDBLOCK``
- No data was written. This might happen if ``O_NONBLOCK`` was
specified and there is no more buffer space available (if
O_NONBLOCK is not specified the function will block until buffer
``O_NONBLOCK`` is not specified the function will block until buffer
space is available).
- .. row 2
- ``EBUSY``
- - ``EBUSY``
- This error code indicates that there are conflicting requests. The
corresponding demux device is setup to receive data from the
front- end. Make sure that these filters are stopped and that the
filters with input set to DMX_IN_DVR are started.
- .. row 3
- ``EBADF``
filters with input set to ``DMX_IN_DVR`` are started.
- fd is not a valid open file descriptor.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -37,6 +37,10 @@ Description
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -42,17 +42,24 @@ the real 90kHz STC value is stc->stc / stc->base .
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.
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- .. row 1
- ``EINVAL``
- Invalid stc number.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -41,6 +41,10 @@ DMX_SET_PES_FILTER or DMX_ADD_PID.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -40,6 +40,11 @@ used.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -47,6 +47,11 @@ will be canceled, and the receive buffer will be flushed.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -42,15 +42,17 @@ capability is supported.
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.
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- .. row 1
......@@ -61,3 +63,7 @@ appropriately. The generic error codes are described at the
There are active filters filtering data from another input source.
Make sure that these filters are stopped before starting this
filter.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -29,15 +29,16 @@ Description
-----------
This ioctl call is used to start the actual filtering operation defined
via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER.
via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`.
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.
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
......@@ -51,7 +52,7 @@ appropriately. The generic error codes are described at the
- ``EINVAL``
- Invalid argument, i.e. no filtering parameters provided via the
DMX_SET_FILTER or DMX_SET_PES_FILTER functions.
:ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` ioctls.
- .. row 2
......@@ -61,3 +62,7 @@ appropriately. The generic error codes are described at the
There are active filters filtering data from another input source.
Make sure that these filters are stopped before starting this
filter.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -36,6 +36,10 @@ started via the DMX_START command.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -39,6 +39,10 @@ The received message is stored at the buffer pointed by ``argp``.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -37,6 +37,10 @@ is manually powered off. Not all DVB adapters support this ioctl.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -43,6 +43,10 @@ It provides support for what's specified at
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -38,7 +38,11 @@ Sends the DiSEqC command pointed by ``argp`` to the antenna subsystem.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -46,6 +46,10 @@ dishes were already legacy in 2004.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -45,6 +45,10 @@ voltages.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -44,10 +44,10 @@ an event becomes available.
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.
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. flat-table::
......@@ -66,3 +66,6 @@ appropriately. The generic error codes are described at the
- ``EOVERFLOW``
- Overflow in event queue - one or more events were lost.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -42,11 +42,10 @@ this command, read-only access to the device is sufficient.
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.
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. flat-table::
:header-rows: 0
......@@ -58,3 +57,6 @@ appropriately. The generic error codes are described at the
- ``EINVAL``
- Maximum supported symbol rate reached.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -53,6 +53,10 @@ The frontend capabilities are described at :c:type:`fe_caps`.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -64,6 +64,10 @@ depends on the delivery system and on the device:
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -41,6 +41,10 @@ access to the device is sufficient.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -41,6 +41,10 @@ to the device is sufficient.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -41,6 +41,10 @@ to the device is sufficient.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -56,6 +56,10 @@ state changes of the frontend hardware. It is produced using the enum
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -43,6 +43,10 @@ sufficient.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -48,6 +48,10 @@ FE_TUNE_MODE_ONESHOT mode
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -48,17 +48,24 @@ requires read/write access to the device.
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.
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
- .. row 1
- ``EINVAL``
- Maximum supported symbol rate reached.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -49,6 +49,10 @@ this is done using the DiSEqC ioctls.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -53,6 +53,10 @@ power up the LNBf.
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
On success 0 is returned.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -41,8 +41,10 @@ down automatically.
Return Value
============
The function returns 0 on success, -1 on failure and the ``errno`` is
set appropriately. Possible error codes:
On success 0 is returned.
EBADF
``fd`` is not a valid open file descriptor.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -79,24 +79,32 @@ On error, -1 is returned, and the ``errno`` variable is set appropriately.
Possible error codes are:
EACCES
The caller has no permission to access the device.
EBUSY
The the device driver is already in use.
On success 0 is returned, and :c:type:`ca_slot_info` is filled.
ENXIO
No device corresponding to this device special file exists.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
ENOMEM
Not enough kernel memory was available to complete the request.
.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
EMFILE
The process already has the maximum number of files open.
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 16
ENFILE
The limit on the total number of files open on the system has been
reached.
- - ``EPERM``
- The caller has no permission to access the device.
ENODEV
The device got removed.
- - ``EBUSY``
- The the device driver is already in use.
- - ``EMFILE``
- The process already has the maximum number of files open.
- - ``ENFILE``
- The limit on the total number of files open on the system has been
reached.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -78,6 +78,10 @@ filled with the number of the created interface.
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
On success 0 is returned, and :c:type:`ca_slot_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -43,6 +43,10 @@ the ``errno`` with ``EINVAL`` error code.
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
On success 0 is returned, and :c:type:`ca_slot_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
......@@ -39,6 +39,10 @@ The NET_REMOVE_IF ioctl deletes an interface previously created via
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
On success 0 is returned, and :c:type:`ca_slot_info` is filled.
On error -1 is returned, and the ``errno`` variable is set
appropriately.
The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment