forked from Minki/linux
c6401af669
This removes comment tags intended for emacs configuration from 67 files in the Media API DocBook. Such comments are not really helpful and violate the coding style rules. Signed-off-by: Sylwester Nawrocki <snjw23@gmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
120 lines
4.3 KiB
XML
120 lines
4.3 KiB
XML
<refentry id="func-poll">
|
|
<refmeta>
|
|
<refentrytitle>V4L2 poll()</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>v4l2-poll</refname>
|
|
<refpurpose>Wait for some event on a file descriptor</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo>
|
|
<funcprototype>
|
|
<funcdef>int <function>poll</function></funcdef>
|
|
<paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>nfds</parameter></paramdef>
|
|
<paramdef>int <parameter>timeout</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>With the <function>poll()</function> function applications
|
|
can suspend execution until the driver has captured data or is ready
|
|
to accept data for output.</para>
|
|
|
|
<para>When streaming I/O has been negotiated this function waits
|
|
until a buffer has been filled or displayed and can be dequeued with
|
|
the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
|
|
queue of the driver the function returns immediately.</para>
|
|
|
|
<para>On success <function>poll()</function> returns the number of
|
|
file descriptors that have been selected (that is, file descriptors
|
|
for which the <structfield>revents</structfield> field of the
|
|
respective <structname>pollfd</structname> structure is non-zero).
|
|
Capture devices set the <constant>POLLIN</constant> and
|
|
<constant>POLLRDNORM</constant> flags in the
|
|
<structfield>revents</structfield> field, output devices the
|
|
<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
|
|
flags. When the function timed out it returns a value of zero, on
|
|
failure it returns <returnvalue>-1</returnvalue> and the
|
|
<varname>errno</varname> variable is set appropriately. When the
|
|
application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
|
|
<function>poll()</function> function succeeds, but sets the
|
|
<constant>POLLERR</constant> flag in the
|
|
<structfield>revents</structfield> field.</para>
|
|
|
|
<para>When use of the <function>read()</function> function has
|
|
been negotiated and the driver does not capture yet, the
|
|
<function>poll</function> function starts capturing. When that fails
|
|
it returns a <constant>POLLERR</constant> 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.</para>
|
|
|
|
<para>When use of the <function>write()</function> function has
|
|
been negotiated the <function>poll</function> function just waits
|
|
until the driver is ready for a non-blocking
|
|
<function>write()</function> call.</para>
|
|
|
|
<para>All drivers implementing the <function>read()</function> or
|
|
<function>write()</function> function or streaming I/O must also
|
|
support the <function>poll()</function> function.</para>
|
|
|
|
<para>For more details see the
|
|
<function>poll()</function> manual page.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On success, <function>poll()</function> returns the number
|
|
structures which have non-zero <structfield>revents</structfield>
|
|
fields, or zero if the call timed out. On error
|
|
<returnvalue>-1</returnvalue> is returned, and the
|
|
<varname>errno</varname> variable is set appropriately:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>EBADF</errorcode></term>
|
|
<listitem>
|
|
<para>One or more of the <parameter>ufds</parameter> members
|
|
specify an invalid file descriptor.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EBUSY</errorcode></term>
|
|
<listitem>
|
|
<para>The driver does not support multiple read or write
|
|
streams and the device is already in use.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EFAULT</errorcode></term>
|
|
<listitem>
|
|
<para><parameter>ufds</parameter> references an inaccessible
|
|
memory area.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EINTR</errorcode></term>
|
|
<listitem>
|
|
<para>The call was interrupted by a signal.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EINVAL</errorcode></term>
|
|
<listitem>
|
|
<para>The <parameter>nfds</parameter> argument is greater
|
|
than <constant>OPEN_MAX</constant>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|