mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
8632d87a0b
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. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@91492 c90b9560-bf6c-de11-be94-00142212c4b1
1004 lines
40 KiB
XML
Executable file
1004 lines
40 KiB
XML
Executable file
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.1 $ -->
|
|
<!-- Author: Wez Furlong <wez@thebrainroom.com>
|
|
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
|
|
-->
|
|
|