dio-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.dio-open" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>dio_open</refname>
  <refpurpose>
   Opens a file (creating it if necessary) at a lower level than the
   C library input/ouput stream functions allow
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>dio_open</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam><type>int</type><parameter>flags</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
  <para>
   <function>dio_open</function> opens a file and returns a new file
   descriptor for it.  
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       The pathname of the file to open.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       The <parameter>flags</parameter> parameter is a bitwise-ORed
       value comprising flags from the following list. This value
       <emphasis>must</emphasis> include one of
       <constant>O_RDONLY</constant>, <constant>O_WRONLY</constant>,
       or <constant>O_RDWR</constant>. Additionally, it may include
       any combination of the other flags from this list.
       <itemizedlist>
        <listitem>
         <para>
          <constant>O_RDONLY</constant> - opens the file for read access.
         </para>
        </listitem>
        <listitem>
         <para>
          <constant>O_WRONLY</constant> - opens the file for write access.
         </para>
        </listitem>
        <listitem>
         <para>
          <constant>O_RDWR</constant> - opens the file for both reading and
          writing.
         </para>
        </listitem>
        <listitem>
         <para>
          <constant>O_CREAT</constant> - creates the file, if it doesn't
          already exist.
         </para>
        </listitem> 
        <listitem>
         <para>
          <constant>O_EXCL</constant> - if both <constant>O_CREAT</constant>
          and <constant>O_EXCL</constant> are set and the file already
          exists, <function>dio_open</function> will fail.
         </para>
        </listitem> 
        <listitem>
         <para>
          <constant>O_TRUNC</constant> - if the file exists and is opened 
          for write access, the file will be truncated to zero length.
         </para>
        </listitem>
        <listitem>
         <para>
          <constant>O_APPEND</constant> - write operations write data at the
          end of the file.
         </para>
        </listitem>
        <listitem>
         <para>
          <constant>O_NONBLOCK</constant> - sets non blocking mode.
         </para>
        </listitem>
        <listitem>
         <para>
          <constant>O_NOCTTY</constant> - prevent the OS from
          assigning the opened file as the process's controlling
          terminal when opening a TTY device file.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       If <parameter>flags</parameter> contains
       <constant>O_CREAT</constant>, <parameter>mode</parameter> will
       set the permissions of the file (creation
       permissions). <parameter>mode</parameter> is required for
       correct operation when <constant>O_CREAT</constant> is
       specified in <parameter>flags</parameter> and is ignored
       otherwise.
      </para>
      <para>
       The actual permissions assigned to the created file will be
       affected by the process's <emphasis>umask</emphasis> setting as
       per usual.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   A file descriptor or &false; on error.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Opening a file descriptor</title>
   <programlisting role="php">
<![CDATA[
<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_close($fd);
?>
]]>
   </programlisting>
  </example>    
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>dio_close</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->