Documentation/userspace-api/media/v4l/func-select.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _func-select:
   5
   6 *************
   7 V4L2 select()
   8 *************
   9
  10 Name
  11 ====
  12
  13 v4l2-select - Synchronous I/O multiplexing
  14
  15 Synopsis
  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
  26 Arguments
  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
  44 Description
  45 ===========
  46
  47 With the :c:func:`select()` function applications can suspend
  48 execution until the driver has captured data or is ready to accept data
  49 for output.
  50
  51 When streaming I/O has been negotiated this function waits until a
  52 buffer has been filled or displayed and can be dequeued with the
  53 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
  54 the outgoing queue of the driver the function returns immediately.
  55
  56 On success :c:func:`select()` returns the total number of bits set in
  57 ``fd_set``. When the function timed out it returns
  58 a value of zero. On failure it returns -1 and the ``errno`` variable is
  59 set appropriately. When the application did not call
  60 :ref:`VIDIOC_QBUF` or
  61 :ref:`VIDIOC_STREAMON` yet the :c:func:`select()`
  62 function succeeds, setting the bit of the file descriptor in ``readfds``
  63 or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
  64 calls will fail. [#f1]_
  65
  66 When use of the :c:func:`read()` function has been negotiated and the
  67 driver does not capture yet, the :c:func:`select()` function starts
  68 capturing. When that fails, :c:func:`select()` returns successful and
  69 a subsequent :c:func:`read()` call, which also attempts to start
  70 capturing, will return an appropriate error code. When the driver
  71 captures continuously (as opposed to, for example, still images) and
  72 data is already available the :c:func:`select()` function returns
  73 immediately.
  74
  75 When 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
  77 non-blocking :c:func:`write()` call.
  78
  79 All drivers implementing the :c:func:`read()` or :c:func:`write()`
  80 function or streaming I/O must also support the :c:func:`select()`
  81 function.
  82
  83 For more details see the :c:func:`select()` manual page.
  84
  85 Return Value
  86 ============
  87
  88 On success, :c:func:`select()` returns the number of descriptors
  89 contained in the three returned descriptor sets, which will be zero if
  90 the timeout expired. On error -1 is returned, and the ``errno`` variable
  91 is set appropriately; the sets and ``timeout`` are undefined. Possible
  92 error codes are:
  93
  94 EBADF
  95     One or more of the file descriptor sets specified a file descriptor
  96     that is not open.
  97
  98 EBUSY
  99     The driver does not support multiple read or write streams and the
 100     device is already in use.
 101
 102 EFAULT
 103     The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
 104     references an inaccessible memory area.
 105
 106 EINTR
 107     The call was interrupted by a signal.
 108
 109 EINVAL
 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``.