func-select.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _func-select:
  5
  6*************
  7V4L2 select()
  8*************
  9
 10Name
 11====
 12
 13v4l2-select - Synchronous I/O multiplexing
 14
 15Synopsis
 16========
 17
 18.. code-block:: c
 19
 20    #include <sys/time.h>
 21    #include <sys/types.h>
 22    #include <unistd.h>
 23
 24.. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
 25
 26Arguments
 27=========
 28
 29``nfds``
 30  The highest-numbered file descriptor in any of the three sets, plus 1.
 31
 32``readfds``
 33  File descriptions to be watched if a read() call won't block.
 34
 35``writefds``
 36  File descriptions to be watched if a write() won't block.
 37
 38``exceptfds``
 39  File descriptions to be watched for V4L2 events.
 40
 41``timeout``
 42  Maximum time to wait.
 43
 44Description
 45===========
 46
 47With the :c:func:`select()` function applications can suspend
 48execution until the driver has captured data or is ready to accept data
 49for output.
 50
 51When streaming I/O has been negotiated this function waits until a
 52buffer has been filled or displayed and can be dequeued with the
 53:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
 54the outgoing queue of the driver the function returns immediately.
 55
 56On success :c:func:`select()` returns the total number of bits set in
 57``fd_set``. When the function timed out it returns
 58a value of zero. On failure it returns -1 and the ``errno`` variable is
 59set appropriately. When the application did not call
 60:ref:`VIDIOC_QBUF` or
 61:ref:`VIDIOC_STREAMON` yet the :c:func:`select()`
 62function succeeds, setting the bit of the file descriptor in ``readfds``
 63or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
 64calls will fail. [#f1]_
 65
 66When use of the :c:func:`read()` function has been negotiated and the
 67driver does not capture yet, the :c:func:`select()` function starts
 68capturing. When that fails, :c:func:`select()` returns successful and
 69a subsequent :c:func:`read()` call, which also attempts to start
 70capturing, will return an appropriate error code. When the driver
 71captures continuously (as opposed to, for example, still images) and
 72data is already available the :c:func:`select()` function returns
 73immediately.
 74
 75When use of the :c:func:`write()` function has been negotiated the
 76:c:func:`select()` function just waits until the driver is ready for a
 77non-blocking :c:func:`write()` call.
 78
 79All drivers implementing the :c:func:`read()` or :c:func:`write()`
 80function or streaming I/O must also support the :c:func:`select()`
 81function.
 82
 83For more details see the :c:func:`select()` manual page.
 84
 85Return Value
 86============
 87
 88On success, :c:func:`select()` returns the number of descriptors
 89contained in the three returned descriptor sets, which will be zero if
 90the timeout expired. On error -1 is returned, and the ``errno`` variable
 91is set appropriately; the sets and ``timeout`` are undefined. Possible
 92error codes are:
 93
 94EBADF
 95    One or more of the file descriptor sets specified a file descriptor
 96    that is not open.
 97
 98EBUSY
 99    The driver does not support multiple read or write streams and the
100    device is already in use.
101
102EFAULT
103    The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
104    references an inaccessible memory area.
105
106EINTR
107    The call was interrupted by a signal.
108
109EINVAL
110    The ``nfds`` argument is less than zero or greater than
111    ``FD_SETSIZE``.
112
113.. [#f1]
114   The Linux kernel implements :c:func:`select()` like the
115   :c:func:`poll()` function, but :c:func:`select()` cannot
116   return a ``POLLERR``.