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

   1 <refentry id="cec-func-open">
   2   <refmeta>
   3     <refentrytitle>cec open()</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>cec-open</refname>
   9     <refpurpose>Open a cec device</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
  15       <funcprototype>
  16         <funcdef>int <function>open</function></funcdef>
  17         <paramdef>const char *<parameter>device_name</parameter></paramdef>
  18         <paramdef>int <parameter>flags</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>device_name</parameter></term>
  29         <listitem>
  30           <para>Device to be opened.</para>
  31         </listitem>
  32       </varlistentry>
  33       <varlistentry>
  34         <term><parameter>flags</parameter></term>
  35         <listitem>
  36           <para>Open flags. Access mode must be <constant>O_RDWR</constant>.
  37           </para>
  38           <para>When the <constant>O_NONBLOCK</constant> flag is
  39 given, the &CEC-RECEIVE; ioctl will return &EAGAIN; when no message is
  40 available, and the &CEC-TRANSMIT;, &CEC-ADAP-S-PHYS-ADDR; and
  41 &CEC-ADAP-S-LOG-ADDRS; ioctls all act in non-blocking mode.</para>
  42           <para>Other flags have no effect.</para>
  43         </listitem>
  44       </varlistentry>
  45     </variablelist>
  46   </refsect1>
  47   <refsect1>
  48     <title>Description</title>
  49     <para>
  50       Note: this documents the proposed CEC API. This API is not yet finalized and
  51       is currently only available as a staging kernel module.
  52     </para>
  53
  54     <para>To open a cec device applications call <function>open()</function>
  55     with the desired device name. The function has no side effects; the device
  56     configuration remain unchanged.</para>
  57     <para>When the device is opened in read-only mode, attempts to modify its
  58     configuration will result in an error, and <varname>errno</varname> will be
  59     set to <errorcode>EBADF</errorcode>.</para>
  60   </refsect1>
  61   <refsect1>
  62     <title>Return Value</title>
  63
  64     <para><function>open</function> returns the new file descriptor on success.
  65     On error, -1 is returned, and <varname>errno</varname> is set appropriately.
  66     Possible error codes include:</para>
  67
  68     <variablelist>
  69       <varlistentry>
  70         <term><errorcode>EACCES</errorcode></term>
  71         <listitem>
  72           <para>The requested access to the file is not allowed.</para>
  73         </listitem>
  74       </varlistentry>
  75       <varlistentry>
  76         <term><errorcode>EMFILE</errorcode></term>
  77         <listitem>
  78           <para>The  process  already  has  the  maximum number of files open.
  79           </para>
  80         </listitem>
  81       </varlistentry>
  82       <varlistentry>
  83         <term><errorcode>ENFILE</errorcode></term>
  84         <listitem>
  85           <para>The system limit on the total number of open files has been
  86           reached.</para>
  87         </listitem>
  88       </varlistentry>
  89       <varlistentry>
  90         <term><errorcode>ENOMEM</errorcode></term>
  91         <listitem>
  92           <para>Insufficient kernel memory was available.</para>
  93         </listitem>
  94       </varlistentry>
  95       <varlistentry>
  96         <term><errorcode>ENXIO</errorcode></term>
  97         <listitem>
  98           <para>No device corresponding to this device special file exists.
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102     </variablelist>
 103   </refsect1>
 104 </refentry>