1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 .. c:namespace:: V4L 3 4 .. _func-poll: 5 6 *********** 7 V4L2 poll() 8 *********** 9 10 Name 11 ==== 12 13 v4l2-poll - Wait for some event on a file descriptor 14 15 Synopsis 16 ======== 17 18 .. code-block:: c 19 20 #include <sys/poll.h> 21 22 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) 23 24 Arguments 25 ========= 26 27 28 Description 29 =========== 30 31 With the :c:func:`poll()` function applications can suspend execution 32 until the driver has captured data or is ready to accept data for 33 output. 34 35 When streaming I/O has been negotiated this function waits until a 36 buffer has been filled by the capture device and can be dequeued with 37 the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this 38 function waits until the device is ready to accept a new buffer to be 39 queued up with the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl for 40 display. When buffers are already in the outgoing queue of the driver 41 (capture) or the incoming queue isn't full (display) the function 42 returns immediately. 43 44 On success :c:func:`poll()` returns the number of file descriptors 45 that have been selected (that is, file descriptors for which the 46 ``revents`` field of the respective ``struct pollfd`` structure 47 is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM`` 48 flags in the ``revents`` field, output devices the ``POLLOUT`` and 49 ``POLLWRNORM`` flags. When the function timed out it returns a value of 50 zero, on failure it returns -1 and the ``errno`` variable is set 51 appropriately. When the application did not call 52 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()` 53 function succeeds, but sets the ``POLLERR`` flag in the ``revents`` 54 field. When the application has called 55 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but 56 hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the 57 :c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in 58 the ``revents`` field. For output devices this same situation will cause 59 :c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and 60 ``POLLWRNORM`` flags in the ``revents`` field. 61 62 If an event occurred (see :ref:`VIDIOC_DQEVENT`) 63 then ``POLLPRI`` will be set in the ``revents`` field and 64 :c:func:`poll()` will return. 65 66 When use of the :c:func:`read()` function has been negotiated and the 67 driver does not capture yet, the :c:func:`poll()` function starts 68 capturing. When that fails it returns a ``POLLERR`` as above. Otherwise 69 it waits until data has been captured and can be read. When the driver 70 captures continuously (as opposed to, for example, still images) the 71 function may return immediately. 72 73 When use of the :c:func:`write()` function has been negotiated and the 74 driver does not stream yet, the :c:func:`poll()` function starts 75 streaming. When that fails it returns a ``POLLERR`` as above. Otherwise 76 it waits until the driver is ready for a non-blocking 77 :c:func:`write()` call. 78 79 If the caller is only interested in events (just ``POLLPRI`` is set in 80 the ``events`` field), then :c:func:`poll()` will *not* start 81 streaming if the driver does not stream yet. This makes it possible to 82 just poll for events and not for buffers. 83 84 All drivers implementing the :c:func:`read()` or :c:func:`write()` 85 function or streaming I/O must also support the :c:func:`poll()` 86 function. 87 88 For more details see the :c:func:`poll()` manual page. 89 90 Return Value 91 ============ 92 93 On success, :c:func:`poll()` returns the number structures which have 94 non-zero ``revents`` fields, or zero if the call timed out. On error -1 95 is returned, and the ``errno`` variable is set appropriately: 96 97 EBADF 98 One or more of the ``ufds`` members specify an invalid file 99 descriptor. 100 101 EBUSY 102 The driver does not support multiple read or write streams and the 103 device is already in use. 104 105 EFAULT 106 ``ufds`` references an inaccessible memory area. 107 108 EINTR 109 The call was interrupted by a signal. 110 111 EINVAL 112 The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use 113 ``getrlimit()`` to obtain this value.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.