0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _func-select:
0005
0006 *************
0007 V4L2 select()
0008 *************
0009
0010 Name
0011 ====
0012
0013 v4l2-select - Synchronous I/O multiplexing
0014
0015 Synopsis
0016 ========
0017
0018 .. code-block:: c
0019
0020 #include <sys/time.h>
0021 #include <sys/types.h>
0022 #include <unistd.h>
0023
0024 .. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
0025
0026 Arguments
0027 =========
0028
0029 ``nfds``
0030 The highest-numbered file descriptor in any of the three sets, plus 1.
0031
0032 ``readfds``
0033 File descriptions to be watched if a read() call won't block.
0034
0035 ``writefds``
0036 File descriptions to be watched if a write() won't block.
0037
0038 ``exceptfds``
0039 File descriptions to be watched for V4L2 events.
0040
0041 ``timeout``
0042 Maximum time to wait.
0043
0044 Description
0045 ===========
0046
0047 With the :c:func:`select()` function applications can suspend
0048 execution until the driver has captured data or is ready to accept data
0049 for output.
0050
0051 When streaming I/O has been negotiated this function waits until a
0052 buffer has been filled or displayed and can be dequeued with the
0053 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
0054 the outgoing queue of the driver the function returns immediately.
0055
0056 On success :c:func:`select()` returns the total number of bits set in
0057 ``fd_set``. When the function timed out it returns
0058 a value of zero. On failure it returns -1 and the ``errno`` variable is
0059 set appropriately. When the application did not call
0060 :ref:`VIDIOC_QBUF` or
0061 :ref:`VIDIOC_STREAMON` yet the :c:func:`select()`
0062 function succeeds, setting the bit of the file descriptor in ``readfds``
0063 or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
0064 calls will fail. [#f1]_
0065
0066 When use of the :c:func:`read()` function has been negotiated and the
0067 driver does not capture yet, the :c:func:`select()` function starts
0068 capturing. When that fails, :c:func:`select()` returns successful and
0069 a subsequent :c:func:`read()` call, which also attempts to start
0070 capturing, will return an appropriate error code. When the driver
0071 captures continuously (as opposed to, for example, still images) and
0072 data is already available the :c:func:`select()` function returns
0073 immediately.
0074
0075 When use of the :c:func:`write()` function has been negotiated the
0076 :c:func:`select()` function just waits until the driver is ready for a
0077 non-blocking :c:func:`write()` call.
0078
0079 All drivers implementing the :c:func:`read()` or :c:func:`write()`
0080 function or streaming I/O must also support the :c:func:`select()`
0081 function.
0082
0083 For more details see the :c:func:`select()` manual page.
0084
0085 Return Value
0086 ============
0087
0088 On success, :c:func:`select()` returns the number of descriptors
0089 contained in the three returned descriptor sets, which will be zero if
0090 the timeout expired. On error -1 is returned, and the ``errno`` variable
0091 is set appropriately; the sets and ``timeout`` are undefined. Possible
0092 error codes are:
0093
0094 EBADF
0095 One or more of the file descriptor sets specified a file descriptor
0096 that is not open.
0097
0098 EBUSY
0099 The driver does not support multiple read or write streams and the
0100 device is already in use.
0101
0102 EFAULT
0103 The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
0104 references an inaccessible memory area.
0105
0106 EINTR
0107 The call was interrupted by a signal.
0108
0109 EINVAL
0110 The ``nfds`` argument is less than zero or greater than
0111 ``FD_SETSIZE``.
0112
0113 .. [#f1]
0114 The Linux kernel implements :c:func:`select()` like the
0115 :c:func:`poll()` function, but :c:func:`select()` cannot
0116 return a ``POLLERR``.
