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