1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _func-select: 4 .. _func-select:
5 5
6 ************* 6 *************
7 V4L2 select() 7 V4L2 select()
8 ************* 8 *************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 v4l2-select - Synchronous I/O multiplexing 13 v4l2-select - Synchronous I/O multiplexing
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. code-block:: c 18 .. code-block:: c
19 19
20 #include <sys/time.h> 20 #include <sys/time.h>
21 #include <sys/types.h> 21 #include <sys/types.h>
22 #include <unistd.h> 22 #include <unistd.h>
23 23
24 .. c:function:: int select( int nfds, fd_set * 24 .. c:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
25 25
26 Arguments 26 Arguments
27 ========= 27 =========
28 28
29 ``nfds`` 29 ``nfds``
30 The highest-numbered file descriptor in any 30 The highest-numbered file descriptor in any of the three sets, plus 1.
31 31
32 ``readfds`` 32 ``readfds``
33 File descriptions to be watched if a read() 33 File descriptions to be watched if a read() call won't block.
34 34
35 ``writefds`` 35 ``writefds``
36 File descriptions to be watched if a write() 36 File descriptions to be watched if a write() won't block.
37 37
38 ``exceptfds`` 38 ``exceptfds``
39 File descriptions to be watched for V4L2 eve 39 File descriptions to be watched for V4L2 events.
40 40
41 ``timeout`` 41 ``timeout``
42 Maximum time to wait. 42 Maximum time to wait.
43 43
44 Description 44 Description
45 =========== 45 ===========
46 46
47 With the :c:func:`select()` function applicati 47 With the :c:func:`select()` function applications can suspend
48 execution until the driver has captured data o 48 execution until the driver has captured data or is ready to accept data
49 for output. 49 for output.
50 50
51 When streaming I/O has been negotiated this fu 51 When streaming I/O has been negotiated this function waits until a
52 buffer has been filled or displayed and can be 52 buffer has been filled or displayed and can be dequeued with the
53 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When 53 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
54 the outgoing queue of the driver the function 54 the outgoing queue of the driver the function returns immediately.
55 55
56 On success :c:func:`select()` returns the tota 56 On success :c:func:`select()` returns the total number of bits set in
57 ``fd_set``. When the function timed out it ret 57 ``fd_set``. When the function timed out it returns
58 a value of zero. On failure it returns -1 and 58 a value of zero. On failure it returns -1 and the ``errno`` variable is
59 set appropriately. When the application did no 59 set appropriately. When the application did not call
60 :ref:`VIDIOC_QBUF` or 60 :ref:`VIDIOC_QBUF` or
61 :ref:`VIDIOC_STREAMON` yet the :c:func:`select 61 :ref:`VIDIOC_STREAMON` yet the :c:func:`select()`
62 function succeeds, setting the bit of the file 62 function succeeds, setting the bit of the file descriptor in ``readfds``
63 or ``writefds``, but subsequent :ref:`VIDIOC_D 63 or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
64 calls will fail. [#f1]_ 64 calls will fail. [#f1]_
65 65
66 When use of the :c:func:`read()` function has 66 When use of the :c:func:`read()` function has been negotiated and the
67 driver does not capture yet, the :c:func:`sele 67 driver does not capture yet, the :c:func:`select()` function starts
68 capturing. When that fails, :c:func:`select()` 68 capturing. When that fails, :c:func:`select()` returns successful and
69 a subsequent :c:func:`read()` call, which also 69 a subsequent :c:func:`read()` call, which also attempts to start
70 capturing, will return an appropriate error co 70 capturing, will return an appropriate error code. When the driver
71 captures continuously (as opposed to, for exam 71 captures continuously (as opposed to, for example, still images) and
72 data is already available the :c:func:`select( 72 data is already available the :c:func:`select()` function returns
73 immediately. 73 immediately.
74 74
75 When use of the :c:func:`write()` function has 75 When use of the :c:func:`write()` function has been negotiated the
76 :c:func:`select()` function just waits until t 76 :c:func:`select()` function just waits until the driver is ready for a
77 non-blocking :c:func:`write()` call. 77 non-blocking :c:func:`write()` call.
78 78
79 All drivers implementing the :c:func:`read()` 79 All drivers implementing the :c:func:`read()` or :c:func:`write()`
80 function or streaming I/O must also support th 80 function or streaming I/O must also support the :c:func:`select()`
81 function. 81 function.
82 82
83 For more details see the :c:func:`select()` ma 83 For more details see the :c:func:`select()` manual page.
84 84
85 Return Value 85 Return Value
86 ============ 86 ============
87 87
88 On success, :c:func:`select()` returns the num 88 On success, :c:func:`select()` returns the number of descriptors
89 contained in the three returned descriptor set 89 contained in the three returned descriptor sets, which will be zero if
90 the timeout expired. On error -1 is returned, 90 the timeout expired. On error -1 is returned, and the ``errno`` variable
91 is set appropriately; the sets and ``timeout`` 91 is set appropriately; the sets and ``timeout`` are undefined. Possible
92 error codes are: 92 error codes are:
93 93
94 EBADF 94 EBADF
95 One or more of the file descriptor sets sp 95 One or more of the file descriptor sets specified a file descriptor
96 that is not open. 96 that is not open.
97 97
98 EBUSY 98 EBUSY
99 The driver does not support multiple read 99 The driver does not support multiple read or write streams and the
100 device is already in use. 100 device is already in use.
101 101
102 EFAULT 102 EFAULT
103 The ``readfds``, ``writefds``, ``exceptfds 103 The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
104 references an inaccessible memory area. 104 references an inaccessible memory area.
105 105
106 EINTR 106 EINTR
107 The call was interrupted by a signal. 107 The call was interrupted by a signal.
108 108
109 EINVAL 109 EINVAL
110 The ``nfds`` argument is less than zero or 110 The ``nfds`` argument is less than zero or greater than
111 ``FD_SETSIZE``. 111 ``FD_SETSIZE``.
112 112
113 .. [#f1] 113 .. [#f1]
114 The Linux kernel implements :c:func:`select 114 The Linux kernel implements :c:func:`select()` like the
115 :c:func:`poll()` function, but :c:func:`sel 115 :c:func:`poll()` function, but :c:func:`select()` cannot
116 return a ``POLLERR``. 116 return a ``POLLERR``.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.