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