117 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _func-select:5 6*************7V4L2 select()8*************9 10Name11====12 13v4l2-select - Synchronous I/O multiplexing14 15Synopsis16========17 18.. code-block:: c19 20 #include <sys/time.h>21 #include <sys/types.h>22 #include <unistd.h>23 24.. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )25 26Arguments27=========28 29``nfds``30 The highest-numbered file descriptor in any of the three sets, plus 1.31 32``readfds``33 File descriptions to be watched if a read() call won't block.34 35``writefds``36 File descriptions to be watched if a write() won't block.37 38``exceptfds``39 File descriptions to be watched for V4L2 events.40 41``timeout``42 Maximum time to wait.43 44Description45===========46 47With the :c:func:`select()` function applications can suspend48execution until the driver has captured data or is ready to accept data49for output.50 51When streaming I/O has been negotiated this function waits until a52buffer has been filled or displayed and can be dequeued with the53:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in54the outgoing queue of the driver the function returns immediately.55 56On success :c:func:`select()` returns the total number of bits set in57``fd_set``. When the function timed out it returns58a value of zero. On failure it returns -1 and the ``errno`` variable is59set appropriately. When the application did not call60:ref:`VIDIOC_QBUF` or61:ref:`VIDIOC_STREAMON` yet the :c:func:`select()`62function succeeds, setting the bit of the file descriptor in ``readfds``63or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`64calls will fail. [#f1]_65 66When use of the :c:func:`read()` function has been negotiated and the67driver does not capture yet, the :c:func:`select()` function starts68capturing. When that fails, :c:func:`select()` returns successful and69a subsequent :c:func:`read()` call, which also attempts to start70capturing, will return an appropriate error code. When the driver71captures continuously (as opposed to, for example, still images) and72data is already available the :c:func:`select()` function returns73immediately.74 75When use of the :c:func:`write()` function has been negotiated the76:c:func:`select()` function just waits until the driver is ready for a77non-blocking :c:func:`write()` call.78 79All drivers implementing the :c:func:`read()` or :c:func:`write()`80function or streaming I/O must also support the :c:func:`select()`81function.82 83For more details see the :c:func:`select()` manual page.84 85Return Value86============87 88On success, :c:func:`select()` returns the number of descriptors89contained in the three returned descriptor sets, which will be zero if90the timeout expired. On error -1 is returned, and the ``errno`` variable91is set appropriately; the sets and ``timeout`` are undefined. Possible92error codes are:93 94EBADF95 One or more of the file descriptor sets specified a file descriptor96 that is not open.97 98EBUSY99 The driver does not support multiple read or write streams and the100 device is already in use.101 102EFAULT103 The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer104 references an inaccessible memory area.105 106EINTR107 The call was interrupted by a signal.108 109EINVAL110 The ``nfds`` argument is less than zero or greater than111 ``FD_SETSIZE``.112 113.. [#f1]114 The Linux kernel implements :c:func:`select()` like the115 :c:func:`poll()` function, but :c:func:`select()` cannot116 return a ``POLLERR``.117