Documentation/media/uapi/v4l/func-select.rst

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