0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _func-poll:
0005
0006 ***********
0007 V4L2 poll()
0008 ***********
0009
0010 Name
0011 ====
0012
0013 v4l2-poll - Wait for some event on a file descriptor
0014
0015 Synopsis
0016 ========
0017
0018 .. code-block:: c
0019
0020 #include <sys/poll.h>
0021
0022 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
0023
0024 Arguments
0025 =========
0026
0027
0028 Description
0029 ===========
0030
0031 With the :c:func:`poll()` function applications can suspend execution
0032 until the driver has captured data or is ready to accept data for
0033 output.
0034
0035 When streaming I/O has been negotiated this function waits until a
0036 buffer has been filled by the capture device and can be dequeued with
0037 the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this
0038 function waits until the device is ready to accept a new buffer to be
0039 queued up with the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl for
0040 display. When buffers are already in the outgoing queue of the driver
0041 (capture) or the incoming queue isn't full (display) the function
0042 returns immediately.
0043
0044 On success :c:func:`poll()` returns the number of file descriptors
0045 that have been selected (that is, file descriptors for which the
0046 ``revents`` field of the respective ``struct pollfd`` structure
0047 is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
0048 flags in the ``revents`` field, output devices the ``POLLOUT`` and
0049 ``POLLWRNORM`` flags. When the function timed out it returns a value of
0050 zero, on failure it returns -1 and the ``errno`` variable is set
0051 appropriately. When the application did not call
0052 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :c:func:`poll()`
0053 function succeeds, but sets the ``POLLERR`` flag in the ``revents``
0054 field. When the application has called
0055 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but
0056 hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the
0057 :c:func:`poll()` function succeeds and sets the ``POLLERR`` flag in
0058 the ``revents`` field. For output devices this same situation will cause
0059 :c:func:`poll()` to succeed as well, but it sets the ``POLLOUT`` and
0060 ``POLLWRNORM`` flags in the ``revents`` field.
0061
0062 If an event occurred (see :ref:`VIDIOC_DQEVENT`)
0063 then ``POLLPRI`` will be set in the ``revents`` field and
0064 :c:func:`poll()` will return.
0065
0066 When use of the :c:func:`read()` function has been negotiated and the
0067 driver does not capture yet, the :c:func:`poll()` function starts
0068 capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
0069 it waits until data has been captured and can be read. When the driver
0070 captures continuously (as opposed to, for example, still images) the
0071 function may return immediately.
0072
0073 When use of the :c:func:`write()` function has been negotiated and the
0074 driver does not stream yet, the :c:func:`poll()` function starts
0075 streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
0076 it waits until the driver is ready for a non-blocking
0077 :c:func:`write()` call.
0078
0079 If the caller is only interested in events (just ``POLLPRI`` is set in
0080 the ``events`` field), then :c:func:`poll()` will *not* start
0081 streaming if the driver does not stream yet. This makes it possible to
0082 just poll for events and not for buffers.
0083
0084 All drivers implementing the :c:func:`read()` or :c:func:`write()`
0085 function or streaming I/O must also support the :c:func:`poll()`
0086 function.
0087
0088 For more details see the :c:func:`poll()` manual page.
0089
0090 Return Value
0091 ============
0092
0093 On success, :c:func:`poll()` returns the number structures which have
0094 non-zero ``revents`` fields, or zero if the call timed out. On error -1
0095 is returned, and the ``errno`` variable is set appropriately:
0096
0097 EBADF
0098 One or more of the ``ufds`` members specify an invalid file
0099 descriptor.
0100
0101 EBUSY
0102 The driver does not support multiple read or write streams and the
0103 device is already in use.
0104
0105 EFAULT
0106 ``ufds`` references an inaccessible memory area.
0107
0108 EINTR
0109 The call was interrupted by a signal.
0110
0111 EINVAL
0112 The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
0113 ``getrlimit()`` to obtain this value.
