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