8.66. V4L2 poll()¶
8.66.1. Name¶
v4l2-poll - Wait for some event on a file descriptor
8.66.2. Synopsis¶
#include <sys/poll.h>
-
int
poll
(struct pollfd *ufds, unsigned int nfds, int timeout)¶
8.66.3. Arguments¶
8.66.4. Description¶
With the poll() function applications can suspend execution until the driver has captured data or is ready to accept data for output.
When streaming I/O has been negotiated this function waits until a buffer has been filled by the capture device and can be dequeued with the VIDIOC_DQBUF ioctl. For output devices this function waits until the device is ready to accept a new buffer to be queued up with the ioctl VIDIOC_QBUF, VIDIOC_DQBUF ioctl for display. When buffers are already in the outgoing queue of the driver (capture) or the incoming queue isn’t full (display) the function returns immediately.
On success poll() returns the number of file descriptors
that have been selected (that is, file descriptors for which the
revents
field of the respective struct pollfd()
structure
is non-zero). Capture devices set the POLLIN
and POLLRDNORM
flags in the revents
field, output devices the POLLOUT
and
POLLWRNORM
flags. When the function timed out it returns a value of
zero, on failure it returns -1 and the errno
variable is set
appropriately. When the application did not call
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF the poll()
function succeeds, but sets the POLLERR
flag in the revents
field. When the application has called
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF for a capture device but
hasn’t yet called ioctl VIDIOC_QBUF, VIDIOC_DQBUF, the
poll() function succeeds and sets the POLLERR
flag in
the revents
field. For output devices this same situation will cause
poll() to succeed as well, but it sets the POLLOUT
and
POLLWRNORM
flags in the revents
field.
If an event occurred (see ioctl VIDIOC_DQEVENT)
then POLLPRI
will be set in the revents
field and
poll() will return.
When use of the read() function has been negotiated and the
driver does not capture yet, the poll() function starts
capturing. When that fails it returns a POLLERR
as above. Otherwise
it waits until data has been captured and can be read. When the driver
captures continuously (as opposed to, for example, still images) the
function may return immediately.
When use of the write() function has been negotiated and the
driver does not stream yet, the poll() function starts
streaming. When that fails it returns a POLLERR
as above. Otherwise
it waits until the driver is ready for a non-blocking
write() call.
If the caller is only interested in events (just POLLPRI
is set in
the events
field), then poll() will not start
streaming if the driver does not stream yet. This makes it possible to
just poll for events and not for buffers.
All drivers implementing the read() or write() function or streaming I/O must also support the poll() function.
For more details see the poll() manual page.
8.66.5. Return Value¶
On success, poll() returns the number structures which have
non-zero revents
fields, or zero if the call timed out. On error -1
is returned, and the errno
variable is set appropriately:
- EBADF
- One or more of the
ufds
members specify an invalid file descriptor. - EBUSY
- The driver does not support multiple read or write streams and the device is already in use.
- EFAULT
ufds
references an inaccessible memory area.- EINTR
- The call was interrupted by a signal.
- EINVAL
- The
nfds
argument is greater thanOPEN_MAX
.