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