documented dio-functions

still open: dio_fnctl (cmd params)


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@66932 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Georg Richter 2002-01-04 22:19:25 +00:00
parent a60496af1c
commit 798e9d2a6b

View file

@ -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>