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