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/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
19 v4l2-poll - Wait for some event on a file descriptor
30 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
41 With the :ref:`poll() <func-poll>` function applications can suspend execution
42 until the driver has captured data or is ready to accept data for
45 When streaming I/O has been negotiated this function waits until a
46 buffer has been filled by the capture device and can be dequeued with
47 the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this
48 function waits until the device is ready to accept a new buffer to be
49 queued up with the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl for
50 display. When buffers are already in the outgoing queue of the driver
51 (capture) or the incoming queue isn't full (display) the function
54 On success :ref:`poll() <func-poll>` returns the number of file descriptors
55 that have been selected (that is, file descriptors for which the
56 ``revents`` field of the respective :c:func:`struct pollfd` structure
57 is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
58 flags in the ``revents`` field, output devices the ``POLLOUT`` and
59 ``POLLWRNORM`` flags. When the function timed out it returns a value of
60 zero, on failure it returns -1 and the ``errno`` variable is set
61 appropriately. When the application did not call
62 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` the :ref:`poll() <func-poll>`
63 function succeeds, but sets the ``POLLERR`` flag in the ``revents``
64 field. When the application has called
65 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` for a capture device but
66 hasn't yet called :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, the
67 :ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in
68 the ``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.
72 If an event occurred (see :ref:`VIDIOC_DQEVENT`)
73 then ``POLLPRI`` will be set in the ``revents`` field and
74 :ref:`poll() <func-poll>` will return.
76 When use of the :ref:`read() <func-read>` function has been negotiated and the
77 driver does not capture yet, the :ref:`poll() <func-poll>` function starts
78 capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
79 it waits until data has been captured and can be read. When the driver
80 captures continuously (as opposed to, for example, still images) the
81 function may return immediately.
83 When use of the :ref:`write() <func-write>` function has been negotiated and the
84 driver does not stream yet, the :ref:`poll() <func-poll>` function starts
85 streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
86 it waits until the driver is ready for a non-blocking
87 :ref:`write() <func-write>` call.
89 If the caller is only interested in events (just ``POLLPRI`` is set in
90 the ``events`` field), then :ref:`poll() <func-poll>` will *not* start
91 streaming if the driver does not stream yet. This makes it possible to
92 just poll for events and not for buffers.
94 All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
95 function or streaming I/O must also support the :ref:`poll() <func-poll>`
98 For more details see the :ref:`poll() <func-poll>` manual page.
104 On success, :ref:`poll() <func-poll>` returns the number structures which have
105 non-zero ``revents`` fields, or zero if the call timed out. On error -1
106 is returned, and the ``errno`` variable is set appropriately:
109 One or more of the ``ufds`` members specify an invalid file
113 The driver does not support multiple read or write streams and the
114 device is already in use.
117 ``ufds`` references an inaccessible memory area.
120 The call was interrupted by a signal.
123 The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
124 ``getrlimit()`` to obtain this value.