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