wez Sat Aug 10 19:38:41 2002 EDT
Added files:
/phpdoc/en/chapters streams.common.xml streams.file.xml streams.xml
streams.constants.xml streams.structs.xml
streams.socket.xml streams.dir.xml
Modified files:
/phpdoc manual.xml.in
Log:
Add docs for streams.
Note: some wizard might need to juggle things so that it belongs in a part
of it's own or something: I'm no doc guru.
Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.131 phpdoc/manual.xml.in:1.132
--- phpdoc/manual.xml.in:1.131 Sat Aug 3 22:39:11 2002
+++ phpdoc/manual.xml.in Sat Aug 10 19:38:40 2002
@@ -198,6 +198,7 @@
</part>
&zendapi.toc;
+ &chapters.streams;
<part id="faq">
<title>&FAQ;</title>
Index: phpdoc/en/chapters/streams.common.xml
+++ phpdoc/en/chapters/streams.common.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<sect1 id="stream.common-api">
<title>Streams Common API Reference</title>
<refentry id="streams.php-stream-stat-path">
<refnamediv>
<refname>php_stream_stat_path</refname>
<refpurpose>Gets the status for a file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_stat_path</methodname>
<methodparam><type>char *</type><parameter>path</parameter></methodparam>
<methodparam><type>php_stream_statbuf
*</type><parameter>ssb</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_stat_path</function> examines the file or URL specified by
<parameter>path</parameter>
and returns information such as file size, access and creation times and so on.
The return value is 0 on success, -1 on error.
For more information about the information returned, see
<link linkend="streams.struct-php-stream-statbuf">php_stream_statbuf</link>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-stat">
<refnamediv>
<refname>php_stream_stat</refname>
<refpurpose>Gets the status for the underlying storage associated with a
stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_stat</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>php_stream_statbuf
*</type><parameter>ssb</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_stat</function> examines the storage to which
<parameter>stream</parameter>
is bound, and returns information such as file size, access and creation times
and so on.
The return value is 0 on success, -1 on error.
For more information about the information returned, see
<link linkend="streams.struct-php-stream-statbuf">php_stream_statbuf</link>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-open-wrapper">
<refnamediv>
<refname>php_stream_open_wrapper</refname>
<refpurpose>Opens a stream on a file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_open_wrapper</methodname>
<methodparam><type>char *</type><parameter>path</parameter></methodparam>
<methodparam><type>char *</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
<methodparam><type>char **</type><parameter>opened</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_open_wrapper</function> opens a stream on the file, URL or
other wrapped resource specified by <parameter>path</parameter>. Depending on
the value of <parameter>mode</parameter>, the stream may be opened for reading,
writing, appending or combinations of those. See the table below for the different
modes that can be used; in addition to the characters listed below, you may
include the character 'b' either as the second or last character in the mode
string.
The presence of the 'b' character informs the relevant stream implementation to
open the stream in a binary safe mode.
</para>
<para>
The 'b' character is ignored on all POSIX conforming systems which treat
binary and text files in the same way. It is a good idea to specify the 'b'
character whenever your stream is accessing data where the full 8 bits
are important, so that your code will work when compiled on a system
where the 'b' flag is important.
</para>
<para>
Any local files created by the streams API will have their initial permissions set
according to the operating system defaults - under UNIX based systems
this means that the umask of the process will be used. Under Windows,
the file will be owned by the creating process.
Any remote files will be created according to the URL wrapper that was
used to open the file, and the credentials supplied to the remote server.
</para>
<para>
<variablelist>
<varlistentry>
<term>
<constant>r</constant>
</term>
<listitem>
<simpara>
Open text file for reading. The stream is positioned at the beginning of
the file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>r+</constant>
</term>
<listitem>
<simpara>
Open text file for reading and writing. The stream is positioned at the
beginning of
the file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>w</constant>
</term>
<listitem>
<simpara>
Truncate the file to zero length or create text file for writing.
The stream is positioned at the beginning of the file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>w+</constant>
</term>
<listitem>
<simpara>
Open text file for reading and writing. The file is created if
it does not exist, otherwise it is truncated. The stream is positioned at
the beginning of the file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>a</constant>
</term>
<listitem>
<simpara>
Open for writing. The file is created if it does not exist.
The stream is positioned at the end of the file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>a+</constant>
</term>
<listitem>
<simpara>
Open text file for reading and writing. The file is created if
it does not exist. The stream is positioned at the end of the file.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<parameter>options</parameter> affects how the path/URL of the stream is
interpreted, safe mode checks and actions taken if there is an error during
opening
of the stream. See <link linkend="streams.options">Stream open options</link> for
more information about options.
</para>
<para>
If <parameter>opened</parameter> is not NULL, it will be set to a string
containing
the name of the actual file/resource that was opened. This is important when the
options include <constant>USE_PATH</constant>, which causes the include_path to
be searched for the
file. You, the caller, are responsible for calling <function>efree</function> on
the filename returned in this parameter.
</para>
<note>
<simpara>
If you specified <constant>STREAM_MUST_SEEK</constant> in
<parameter>options</parameter>,
the path returned in <parameter>opened</parameter> may not be the name of the
actual stream that was returned to you. It will, however, be the name of the
original
resource from which the seekable stream was manufactured.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="streams.php-stream-read">
<refnamediv>
<refname>php_stream_read</refname>
<refpurpose>Read a number of bytes from a stream into a buffer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>size_t</type><methodname>php_stream_read</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>char *</type><parameter>buf</parameter></methodparam>
<methodparam><type>size_t</type><parameter>count</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_read</function> reads up to <parameter>count</parameter>
bytes of data from <parameter>stream</parameter> and copies them into the
buffer <parameter>buf</parameter>.
</para>
<para>
<function>php_stream_read</function> returns the number of bytes that were
read successfully. There is no distinction between a failed read or an
end-of-file
condition - use <function>php_stream_eof</function> to test for an
<constant>EOF</constant>.
</para>
<para>
The internal position of the stream is advanced by the number of bytes that were
read, so that subsequent reads will continue reading from that point.
</para>
<para>
If less than <parameter>count</parameter> bytes are available to be read, this
call will block (or wait) until the required number are available, depending on
the
blocking status of the stream. By default, a stream is opened in blocking mode.
When reading from regular files, the blocking mode will not usually make any
difference: when the stream reaches the <constant>EOF</constant>
<function>php_stream_read</function> will return a value less than
<parameter>count</parameter>, and 0 on subsequent reads.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-write">
<refnamediv>
<refname>php_stream_write</refname>
<refpurpose>Write a number of bytes from a buffer to a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>size_t</type><methodname>php_stream_write</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>const char *</type><parameter>buf</parameter></methodparam>
<methodparam><type>size_t</type><parameter>count</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_write</function> writes <parameter>count</parameter>
bytes of data from <parameter>buf</parameter> into <parameter>stream</parameter>.
</para>
<para>
<function>php_stream_write</function> returns the number of bytes that were
read successfully. If there was an error, the number of bytes written will be
less than <parameter>count</parameter>.
</para>
<para>
The internal position of the stream is advanced by the number of bytes that were
written, so that subsequent writes will continue writing from that point.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-eof">
<refnamediv>
<refname>php_stream_eof</refname>
<refpurpose>Check for an end-of-file condition on a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_eof</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_eof</function> checks for an end-of-file condition
on <parameter>stream</parameter>.
</para>
<para>
<function>php_stream_read</function> returns the 1 to indicate
<constant>EOF</constant>, 0 if there is no <constant>EOF</constant> and -1 to
indicate an error.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-getc">
<refnamediv>
<refname>php_stream_getc</refname>
<refpurpose>Read a single byte from a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_getc</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_getc</function> reads a single character from
<parameter>stream</parameter> and returns it as an unsigned char cast
as an int, or <constant>EOF</constant> if the end-of-file is reached, or an error
occurred.
</para>
<para>
<function>php_stream_getc</function> may block in the same way as
<function>php_stream_read</function> blocks.
</para>
<para>
The internal position of the stream is advanced by 1 if successful.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-gets">
<refnamediv>
<refname>php_stream_gets</refname>
<refpurpose>Read a line of data from a stream into a buffer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>char *</type><methodname>php_stream_gets</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>char *</type><parameter>buf</parameter></methodparam>
<methodparam><type>size_t</type><parameter>maxlen</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_gets</function> reads up to <parameter>count</parameter>-1
bytes of data from <parameter>stream</parameter> and copies them into the
buffer <parameter>buf</parameter>. Reading stops after an
<constant>EOF</constant>
or a newline. If a newline is read, it is stored in <parameter>buf</parameter>
as part of
the returned data. A NUL terminating character is stored as the last character
in the buffer.
</para>
<para>
<function>php_stream_read</function> returns <parameter>buf</parameter>
when successful or NULL otherwise.
</para>
<para>
The internal position of the stream is advanced by the number of bytes that were
read, so that subsequent reads will continue reading from that point.
</para>
<para>
This function may block in the same way as <function>php_stream_read</function>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-close">
<refnamediv>
<refname>php_stream_close</refname>
<refpurpose>Close a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_close</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_close</function> safely closes <parameter>stream</parameter>
and releases the resources associated with it. After
<parameter>stream</parameter>
has been closed, it's value is undefined and should not be used.
</para>
<para>
<function>php_stream_close</function> returns 0 if the stream was closed or
<constant>EOF</constant> to indicate an error. Regardless of the success of the
call,
<parameter>stream</parameter> is undefined and should not be used after a call to
this function.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-flush">
<refnamediv>
<refname>php_stream_flush</refname>
<refpurpose>Flush stream buffers to storage</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_flush</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_flush</function> causes any data held in
write buffers in <parameter>stream</parameter> to be committed to the
underlying storage.
</para>
<para>
<function>php_stream_flush</function> returns 0 if the buffers were flushed,
or if the buffers did not need to be flushed, but returns <constant>EOF</constant>
to indicate an error.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-seek">
<refnamediv>
<refname>php_stream_seek</refname>
<refpurpose>Reposition a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_seek</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>off_t</type><parameter>offset</parameter></methodparam>
<methodparam><type>int</type><parameter>whence</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_seek</function> repositions the internal
position of <parameter>stream</parameter>.
The new position is determined by adding the <parameter>offset</parameter>
to the position indicated by <parameter>whence</parameter>.
If <parameter>whence</parameter> is set to <constant>SEEK_SET</constant>,
<constant>SEEK_CUR</constant> or <constant>SEEK_END</constant> the offset
is relative to the start of the stream, the current position or the end of the
stream, respectively.
</para>
<para>
<function>php_stream_seek</function> returns 0 on success, but -1 if there was an
error.
</para>
<note>
<para>
Not all streams support seeking, although the streams API will emulate a seek if
<parameter>whence</parameter> is set to <constant>SEEK_CUR</constant>
and <parameter>offset</parameter> is positive, by calling
<function>php_stream_read</function>
to read (and discard) <parameter>offset</parameter> bytes.
</para>
<para>
The emulation is only applied when the underlying stream implementation does not
support seeking. If the stream is (for example) a file based stream that is
wrapping
a non-seekable pipe, the streams api will not apply emulation because the file
based
stream implements a seek operation; the seek will fail and an error result will
be
returned to the caller.
</para>
</note>
</refsect1>
</refentry>
<refentry id="streams.php-stream-tell">
<refnamediv>
<refname>php_stream_tell</refname>
<refpurpose>Determine the position of a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>off_t</type><methodname>php_stream_tell</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_tell</function> returns the internal position of
<parameter>stream</parameter>, relative to the start of the stream.
If there is an error, -1 is returned.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-copy-to-stream">
<refnamediv>
<refname>php_stream_copy_to_stream</refname>
<refpurpose>Copy data from one stream to another</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>size_t</type><methodname>php_stream_copy_to_stream</methodname>
<methodparam><type>php_stream *</type><parameter>src</parameter></methodparam>
<methodparam><type>php_stream *</type><parameter>dest</parameter></methodparam>
<methodparam><type>size_t</type><parameter>maxlen</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_copy_to_stream</function> attempts to read up to
<parameter>maxlen</parameter>
bytes of data from <parameter>src</parameter> and write them to
<parameter>dest</parameter>,
and returns the number of bytes that were successfully copied.
</para>
<para>
If you want to copy all remaining data from the <parameter>src</parameter>
stream, pass the
constant <constant>PHP_STREAM_COPY_ALL</constant> as the value of
<parameter>maxlen</parameter>.
</para>
<note>
<simpara>
This function will attempt to copy the data in the most efficient manner, using
memory mapped
files when possible.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="streams.php-stream-copy-to-mem">
<refnamediv>
<refname>php_stream_copy_to_mem</refname>
<refpurpose>Copy data from stream and into an allocated buffer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>size_t</type><methodname>php_stream_copy_to_mem</methodname>
<methodparam><type>php_stream *</type><parameter>src</parameter></methodparam>
<methodparam><type>char **</type><parameter>buf</parameter></methodparam>
<methodparam><type>size_t</type><parameter>maxlen</parameter></methodparam>
<methodparam><type>int</type><parameter>persistent</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_copy_to_mem</function> allocates a buffer
<parameter>maxlen</parameter>+1
bytes in length using <function>pemalloc</function> (passing
<parameter>persistent</parameter>).
It then reads <parameter>maxlen</parameter> bytes from <parameter>src</parameter>
and stores
them in the allocated buffer.
</para>
<para>
The allocated buffer is returned in <parameter>buf</parameter>, and the number of
bytes successfully
read. You, the caller, are responsible for freeing the buffer by passing it and
<parameter>persistent</parameter>
to <function>pefree</function>.
</para>
<para>
If you want to copy all remaining data from the <parameter>src</parameter>
stream, pass the
constant <constant>PHP_STREAM_COPY_ALL</constant> as the value of
<parameter>maxlen</parameter>.
</para>
<note>
<simpara>
This function will attempt to copy the data in the most efficient manner, using
memory mapped
files when possible.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="streams.php-stream-make-seekable">
<refnamediv>
<refname>php_stream_make_seekable</refname>
<refpurpose>Convert a stream into a stream is seekable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_make_seekable</methodname>
<methodparam><type>php_stream
*</type><parameter>origstream</parameter></methodparam>
<methodparam><type>php_stream
**</type><parameter>newstream</parameter></methodparam>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_make_seekable</function> checks if
<parameter>origstream</parameter> is
seekable. If it is not, it will copy the data into a new temporary stream.
If successful, <parameter>newstream</parameter> is always set to the stream that
is valid to use, even if the original
stream was seekable.
</para>
<para>
<parameter>flags</parameter> allows you to specify your preference for the
seekeable stream that is
returned: use <constant>PHP_STREAM_NO_PREFERENCE</constant> to use the default
seekable stream
(which uses a dynamically expanding memory buffer, but switches to temporary file
backed storage
when the stream size becomes large), or use
<constant>PHP_STREAM_PREFER_STDIO</constant> to
use "regular" temporary file backed storage.
</para>
<para>
<table>
<title><function>php_stream_make_seekable</function> return values</title>
<tgroup cols="2">
<thead>
<row>
<entry>Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>PHP_STREAM_UNCHANGED</entry>
<entry>Original stream was seekable anyway. <parameter>newstream</parameter>
is set to the value
of <parameter>origstream</parameter>.
</entry>
</row>
<row>
<entry>PHP_STREAM_RELEASED</entry>
<entry>Original stream was not seekable and has been released.
<parameter>newstream</parameter> is set to the
new seekable stream. You should not access
<parameter>origstream</parameter> anymore.
</entry>
</row>
<row>
<entry>PHP_STREAM_FAILED</entry>
<entry>An error occurred while attempting conversion.
<parameter>newstream</parameter> is set to NULL;
<parameter>origstream</parameter> is still valid.
</entry>
</row>
<row>
<entry>PHP_STREAM_CRITICAL</entry>
<entry>An error occurred while attempting conversion that has left
<parameter>origstream</parameter> in
an indeterminate state. <parameter>newstream</parameter> is set to NULL and
it is highly recommended
that you close <parameter>origstream</parameter>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<simpara>
If you need to seek and write to the stream, it does not make sense to use this
function, because the stream
it returns is not guaranteed to be bound to the same resource as the original
stream.
</simpara>
</note>
<note>
<simpara>
If you only need to seek forwards, there is no need to call this function, as
the streams API will emulate
forward seeks when the whence parameter is <constant>SEEK_CUR</constant>.
</simpara>
</note>
<note>
<simpara>
If <parameter>origstream</parameter> is network based, this function will block
until the whole contents
have been downloaded.
</simpara>
</note>
<note>
<simpara>
NEVER call this function with an <parameter>origstream</parameter> that is
reference by a file pointer
in a PHP script! This function may cause the underlying stream to be closed
which could cause a crash
when the script next accesses the file pointer!
</simpara>
</note>
<note>
<simpara>
In many cases, this function can only succeed when
<parameter>origstream</parameter> is a newly opened
stream with no data buffered in the stream layer. For that reason, and because
this function is complicated to
use correctly, it is recommended that you use
<function>php_stream_open_wrapper</function> and pass in
<constant>PHP_STREAM_MUST_SEEK</constant> in your options instead of calling this
function directly.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="streams.php-stream-cast">
<refnamediv>
<refname>php_stream_cast</refname>
<refpurpose>Convert a stream into another form, such as a FILE* or
socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_cast</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>castas</parameter></methodparam>
<methodparam><type>void **</type><parameter>ret</parameter></methodparam>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_cast</function> attempts to convert
<parameter>stream</parameter> into
a resource indicated by <parameter>castas</parameter>.
If <parameter>ret</parameter> is NULL, the stream is queried to find out if such
a conversion is
possible, without actually performing the conversion (however, some internal
stream state *might*
be changed in this case).
If <parameter>flags</parameter> is set to <constant>REPORT_ERRORS</constant>, an
error
message will be displayed is there is an error during conversion.
</para>
<note>
<para>
This function returns <constant>SUCCESS</constant> for success or
<constant>FAILURE</constant>
for failure. Be warned that you must explicitly compare the return value
with <constant>SUCCESS</constant>
or <constant>FAILURE</constant> because of the underlying values of those
constants. A simple
boolean expression will not be interpreted as you intended.
</para>
</note>
<para>
<table>
<title>Resource types for <parameter>castas</parameter></title>
<tgroup cols="2">
<thead>
<row>
<entry>Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>PHP_STREAM_AS_STDIO</entry>
<entry>Requests an ANSI FILE* that represents the stream</entry>
</row>
<row>
<entry>PHP_STREAM_AS_FD</entry>
<entry>Requests a POSIX file descriptor that represents the stream</entry>
</row>
<row>
<entry>PHP_STREAM_AS_SOCKETD</entry>
<entry>Requests a network socket descriptor that represents the stream</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In addition to the basic resource types above, the conversion process can be
altered by using the
following flags by using the OR operator to combine the resource type with one or
more of the
following values:
<table>
<title>Resource types for <parameter>castas</parameter></title>
<tgroup cols="2">
<thead>
<row>
<entry>Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>PHP_STREAM_CAST_TRY_HARD</entry>
<entry>Tries as hard as possible, at the expense of additional resources, to
ensure that the conversion succeeds</entry>
</row>
<row>
<entry>PHP_STREAM_CAST_RELEASE</entry>
<entry>Informs the streams API that some other code (possibly a third party
library) will be responsible for closing the
underlying handle/resource. This causes the <parameter>stream</parameter> to
be closed in such a way the underlying
handle is preserved and returned in <parameter>ret</parameter>. If this
function succeeds, <parameter>stream</parameter>
should be considered closed and should no longer be used.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<simpara>
If your system supports <function>fopencookie</function> (systems using glibc 2
or later), the streams API
will always be able to synthesize an ANSI FILE* pointer over any stream.
While this is tremendously useful for passing any PHP stream to any third-party
libraries, such behaviour is not
portable. You are requested to consider the portability implications before
distributing you extension.
If the fopencookie synthesis is not desireable, you should query the stream to
see if it naturally supports FILE*
by using <function>php_stream_is</function>
</simpara>
</note>
<note>
<simpara>
If you ask a socket based stream for a FILE*, the streams API will use
<function>fdopen</function> to
create it for you. Be warned that doing do may cause data that was buffered in
the streams layer to be
lost if you intermix streams API calls with ANSI stdio calls.
</simpara>
</note>
<para>
See also <function>php_stream_is</function> and
<function>php_stream_can_cast</function>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-can-cast">
<refnamediv>
<refname>php_stream_can_cast</refname>
<refpurpose>Determines if a stream can be converted into another form, such as a
FILE* or socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_can_cast</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>castas</parameter></methodparam>
</methodsynopsis>
<para>
This function is equivalent to calling <function>php_stream_cast</function> with
<parameter>ret</parameter>
set to NULL and <parameter>flags</parameter> set to 0.
It returns <constant>SUCCESS</constant> if the stream can be converted into the
form requested, or
<constant>FAILURE</constant> if the conversion cannot be performed.
</para>
<note>
<simpara>
Although this function will not perform the conversion, some internal stream
state *might* be
changed by this call.
</simpara>
</note>
<note>
<simpara>
You must explicity compare the return value of this function with one of the
constants, as described
in <function>php_stream_cast</function>.
</simpara>
</note>
<para>
See also <function>php_stream_cast</function> and
<function>php_stream_is</function>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-is-persistent">
<refnamediv>
<refname>php_stream_is_persistent</refname>
<refpurpose>Determines if a stream is a persistent stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_is_persistent</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_is_persistent</function> returns 1 if the stream is a
persistent stream,
0 otherwise.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-is">
<refnamediv>
<refname>php_stream_is</refname>
<refpurpose>Determines if a stream is of a particular type</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_is</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>istype</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_is</function> returns 1 if <parameter>stream</parameter> is
of
the type specified by <parameter>istype</parameter>, or 0 otherwise.
<table>
<title>Values for <parameter>istype</parameter></title>
<tgroup cols="2">
<thead>
<row>
<entry>Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>PHP_STREAM_IS_STDIO</entry>
<entry>The stream is implemented using the stdio implementation</entry>
</row>
<row>
<entry>PHP_STREAM_IS_SOCKET</entry>
<entry>The stream is implemented using the network stream
implementation</entry>
</row>
<row>
<entry>PHP_STREAM_IS_USERSPACE</entry>
<entry>The stream is implemented using the userspace object
implementation</entry>
</row>
<row>
<entry>PHP_STREAM_IS_MEMORY</entry>
<entry>The stream is implemented using the grow-on-demand memory stream
implementation</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<simpara>
The PHP_STREAM_IS_XXX "constants" are actually defined as pointers to the
underlying
stream operations structure. If your extension (or some other extension)
defines additional
streams, it should also declare a PHP_STREAM_IS_XXX constant in it's header file
that you
can use as the basis of this comparison.
</simpara>
</note>
<note>
<simpara>
This function is implemented as a simple (and fast) pointer comparision, and
does not change
the stream state in any way.
</simpara>
</note>
<para>
See also <function>php_stream_cast</function> and
<function>php_stream_can_cast</function>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-passthru">
<refnamediv>
<refname>php_stream_passthru</refname>
<refpurpose>Outputs all remaining data from a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>size_t</type><methodname>php_stream_passthru</methodname>
<methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_passthru</function> outputs all remaining data from
<parameter>stream</parameter>
to the active output buffer and returns the number of bytes output.
If buffering is disabled, the data is written straight to the output, which is
the browser making the
request in the case of PHP on a web server, or stdout for CLI based PHP.
This function will use memory mapped files if possible to help improve
performance.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-register-url-stream-wrapper">
<refnamediv>
<refname>php_register_url_stream_wrapper</refname>
<refpurpose>Registers a wrapper with the Streams API</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_register_url_stream_wrapper</methodname>
<methodparam><type>char *</type><parameter>protocol</parameter></methodparam>
<methodparam><type>php_stream_wrapper
*</type><parameter>wrapper</parameter></methodparam>
<methodparam><type>TSRMLS_DC</type><parameter></parameter></methodparam>
</methodsynopsis>
<para>
<function>php_register_url_stream_wrapper</function> registers
<parameter>wrapper</parameter>
as the handler for the protocol specified by <parameter>protocol</parameter>.
</para>
<note>
<simpara>
If you call this function from a loadable module, you *MUST* call
<function>php_unregister_url_stream_wrapper</function>
in your module shutdown function, otherwise PHP will crash.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="streams.php-unregister-url-stream-wrapper">
<refnamediv>
<refname>php_unregister_url_stream_wrapper</refname>
<refpurpose>Un-registers a wrapper from the Streams API</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_unregister_url_stream_wrapper</methodname>
<methodparam><type>char *</type><parameter>protocol</parameter></methodparam>
<methodparam><type>TSRMLS_DC</type><parameter></parameter></methodparam>
</methodsynopsis>
<para>
<function>php_unregister_url_stream_wrapper</function> unregisters the wrapper
associated with <parameter>protocol</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-open-wrapper-ex">
<refnamediv>
<refname>php_stream_open_wrapper_ex</refname>
<refpurpose>Opens a stream on a file or URL, specifying context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_open_wrapper_ex</methodname>
<methodparam><type>char *</type><parameter>path</parameter></methodparam>
<methodparam><type>char *</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
<methodparam><type>char **</type><parameter>opened</parameter></methodparam>
<methodparam><type>php_stream_context
*</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_open_wrapper_ex</function> is exactly like
<function>php_stream_open_wrapper</function>, but allows you to specify a
php_stream_context object using <parameter>context</parameter>.
To find out more about stream contexts, see XXX
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-open-wrapper-as-file">
<refnamediv>
<refname>php_stream_open_wrapper_as_file</refname>
<refpurpose>Opens a stream on a file or URL, and converts to a FILE*</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>FILE *</type><methodname>php_stream_open_wrapper_as_file</methodname>
<methodparam><type>char *</type><parameter>path</parameter></methodparam>
<methodparam><type>char *</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
<methodparam><type>char **</type><parameter>opened</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_open_wrapper_as_file</function> is exactly like
<function>php_stream_open_wrapper</function>, but converts the stream
into an ANSI stdio FILE* and returns that instead of the stream.
This is a convenient shortcut for extensions that pass FILE* to third-party
libraries.
</para>
</refsect1>
</refentry>
</sect1>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/chapters/streams.file.xml
+++ phpdoc/en/chapters/streams.file.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<sect1 id="streams.file-api">
<title>Streams File API Reference</title>
<refentry id="streams.php-stream-fopen-from-file">
<refnamediv>
<refname>php_stream_fopen_from_file</refname>
<refpurpose>Convert an ANSI FILE* into a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_fopen_from_file</methodname>
<methodparam><type>FILE *</type><parameter>file</parameter></methodparam>
<methodparam><type>char *</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_fopen_from_file</function> returns a stream based on the
<parameter>file</parameter>. <parameter>mode</parameter> must be the same
as the mode used to open <parameter>file</parameter>, otherwise strange errors
may occur when trying to write when the mode of the stream is different from the
mode
on the file.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-fopen-tmpfile">
<refnamediv>
<refname>php_stream_fopen_tmpfile</refname>
<refpurpose>Open a FILE* with tmpfile() and convert into a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_fopen_tmpfile</methodname>
<methodparam><type>void</type><parameter></parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_fopen_from_file</function> returns a stream based on a
temporary file opened with a mode of "w+b". The temporary file will be deleted
automatically when the stream is closed or the process terminates.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-fopen-temporary-file">
<refnamediv>
<refname>php_stream_fopen_temporary_file</refname>
<refpurpose>Generate a temporary file name and open a stream on it</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_fopen_temporary_file</methodname>
<methodparam><type>const char *</type><parameter>dir</parameter></methodparam>
<methodparam><type>const char *</type><parameter>pfx</parameter></methodparam>
<methodparam><type>char **</type><parameter>opened</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_fopen_temporary_file</function> generates a temporary file
name
in the directory specified by <parameter>dir</parameter> and with a prefix of
<parameter>pfx</parameter>.
The generated file name is returns in the <parameter>opened</parameter>
parameter, which you
are responsible for cleaning up using <function>efree</function>.
A stream is opened on that generated filename in "w+b" mode.
The file is NOT automatically deleted; you are responsible for unlinking or
moving the file when you have
finished with it.
</para>
</refsect1>
</refentry>
</sect1>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/chapters/streams.xml
+++ phpdoc/en/chapters/streams.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<chapter id="streams">
<title>Streams API for PHP Extension Authors</title>
<sect1 id="streams.overview">
<title>Overview</title>
<para>
The PHP Streams API introduces a unified approach to the handling of
files and sockets in PHP extension. Using a single API with standard
functions for common operations, the streams API allows your extension
to access files, sockets, URLs, memory and script-defined objects.
Streams is a run-time extensible API that allows dynamically loaded
modules (and scripts!) to register new streams.
</para>
<para>
The aim of the Streams API is to make it comfortable for developers to
open files, urls and other streamable data sources with a unified API
that is easy to understand. The API is more or less based on the ANSI
C stdio family of functions (with identical semantics for most of the main
functions), so C programmers will have a feeling of familiarity with streams.
</para>
<para>
The streams API operates on a couple of different levels: at the base level,
the API defines php_stream objects to represent streamable data sources.
On a slightly higher level, the API defines php_stream_wrapper objects
which "wrap" around the lower level API to provide support for retrieving
data and meta-data from URLs.
</para>
<para>
Streams can be cast (converted) into other types of file-handles, so that they
can be used with third-pary libraries without a great deal of trouble. This
allows those libraries to access data directly from URL sources. If your
system has the <function>fopencookie</function> function, you can even
pass any PHP stream to any library that uses ANSI stdio!
</para>
</sect1>
<sect1 id="streams.basics">
<title>Streams Basics</title>
<para>
Using streams is very much like using ANSI stdio functions. The main
difference is in how you obtain the stream handle to begin with.
In most cases, you will use <function>php_stream_open_wrapper</function>
to obtain the stream handle. This function works very much like fopen,
as can be seen from the example below:
</para>
<para>
<example>
<title>simple stream example that displays the PHP home page</title>
<programlisting role="c">
<![CDATA[
php_stream * stream = php_stream_open_wrapper("http://www.php.net";, "rb",
REPORT_ERRORS, NULL);
if (stream) {
while(!php_stream_eof(stream)) {
char buf[1024];
if (php_stream_gets(stream, buf, sizeof(buf))) {
printf(buf);
} else {
break;
}
}
php_stream_close(stream);
}
]]>
</programlisting>
</example>
</para>
<para>
The table below shows the Streams equivalents of the more common ANSI stdio
functions.
Unless noted otherwise, the semantics of the functions are identical.
<table>
<title>ANSI stdio equivalent functions in the Streams API</title>
<tgroup cols="3">
<thead>
<row>
<entry>ANSI Stdio Function</entry>
<entry>PHP Streams Function</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry>fopen</entry>
<entry>php_stream_open_wrapper</entry>
<entry>Streams includes additional parameters</entry>
</row>
<row>
<entry>fclose</entry>
<entry>php_stream_close</entry>
<entry></entry>
</row>
<row>
<entry>fgets</entry>
<entry>php_stream_gets</entry>
<entry></entry>
</row>
<row>
<entry>fread</entry>
<entry>php_stream_read</entry>
<entry>The nmemb parameter is assumed to have a value of 1, so the prototype
looks more like read(2)</entry>
</row>
<row>
<entry>fwrite</entry>
<entry>php_stream_write</entry>
<entry>The nmemb parameter is assumed to have a value of 1, so the prototype
looks more like write(2)</entry>
</row>
<row>
<entry>fseek</entry>
<entry>php_stream_seek</entry>
<entry></entry>
</row>
<row>
<entry>ftell</entry>
<entry>php_stream_tell</entry>
<entry></entry>
</row>
<row>
<entry>rewind</entry>
<entry>php_stream_rewind</entry>
<entry></entry>
</row>
<row>
<entry>feof</entry>
<entry>php_stream_eof</entry>
<entry></entry>
</row>
<row>
<entry>fgetc</entry>
<entry>php_stream_getc</entry>
<entry></entry>
</row>
<row>
<entry>fputc</entry>
<entry>php_stream_putc</entry>
<entry></entry>
</row>
<row>
<entry>fflush</entry>
<entry>php_stream_flush</entry>
<entry></entry>
</row>
<row>
<entry>puts</entry>
<entry>php_stream_puts</entry>
<entry>Same semantics as puts, NOT fputs</entry>
</row>
<row>
<entry>fstat</entry>
<entry>php_stream_stat</entry>
<entry>Streams has a richer stat structure</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</sect1>
&chapters.streams.common;
&chapters.streams.dir;
&chapters.streams.file;
&chapters.streams.socket;
&chapters.streams.structs;
&chapters.streams.constants;
</chapter>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/chapters/streams.constants.xml
+++ phpdoc/en/chapters/streams.constants.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<sect1 id="streams.constants">
<title>Streams Constants</title>
<refentry id="streams.options">
<refnamediv>
<refname>Stream open options</refname>
<refpurpose>Affects the operation of stream factory functions</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
One or more of these values can be combined using the OR operator.
<variablelist>
<varlistentry>
<term>
<constant>IGNORE_PATH</constant>
</term>
<listitem>
<simpara>
This is the default option for streams; it requests that the include_path is
not to be searched for the requested file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>USE_PATH</constant>
</term>
<listitem>
<simpara>
Requests that the include_path is to be searched for the requested file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IGNORE_URL</constant>
</term>
<listitem>
<simpara>
Requests that registered URL wrappers are to be ignored when opening the
stream. Other non-URL wrappers will be taken into consideration when
decoding the path. There is no opposite form for this flag; the streams
API will use all registered wrappers by default.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IGNORE_URL_WIN</constant>
</term>
<listitem>
<simpara>
On Windows systems, this is equivalent to IGNORE_URL.
On all other systems, this flag has no effect.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>ENFORCE_SAFE_MODE</constant>
</term>
<listitem>
<simpara>
Requests that the underlying stream implementation perform safe_mode
checks on the file before opening the file. Omitting this flag will skip
safe_mode checks and allow opening of any file that the PHP process
has rights to access.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>REPORT_ERRORS</constant>
</term>
<listitem>
<simpara>
If this flag is set, and there was an error during the opening of the file
or URL, the streams API will call the php_error function for you. This
is useful because the path may contain username/password information
that should not be displayed in the browser output (it would be a
security risk to do so). When the streams API raises the error, it first
strips username/password information from the path, making the error
message safe to display in the browser.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>STREAM_MUST_SEEK</constant>
</term>
<listitem>
<simpara>
This flag is useful when your extension really must be able to randomly
seek around in a stream. Some streams may not be seekable in their
native form, so this flag asks the streams API to check to see if the
stream does support seeking. If it does not, it will copy the stream
into temporary storage (which may be a temporary file or a memory
stream) which does support seeking.
Please note that this flag is not useful when you want to seek the
stream and write to it, because the stream you are accessing might
not be bound to the actual resource you requested.
</simpara>
<note>
<simpara>
If the requested resource is network based, this flag will cause the
opener to block until the whole contents have been downloaded.
</simpara>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>STREAM_WILL_CAST</constant>
</term>
<listitem>
<simpara>
If your extension is using a third-party library that expects a FILE* or
file descriptor, you can use this flag to request the streams API to
open the resource but avoid buffering. You can then use
<function>php_stream_cast</function> to retrieve the FILE* or
file descriptor that the library requires.
</simpara>
<simpara>
The is particularly useful when accessing HTTP URLs where the start
of the actual stream data is found after an indeterminate offset into
the stream.
</simpara>
<simpara>
Since this option disables buffering at the streams API level, you
may experience lower performance when using streams functions
on the stream; this is deemed acceptable because you have told
streams that you will be using the functions to match the underlying
stream implementation.
Only use this option when you are sure you need it.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>
</sect1>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/chapters/streams.structs.xml
+++ phpdoc/en/chapters/streams.structs.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<sect1 id="streams.structs">
<title>Streams Structures</title>
<refentry id="streams.struct-php-stream-statbuf">
<refnamediv>
<refname>struct php_stream_statbuf</refname>
<refpurpose>Holds information about a file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<synopsis>
<structname>php_stream_statbuf</structname>
<type>struct stat</type> <structfield>sb</structfield>
</synopsis>
<para>
<structfield>sb</structfield> is a regular, system defined, struct stat.
</para>
</refsect1>
</refentry>
<refentry id="streams.struct-php-stream-dirent">
<refnamediv>
<refname>struct php_stream_dirent</refname>
<refpurpose>Holds information about a single file during dir scanning</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<synopsis>
<structname>php_stream_dirent</structname>
<type>char</type> <structfield>d_name[MAXPATHLEN]</structfield>
</synopsis>
<para>
<structfield>d_name</structfield> holds the name of the file, relative to the
directory
being scanned.
</para>
</refsect1>
</refentry>
</sect1>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/chapters/streams.socket.xml
+++ phpdoc/en/chapters/streams.socket.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<sect1 id="streams.socket-api">
<title>Streams Socket API Reference</title>
<refentry id="streams.php-stream-sock-open-from-socket">
<refnamediv>
<refname>php_stream_sock_open_from_socket</refname>
<refpurpose>Convert a socket descriptor into a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream
*</type><methodname>php_stream_sock_open_from_socket</methodname>
<methodparam><type>int</type><parameter>socket</parameter></methodparam>
<methodparam><type>int</type><parameter>persistent</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_sock_open_from_socket</function> returns a stream based on
the
<parameter>socket</parameter>. <parameter>persistent</parameter> is a flag that
controls whether the stream is opened as a persistent stream. Generally
speaking, this parameter
will usually be 0.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-sock-open-host">
<refnamediv>
<refname>php_stream_sock_open_host</refname>
<refpurpose>Open a connection to a host and return a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_sock_open_host</methodname>
<methodparam><type>const char *</type><parameter>host</parameter></methodparam>
<methodparam><type>unsigned short</type><parameter>port</parameter></methodparam>
<methodparam><type>int</type><parameter>socktype</parameter></methodparam>
<methodparam><type>struct timeval
*</type><parameter>timeout</parameter></methodparam>
<methodparam><type>int</type><parameter>persistent</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_sock_open_host</function> establishes a connect to the
specified
<parameter>host</parameter> and <parameter>port</parameter>.
<parameter>socktype</parameter>
specifies the connection semantics that should apply to the connection. Values for
<parameter>socktype</parameter> are system dependent, but will usually include
(at a minimum)
<constant>SOCK_STREAM</constant> for sequenced, reliable, two-way connection
based streams (TCP),
or <constant>SOCK_DGRAM</constant> for connectionless, unreliable messages of a
fixed maximum
length (UDP).
</para>
<para>
<parameter>persistent</parameter> is a flag the controls whether the stream is
opened as a persistent
stream. Generally speaking, this parameter will usually be 0.
</para>
<para>
If not NULL, <parameter>timeout</parameter> specifies a maximum time to allow for
the connection to be made.
If the connection attempt takes longer than the timeout value, the connection
attempt is aborted and
NULL is returned to indicate that the stream could not be opened.
</para>
<note>
<simpara>
The timeout value does not include the time taken to perform a DNS lookup. The
reason for this is
because there is no portable way to implement a non-blocking DNS lookup.
</simpara>
<simpara>
The timeout only applies to the connection phase; if you need to set timeouts
for subsequent read
or write operations, you should use
<function>php_stream_sock_set_timeout</function> to configure
the timeout duration for your stream once it has been opened.
</simpara>
</note>
<para>
The streams API places no restrictions on the values you use for
<parameter>socktype</parameter>,
but encourages you to consider the portability of values you choose before you
release your
extension.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-sock-open-unix">
<refnamediv>
<refname>php_stream_sock_open_unix</refname>
<refpurpose>Open a UNIX domain socket and convert into a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_sock_open_unix</methodname>
<methodparam><type>const char *</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>pathlen</parameter></methodparam>
<methodparam><type>int</type><parameter>persistent</parameter></methodparam>
<methodparam><type>struct timeval
*</type><parameter>timeout</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_sock_open_unix</function> attempts to open the UNIX domain
socket
specified by <parameter>path</parameter>. <parameter>pathlen</parameter>
specifies the
length of <parameter>path</parameter>.
If <parameter>timeout</parameter> is not NULL, it specifies a timeout period for
the connection attempt.
<parameter>persistent</parameter> indicates if the stream should be opened as a
persistent
stream. Generally speaking, this parameter will usually be 0.
</para>
<note>
<simpara>
This function will not work under Windows, which does not implement unix domain
sockets.
A possible exception to this rule is if your PHP binary was built using cygwin.
You are encouraged
to consider this aspect of the portability of your extension before it's
release.
</simpara>
</note>
<note>
<simpara>
This function treats <parameter>path</parameter> in a binary safe manner,
suitable for
use on systems with an abstract namespace (such as Linux), where the first
character
of path is a NUL character.
</simpara>
</note>
</refsect1>
</refentry>
</sect1>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/chapters/streams.dir.xml
+++ phpdoc/en/chapters/streams.dir.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <[EMAIL PROTECTED]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<sect1 id="streams.dir-api">
<title>Streams Dir API Reference</title>
<para>
The functions listed in this section work on local files, as well as remote files
(provided that the wrapper supports this functionality!).
</para>
<refentry id="streams.php-stream-opendir">
<refnamediv>
<refname>php_stream_opendir</refname>
<refpurpose>Open a directory for file enumeration</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream *</type><methodname>php_stream_opendir</methodname>
<methodparam><type>char *</type><parameter>path</parameter></methodparam>
<methodparam><type>php_stream_context
*</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_opendir</function> returns a stream that can be used to list
the
files that are contained in the directory specified by
<parameter>path</parameter>.
This function is functionally equivalent to POSIX <function>opendir</function>.
Although this function returns a php_stream object, it is not recommended to
try to use the functions from the common API on these streams.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-readdir">
<refnamediv>
<refname>php_stream_readdir</refname>
<refpurpose>Fetch the next directory entry from an opened dir</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>php_stream_dirent *</type><methodname>php_stream_readdir</methodname>
<methodparam><type>php_stream
*</type><parameter>dirstream</parameter></methodparam>
<methodparam><type>php_stream_dirent
*</type><parameter>ent</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_readdir</function> reads the next directory entry
from <parameter>dirstream</parameter> and stores it into
<parameter>ent</parameter>.
If the function succeeds, the return value is <parameter>ent</parameter>.
If the function fails, the return value is NULL.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-rewinddir">
<refnamediv>
<refname>php_stream_rewinddir</refname>
<refpurpose>Rewind a directory stream to the first entry</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_rewinddir</methodname>
<methodparam><type>php_stream
*</type><parameter>dirstream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_rewinddir</function> rewinds a directory stream to the first
entry.
Returns 0 on success, but -1 on failure.
</para>
</refsect1>
</refentry>
<refentry id="streams.php-stream-closedir">
<refnamediv>
<refname>php_stream_closedir</refname>
<refpurpose>Close a directory stream and release resources</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>php_stream_closedir</methodname>
<methodparam><type>php_stream
*</type><parameter>dirstream</parameter></methodparam>
</methodsynopsis>
<para>
<function>php_stream_closedir</function> closes a directory stream and releases
resources associated with it.
Returns 0 on success, but -1 on failure.
</para>
</refsect1>
</refentry>
</sect1>
<!-- 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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
