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

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