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