georg Fri Jan 4 17:19:25 2002 EDT
Modified files:
/phpdoc/en/functions dio.xml
Log:
documented dio-functions
still open: dio_fnctl (cmd params)
Index: phpdoc/en/functions/dio.xml
diff -u phpdoc/en/functions/dio.xml:1.4 phpdoc/en/functions/dio.xml:1.5
--- phpdoc/en/functions/dio.xml:1.4 Sat Dec 15 09:34:49 2001
+++ phpdoc/en/functions/dio.xml Fri Jan 4 17:19:25 2002
@@ -1,20 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<reference id="ref.dio">
<title>Direct IO functions</title>
<titleabbrev>DIO functions</titleabbrev>
<partintro>
- <para>
- Undocumented
- </para>
+ <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>Open a new filename with specified permissions of flags and creation
permissions of mode </refpurpose>
+ <refpurpose>Opens a new filename with specified permissions of flags and creation
+permissions of mode </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -29,7 +40,32 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>dio_open</function> opens a file and returns a new
+ file descriptor for it, or -1 if any error occured.
+ 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>
@@ -37,7 +73,7 @@
<refentry id="function.dio-read">
<refnamediv>
<refname>dio_read</refname>
- <refpurpose>Read n bytes from fd and return them, if n is not specified, read 1k
</refpurpose>
+ <refpurpose>Reads n bytes from fd and returns them, if n is not specified, reads
+1k block</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -51,7 +87,11 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ 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>
@@ -59,7 +99,7 @@
<refentry id="function.dio-write">
<refnamediv>
<refname>dio_write</refname>
- <refpurpose>Write data to fd with optional truncation at length </refpurpose>
+ <refpurpose>Writes data to fd with optional truncation at length </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -74,7 +114,14 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ 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>
@@ -82,7 +129,7 @@
<refentry id="function.dio-truncate">
<refnamediv>
<refname>dio_truncate</refname>
- <refpurpose>Truncate file descriptor fd to offset bytes </refpurpose>
+ <refpurpose>Truncates file descriptor fd to offset bytes </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -94,7 +141,14 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ 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>
@@ -102,7 +156,7 @@
<refentry id="function.dio-stat">
<refnamediv>
<refname>dio_stat</refname>
- <refpurpose>Get stat information about the file descriptor fd </refpurpose>
+ <refpurpose>Gets stat information about the file descriptor fd </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -113,7 +167,28 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ Function <function>fstat</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>
@@ -121,7 +196,7 @@
<refentry id="function.dio-seek">
<refnamediv>
<refname>dio_seek</refname>
- <refpurpose>Seek to pos on fd from whence </refpurpose>
+ <refpurpose>Seeks to pos on fd from whence </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -134,7 +209,26 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ 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>
@@ -157,7 +251,17 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ 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>cmd</parameter> can be one of the following
+ operations:
+ </para>
+ <para>
+ cmd parameters still undocumented.
</para>
</refsect1>
</refentry>
@@ -165,7 +269,7 @@
<refentry id="function.dio-close">
<refnamediv>
<refname>dio_close</refname>
- <refpurpose>Close the file descriptor given by fd </refpurpose>
+ <refpurpose>Closes the file descriptor given by fd </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -176,7 +280,8 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ The function <function>dio_close</function> closes the
+ filedescriptor <parameter>resource</parameter>.
</para>
</refsect1>
</refentry>
