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