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