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