mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
4c31e191c5
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@69281 c90b9560-bf6c-de11-be94-00142212c4b1
388 lines
13 KiB
XML
388 lines
13 KiB
XML
<?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:
|
|
-->
|
|
|
|
|