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