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