Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _func-select: | |
4 | ||
5 | ************* | |
6 | V4L2 select() | |
7 | ************* | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | v4l2-select - Synchronous I/O multiplexing |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
18 | .. code-block:: c | |
19 | ||
20 | #include <sys/time.h> | |
21 | #include <sys/types.h> | |
22 | #include <unistd.h> | |
23 | ||
24 | ||
b7e67f6c | 25 | .. cpp:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ) |
5377d91f | 26 | |
586027ce | 27 | |
15e7d615 | 28 | Arguments |
586027ce MCC |
29 | ========= |
30 | ||
31 | ||
32 | ||
15e7d615 | 33 | Description |
5377d91f MH |
34 | =========== |
35 | ||
760c7010 | 36 | With the :ref:`select() <func-select>` function applications can suspend |
5377d91f MH |
37 | execution until the driver has captured data or is ready to accept data |
38 | for output. | |
39 | ||
40 | When streaming I/O has been negotiated this function waits until a | |
41 | buffer has been filled or displayed and can be dequeued with the | |
af4a4d0d | 42 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in |
5377d91f MH |
43 | the outgoing queue of the driver the function returns immediately. |
44 | ||
760c7010 | 45 | On success :ref:`select() <func-select>` returns the total number of bits set in |
acf309a2 | 46 | :c:func:`struct fd_set`. When the function timed out it returns |
5377d91f MH |
47 | a value of zero. On failure it returns -1 and the ``errno`` variable is |
48 | set appropriately. When the application did not call | |
7347081e | 49 | :ref:`VIDIOC_QBUF` or |
760c7010 | 50 | :ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>` |
5377d91f | 51 | function succeeds, setting the bit of the file descriptor in ``readfds`` |
af4a4d0d | 52 | or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` |
4855307b | 53 | calls will fail. [#f1]_ |
5377d91f | 54 | |
760c7010 MCC |
55 | When use of the :ref:`read() <func-read>` function has been negotiated and the |
56 | driver does not capture yet, the :ref:`select() <func-select>` function starts | |
57 | capturing. When that fails, :ref:`select() <func-select>` returns successful and | |
58 | a subsequent :ref:`read() <func-read>` call, which also attempts to start | |
5377d91f MH |
59 | capturing, will return an appropriate error code. When the driver |
60 | captures continuously (as opposed to, for example, still images) and | |
760c7010 | 61 | data is already available the :ref:`select() <func-select>` function returns |
5377d91f MH |
62 | immediately. |
63 | ||
760c7010 MCC |
64 | When use of the :ref:`write() <func-write>` function has been negotiated the |
65 | :ref:`select() <func-select>` function just waits until the driver is ready for a | |
66 | non-blocking :ref:`write() <func-write>` call. | |
5377d91f | 67 | |
760c7010 MCC |
68 | All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>` |
69 | function or streaming I/O must also support the :ref:`select() <func-select>` | |
5377d91f MH |
70 | function. |
71 | ||
760c7010 | 72 | For more details see the :ref:`select() <func-select>` manual page. |
5377d91f MH |
73 | |
74 | ||
15e7d615 | 75 | Return Value |
5377d91f MH |
76 | ============ |
77 | ||
760c7010 | 78 | On success, :ref:`select() <func-select>` returns the number of descriptors |
5377d91f MH |
79 | contained in the three returned descriptor sets, which will be zero if |
80 | the timeout expired. On error -1 is returned, and the ``errno`` variable | |
81 | is set appropriately; the sets and ``timeout`` are undefined. Possible | |
82 | error codes are: | |
83 | ||
84 | EBADF | |
85 | One or more of the file descriptor sets specified a file descriptor | |
86 | that is not open. | |
87 | ||
88 | EBUSY | |
89 | The driver does not support multiple read or write streams and the | |
90 | device is already in use. | |
91 | ||
92 | EFAULT | |
93 | The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer | |
94 | references an inaccessible memory area. | |
95 | ||
96 | EINTR | |
97 | The call was interrupted by a signal. | |
98 | ||
99 | EINVAL | |
100 | The ``nfds`` argument is less than zero or greater than | |
101 | ``FD_SETSIZE``. | |
102 | ||
4855307b | 103 | .. [#f1] |
760c7010 MCC |
104 | The Linux kernel implements :ref:`select() <func-select>` like the |
105 | :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot | |
5377d91f | 106 | return a ``POLLERR``. |