Documentation/DocBook/media/v4l/cec-func-poll.xml

   1 <refentry id="cec-func-poll">
   2   <refmeta>
   3     <refentrytitle>cec poll()</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>cec-poll</refname>
   9     <refpurpose>Wait for some event on a file descriptor</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcsynopsisinfo>#include &lt;sys/poll.h&gt;</funcsynopsisinfo>
  15       <funcprototype>
  16         <funcdef>int <function>poll</function></funcdef>
  17         <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
  18         <paramdef>unsigned int <parameter>nfds</parameter></paramdef>
  19         <paramdef>int <parameter>timeout</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Description</title>
  26
  27     <para>
  28       Note: this documents the proposed CEC API. This API is not yet finalized and
  29       is currently only available as a staging kernel module.
  30     </para>
  31
  32     <para>With the <function>poll()</function> function applications
  33 can wait for CEC events.</para>
  34
  35     <para>On success <function>poll()</function> returns the number of
  36 file descriptors that have been selected (that is, file descriptors
  37 for which the <structfield>revents</structfield> field of the
  38 respective <structname>pollfd</structname> structure is non-zero).
  39 CEC devices set the <constant>POLLIN</constant> and
  40 <constant>POLLRDNORM</constant> flags in the
  41 <structfield>revents</structfield> field if there are messages in the
  42 receive queue. If the transmit queue has room for new messages, the
  43 <constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
  44 flags are set. If there are events in the event queue, then the
  45 <constant>POLLPRI</constant> flag is set.
  46 When the function timed out it returns a value of zero, on
  47 failure it returns <returnvalue>-1</returnvalue> and the
  48 <varname>errno</varname> variable is set appropriately.
  49 </para>
  50
  51     <para>For more details see the
  52 <function>poll()</function> manual page.</para>
  53   </refsect1>
  54
  55   <refsect1>
  56     <title>Return Value</title>
  57
  58     <para>On success, <function>poll()</function> returns the number
  59 structures which have non-zero <structfield>revents</structfield>
  60 fields, or zero if the call timed out. On error
  61 <returnvalue>-1</returnvalue> is returned, and the
  62 <varname>errno</varname> variable is set appropriately:</para>
  63
  64     <variablelist>
  65       <varlistentry>
  66         <term><errorcode>EBADF</errorcode></term>
  67         <listitem>
  68           <para>One or more of the <parameter>ufds</parameter> members
  69 specify an invalid file descriptor.</para>
  70         </listitem>
  71       </varlistentry>
  72       <varlistentry>
  73         <term><errorcode>EFAULT</errorcode></term>
  74         <listitem>
  75           <para><parameter>ufds</parameter> references an inaccessible
  76 memory area.</para>
  77         </listitem>
  78       </varlistentry>
  79       <varlistentry>
  80         <term><errorcode>EINTR</errorcode></term>
  81         <listitem>
  82           <para>The call was interrupted by a signal.</para>
  83         </listitem>
  84       </varlistentry>
  85       <varlistentry>
  86         <term><errorcode>EINVAL</errorcode></term>
  87         <listitem>
  88           <para>The <parameter>nfds</parameter> argument is greater
  89 than <constant>OPEN_MAX</constant>.</para>
  90         </listitem>
  91       </varlistentry>
  92     </variablelist>
  93   </refsect1>
  94 </refentry>