<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
 <reference id="ref.dio">
  <title>Direct IO functions</title>
  <titleabbrev>DIO functions</titleabbrev>

  <partintro>
   <section id="dio.intro">
    <title>Direct I/O Functions</title>
    <para>
     PHP supports the direct io functions as described in the Posix
     Standard (Section 6) for performing I/O functions at a lower
     level than the C-Language stream I/O functions (fopen, fread,..).
    </para>
   </section>
   <section id="dio.installation">
    <title>Installation</title>
    <para>
     To get these functions to work, you have to configure PHP with
     <option role="configure">--enable-dio</option>.
    </para>
   </section>
  </partintro>
 
  <refentry id="function.dio-open">
   <refnamediv>
    <refname>dio_open</refname>
    <refpurpose>
     Opens a new filename with specified permissions of flags and
     creation permissions of mode
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <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></methodparam>
     </methodsynopsis>
    <para>
     <function>dio_open</function> opens a file and returns a new file
     descriptor for it, or -1 if any error occurred.  If
     <parameter>flags</parameter> is O_CREAT, optional third parameter
     <parameter>mode</parameter> will set the mode of the file
     (creation permissions).  The <parameter>flags</parameter>
     parameter can be one of the following options:
     <itemizedlist>
      <listitem>
       <para>O_RDONLY - opens the file for read access</para>
      </listitem>
      <listitem>
       <para>O_WRONLY - opens the file for write access</para>
      </listitem>
      <listitem>
       <para>
        O_RDWR - opens the file for both reading and
        writing
       </para>
      </listitem>
     </itemizedlist>
      The <parameter>flags</parameter> parameter can also include any
      combination of the following flags:
     <itemizedlist>
      <listitem>
       <para>
        O_CREAT - creates the file, if it doesn't already exist
       </para>
      </listitem> 
      <listitem>
       <para>
        O_EXCL - if both, O_CREAT and O_EXCL are set,
        <function>dio_open</function> fails, if file already exists
       </para>
      </listitem> 
      <listitem>
       <para>
        O_TRUNC - if file exists, and its opened for write access,
        file will be truncated to zero length.
       </para>
      </listitem>
      <listitem>
       <para>
        O_APPEND - write operations write data at the
        end of file</para></listitem> <listitem><para>O_NONBLOCK -
        sets non blocking mode
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-read">
   <refnamediv>
    <refname>dio_read</refname>
    <refpurpose>
     Reads n bytes from fd and returns them, if n is not specified,
     reads 1k block
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dio_read</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>n</parameter></methodparam>
     </methodsynopsis>
    <para>
     The function <function>dio_read</function> reads and returns
     <parameter>n</parameter> bytes from file with descriptor
     <parameter>resource</parameter>. If <parameter>n</parameter> is
     not specified, <function>dio_read</function> reads 1K sized block
     and returns them.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-write">
   <refnamediv>
    <refname>dio_write</refname>
    <refpurpose>
     Writes data to fd with optional truncation at length 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dio_write</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>len</parameter></methodparam>
     </methodsynopsis>
    <para>
     The function <function>dio_write</function> writes up to
     <parameter>len</parameter> bytes from <parameter>data</parameter>
     to file <parameter>fd</parameter>. If <parameter>len</parameter>
     is not specified, <function>dio_write</function> writes all
     <parameter>data</parameter> to the specified
     file. <function>dio_write</function> returns the number of bytes
     written to <parameter>fd</parameter>.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-truncate">
   <refnamediv>
    <refname>dio_truncate</refname>
    <refpurpose>
     Truncates file descriptor fd to offset bytes 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dio_truncate</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
      <methodparam><type>int</type><parameter>offset</parameter></methodparam>
     </methodsynopsis>
    <para>
     Function <function>dio_truncate</function> causes the file
     referenced by <parameter>fd</parameter> to be truncated to at
     most <parameter>offset</parameter> bytes in size.  If the file
     previously was larger than this size, the extra data is lost. If
     the file previously was shorter, it is unspecified whether the
     file is left unchanged or is extended. In the latter case the
     extended part reads as zero bytes. Returns 0 on success,
     otherwise -1.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-stat">
   <refnamediv>
    <refname>dio_stat</refname>
    <refpurpose>
     Gets stat information about the file descriptor fd
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>dio_stat</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
     </methodsynopsis>
    <para>
     Function <function>dio_stat</function> returns information about
     the file with file descriptor
     <parameter>fd</parameter>. <function>dio_stat</function> returns
     an associative array with the following keys:
     <itemizedlist>
      <listitem><para>"device" - device</para></listitem>
      <listitem><para>"inode" - inode</para></listitem>
      <listitem><para>"mode" - mode</para></listitem>
      <listitem><para>"nlink" - number of hard links</para></listitem>
      <listitem><para>"uid" - user id</para></listitem>
      <listitem><para>"gid" - group id</para></listitem>
      <listitem>
       <para>
        "device_type" - device type (if inode device)
       </para>
      </listitem>
      <listitem><para>"size" - total size in bytes</para></listitem>
      <listitem><para>"blocksize" - blocksize</para></listitem>
      <listitem><para>"blocks" - number of blocks allocated</para></listitem>
      <listitem><para>"atime" - time of last access</para></listitem>
      <listitem><para>"mtime" - time of last modification</para></listitem>
      <listitem><para>"ctime" - time of last change</para></listitem>
     </itemizedlist>
     On error <function>dio_stat</function> returns NULL.
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-seek">
   <refnamediv>
    <refname>dio_seek</refname>
    <refpurpose>Seeks to pos on fd from whence</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dio_seek</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
      <methodparam><type>int</type><parameter>pos</parameter></methodparam>
      <methodparam><type>int</type><parameter>whence</parameter></methodparam>
     </methodsynopsis>
    <para>
     The function <function>dio_seek</function> is used to change the
     file position of the file with descriptor
     <parameter>resource</parameter>.  The parameter
     <parameter>whence</parameter> specifies how the position
     <parameter>pos</parameter> should be interpreted:
     <itemizedlist>
      <listitem>
       <para>
        SEEK_SET - specifies that <parameter>pos</parameter> is
        specified from the beginning of the file
       </para>
      </listitem>
      <listitem>
       <para>
        SEEK_CUR - Specifies that <parameter>pos</parameter> is a
        count of characters from the current file position. This count
        may be positive or negative
       </para>
      </listitem>
      <listitem>
       <para>
        SEEK_END - Specifies that <parameter>pos</parameter> is a
        count of characters from the end of the file. A negative count
        specifies a position within the current extent of the file; a
        positive count specifies a position past the current end. If
        you set the position past the current end, and actually write
        data, you will extend the file with zeros up to that
        position
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-fcntl">
   <refnamediv>
    <refname>dio_fcntl</refname>
    <refpurpose>Performs a c library fcntl on fd</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>dio_fcntl</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
      <methodparam><type>int</type><parameter>cmd</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
     </methodsynopsis>
    <para>
     The <function>dio_fcntl</function> function performs the
     operation specified by <parameter>cmd</parameter> on the file
     descriptor <parameter>fd</parameter>. Some commands require
     additional arguments <parameter>args</parameter> to be supplied.
    </para>
    <para>
     <parameter>arg</parameter> is an associative array, when
     <parameter>cmd</parameter> is F_SETLK or F_SETLLW, with the
     following keys:
     <itemizedlist>
      <listitem>
       <para>
        "start" - offset where lock begins
       </para>
      </listitem>
      <listitem>
       <para>
        "length" - size of locked area. zero means to end of file
       </para>
      </listitem>
      <listitem>
       <para>
        "wenth" - Where l_start is relative to: can be SEEK_SET,
        SEEK_END and SEEK_CUR
       </para>
      </listitem>
      <listitem>
       <para>
        "type" - type of lock: can be F_RDLCK (read lock), F_WRLCK
        (write lock) or F_UNLCK (unlock)
       </para>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     <parameter>cmd</parameter> can be one of the following
     operations:
     <itemizedlist>
      <listitem>
       <para>
        F_SETLK - Lock is set or cleared. If the lock
        is held by someone else <function>dio_fcntl</function> returns
        -1.
       </para>
      </listitem>
      <listitem>
       <para>
        F_SETLKW - like F_SETLK, but in case the lock
        is held by someone else, <function>dio_fcntl</function> waits
        until the lock is released.
       </para>
      </listitem>
      <listitem>
       <para>
        F_GETLK - <function>dio_fcntl</function> returns an
        associative array (as described above) if someone else
        prevents lock. If there is no obstruction key "type" will set
        to F_UNLCK.
       </para>
      </listitem>
      <listitem>
       <para>
        F_DUPFD - finds the lowest numbered available file descriptor
        greater or equal than <parameter>arg</parameter> and returns
        them.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>
	
  <refentry id="function.dio-close">
   <refnamediv>
    <refname>dio_close</refname>
    <refpurpose>Closes the file descriptor given by fd</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>dio_close</methodname>
      <methodparam><type>resource</type><parameter>fd</parameter></methodparam>
     </methodsynopsis>
    <para>
     The function <function>dio_close</function> closes the
     file descriptor <parameter>resource</parameter>.
    </para>
   </refsect1>
  </refentry>
	
 </reference>
 
<!-- 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:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->