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