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