sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

WS, prepare for new doc style

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@249386 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-12-30 00:26:59 +00:00
parent cecfe8e440
commit 65206b229b
34 changed files with 2158 additions and 2169 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
reference/stream/functions/stream-context-create.xml
View file

@ -1,48 +1,48 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<refentry xml:id="function.stream-context-create" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_create</refname>
<refpurpose>Create a streams context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_context_create</methodname>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<simpara>
Creates and returns a stream context with any options supplied in
<parameter>options</parameter> preset.
</simpara>
<simpara>
<parameter>options</parameter> must be an associative
array of associative arrays in the format
<literal>$arr['wrapper']['option'] = $value</literal>.
It defaults to an empty array.
</simpara>
<simpara>
<parameter>params</parameter> must be an associative array
in the format <literal>$arr['parameter'] = $value</literal>.
Refer to <function>stream_context_set_params</function> for
a listing of standard stream parameters.
</simpara>
<note>
<simpara>
The <parameter>params</parameter> argument
was added to <literal>PHP 6.0.0</literal>.
</simpara>
</note>
<example>
<title>Using <function>stream_context_create</function></title>
<programlisting role="php">
<!-- $Revision: 1.7 $ -->
<refentry xml:id="function.stream-context-create" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_create</refname>
<refpurpose>Create a streams context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_context_create</methodname>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<simpara>
Creates and returns a stream context with any options supplied in
<parameter>options</parameter> preset.
</simpara>
<simpara>
<parameter>options</parameter> must be an associative
array of associative arrays in the format
<literal>$arr['wrapper']['option'] = $value</literal>.
It defaults to an empty array.
</simpara>
<simpara>
<parameter>params</parameter> must be an associative array
in the format <literal>$arr['parameter'] = $value</literal>.
Refer to <function>stream_context_set_params</function> for
a listing of standard stream parameters.
</simpara>
<note>
<simpara>
The <parameter>params</parameter> argument
was added to <literal>PHP 6.0.0</literal>.
</simpara>
</note>
<example>
<title>Using <function>stream_context_create</function></title>
<programlisting role="php">
<![CDATA[
<?php
$opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar\r\n"
)
);
@ -56,15 +56,15 @@ fpassthru($fp);
fclose($fp);
?>
]]>
</programlisting>
</example>
<simpara>
See also
<function>stream_context_set_option</function>, and
Listing of supported wrappers with context options (<xref linkend="wrappers"/>).
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
<simpara>
See also
<function>stream_context_set_option</function>, and
Listing of supported wrappers with context options (<xref linkend="wrappers"/>).
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

74
reference/stream/functions/stream-context-get-default.xml
View file

@ -1,37 +1,37 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<refentry xml:id="function.stream-context-get-default" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_get_default</refname>
<refpurpose>Retreive the default streams context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_context_get_default</methodname>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns the default stream context which is used whenever file operations
(<function>fopen</function>, <function>file_get_contents</function>, etc...)
are called without a context parameter. Options for the default context
can optionally be specified with this function using the same syntax as
<function>stream_context_create</function>.
</simpara>
<simpara>
<parameter>options</parameter> must be an associative
array of associative arrays in the format
<literal>$arr['wrapper']['option'] = $value</literal>.
</simpara>
<example>
<title>Using <function>stream_context_get_default</function></title>
<programlisting role="php">
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-context-get-default" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_get_default</refname>
<refpurpose>Retreive the default streams context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_context_get_default</methodname>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns the default stream context which is used whenever file operations
(<function>fopen</function>, <function>file_get_contents</function>, etc...)
are called without a context parameter. Options for the default context
can optionally be specified with this function using the same syntax as
<function>stream_context_create</function>.
</simpara>
<simpara>
<parameter>options</parameter> must be an associative
array of associative arrays in the format
<literal>$arr['wrapper']['option'] = $value</literal>.
</simpara>
<example>
<title>Using <function>stream_context_get_default</function></title>
<programlisting role="php">
<![CDATA[
<?php
$default_opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar",
'proxy'=>"tcp://10.54.1.39:8000"
)
@ -62,15 +62,15 @@ readfile('http://www.example.com', false, $alternate);
?>
]]>
</programlisting>
</example>
<simpara>
See also
<function>stream_context_create</function>, and
Listing of supported wrappers with context options (<xref linkend="wrappers"/>).
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
<simpara>
See also
<function>stream_context_create</function>, and
Listing of supported wrappers with context options (<xref linkend="wrappers"/>).
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

34
reference/stream/functions/stream-context-get-options.xml
View file

@ -1,21 +1,21 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-context-get-options" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_get_options</refname>
<refpurpose>Retrieve options for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_context_get_options</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns an array of options on the specified stream or context.
</simpara>
</refsect1>
</refentry>
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-context-get-options" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_get_options</refname>
<refpurpose>Retrieve options for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_context_get_options</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns an array of options on the specified stream or context.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

52
reference/stream/functions/stream-context-set-option.xml
View file

@ -1,30 +1,30 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-context-set-option" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_set_option</refname>
<refpurpose>Sets an option for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_context_set_option</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
<methodparam><type>string</type><parameter>wrapper</parameter></methodparam>
<methodparam><type>string</type><parameter>option</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>bool</type><methodname>stream_context_set_option</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
<methodparam><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<simpara>
Sets an option on the specified context. <parameter>value</parameter>
is set to <parameter>option</parameter> for <parameter>wrapper</parameter>
</simpara>
</refsect1>
</refentry>
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-context-set-option" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_set_option</refname>
<refpurpose>Sets an option for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_context_set_option</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
<methodparam><type>string</type><parameter>wrapper</parameter></methodparam>
<methodparam><type>string</type><parameter>option</parameter></methodparam>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>bool</type><methodname>stream_context_set_option</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
<methodparam><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<simpara>
Sets an option on the specified context. <parameter>value</parameter>
is set to <parameter>option</parameter> for <parameter>wrapper</parameter>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

88
reference/stream/functions/stream-context-set-params.xml
View file

@ -1,48 +1,48 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-context-set-params" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_set_params</refname>
<refpurpose>Set parameters for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_context_set_params</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<simpara>
<parameter>params</parameter> should be an associative array of the structure:
<literal>$params['paramname'] = "paramvalue";</literal>.
</simpara>
<table>
<title>Parameters</title>
<tgroup cols="2">
<thead>
<row>
<entry>Parameters</entry>
<entry>Purpose</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>notification</literal></entry>
<entry>
Name of user-defined callback function to be called whenever a stream triggers a notification.
</entry>
</row>
<row>
<entry><literal>options</literal></entry>
<entry>
Array of options as in <function>stream_context_create</function>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
</refentry>
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-context-set-params" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_context_set_params</refname>
<refpurpose>Set parameters for a stream/wrapper/context</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_context_set_params</methodname>
<methodparam><type>resource</type><parameter>stream_or_context</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<simpara>
<parameter>params</parameter> should be an associative array of the structure:
<literal>$params['paramname'] = "paramvalue";</literal>.
</simpara>
<table>
<title>Parameters</title>
<tgroup cols="2">
<thead>
<row>
<entry>Parameters</entry>
<entry>Purpose</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>notification</literal></entry>
<entry>
Name of user-defined callback function to be called whenever a stream triggers a notification.
</entry>
</row>
<row>
<entry><literal>options</literal></entry>
<entry>
Array of options as in <function>stream_context_create</function>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

150
reference/stream/functions/stream-filter-append.xml
View file

@ -1,52 +1,52 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<refentry xml:id="function.stream-filter-append" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_append</refname>
<refpurpose>Attach a filter to a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_filter_append</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>read_write</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Adds <parameter>filtername</parameter> to the list of filters
attached to <parameter>stream</parameter>. This filter will be
added with the specified <parameter>params</parameter>
to the <emphasis>end</emphasis> of the list and
will therefore be called last during stream operations. To
add a filter to the beginning of the list, use
<function>stream_filter_prepend</function>.
</para>
<para>
By default, <function>stream_filter_append</function> will
attach the filter to the <literal>read filter chain</literal>
if the file was opened for reading (i.e. File Mode:
<literal>r</literal>, and/or <literal>+</literal>). The filter
will also be attached to the <literal>write filter chain</literal>
if the file was opened for writing (i.e. File Mode:
<literal>w</literal>, <literal>a</literal>, and/or <literal>+</literal>).
<constant>STREAM_FILTER_READ</constant>,
<constant>STREAM_FILTER_WRITE</constant>, and/or
<constant>STREAM_FILTER_ALL</constant> can also be passed to the
<parameter>read_write</parameter> parameter to override this behavior.
</para>
<para>
As of PHP 5.1.0, this function returns a resource which
can be used to refer to this filter instance during a call
to <function>stream_filter_remove</function>.
Prior to PHP 5.1.0, this function returns &true; on success
or &false; on failure.
</para>
<para>
<example>
<title>Controlling where filters are applied</title>
<programlisting role="php">
<!-- $Revision: 1.18 $ -->
<refentry xml:id="function.stream-filter-append" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_append</refname>
<refpurpose>Attach a filter to a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_filter_append</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>read_write</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Adds <parameter>filtername</parameter> to the list of filters
attached to <parameter>stream</parameter>. This filter will be
added with the specified <parameter>params</parameter>
to the <emphasis>end</emphasis> of the list and
will therefore be called last during stream operations. To
add a filter to the beginning of the list, use
<function>stream_filter_prepend</function>.
</para>
<para>
By default, <function>stream_filter_append</function> will
attach the filter to the <literal>read filter chain</literal>
if the file was opened for reading (i.e. File Mode:
<literal>r</literal>, and/or <literal>+</literal>). The filter
will also be attached to the <literal>write filter chain</literal>
if the file was opened for writing (i.e. File Mode:
<literal>w</literal>, <literal>a</literal>, and/or <literal>+</literal>).
<constant>STREAM_FILTER_READ</constant>,
<constant>STREAM_FILTER_WRITE</constant>, and/or
<constant>STREAM_FILTER_ALL</constant> can also be passed to the
<parameter>read_write</parameter> parameter to override this behavior.
</para>
<para>
As of PHP 5.1.0, this function returns a resource which
can be used to refer to this filter instance during a call
to <function>stream_filter_remove</function>.
Prior to PHP 5.1.0, this function returns &true; on success
or &false; on failure.
</para>
<para>
<example>
<title>Controlling where filters are applied</title>
<programlisting role="php">
<![CDATA[
<?php
/* Open a test file for reading and writing */
@ -81,33 +81,33 @@ Guvf vf n grfg
*/
?>
]]>
</programlisting>
</example>
</para>
<note>
<title>When using custom (user) filters</title>
<simpara>
<function>stream_filter_register</function> must be called first
in order to register the desired user filter to <parameter>filtername</parameter>.
</simpara>
</note>
<note>
<simpara>
Stream data is read from resources (both local and remote) in chunks,
with any unconsumed data kept in internal buffers. When a new
filter is appended to a stream, data in the internal buffers is processed through
the new filter at that time. This differs from the behavior of
<function>stream_filter_prepend</function>.
</simpara>
</note>
<simpara>
See also
<function>stream_filter_register</function>,
<function>stream_filter_prepend</function>, and
<function>stream_get_filters</function>.
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<title>When using custom (user) filters</title>
<simpara>
<function>stream_filter_register</function> must be called first
in order to register the desired user filter to <parameter>filtername</parameter>.
</simpara>
</note>
<note>
<simpara>
Stream data is read from resources (both local and remote) in chunks,
with any unconsumed data kept in internal buffers. When a new
filter is appended to a stream, data in the internal buffers is processed through
the new filter at that time. This differs from the behavior of
<function>stream_filter_prepend</function>.
</simpara>
</note>
<simpara>
See also
<function>stream_filter_register</function>,
<function>stream_filter_prepend</function>, and
<function>stream_get_filters</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

142
reference/stream/functions/stream-filter-prepend.xml
View file

@ -1,75 +1,75 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<refentry xml:id="function.stream-filter-prepend" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_prepend</refname>
<refpurpose>Attach a filter to a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_filter_prepend</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>read_write</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Adds <parameter>filtername</parameter> to the list of filters
attached to <parameter>stream</parameter>. This filter will be
added with the specified <parameter>params</parameter>
to the <emphasis>beginning</emphasis> of the list and
will therefore be called first during stream operations. To
add a filter to the end of the list, use
<function>stream_filter_append</function>.
</para>
<para>
By default, <function>stream_filter_prepend</function> will
attach the filter to the <literal>read filter chain</literal>
if the file was opened for reading (i.e. File Mode:
<literal>r</literal>, and/or <literal>+</literal>). The filter
will also be attached to the <literal>write filter chain</literal>
if the file was opened for writing (i.e. File Mode:
<literal>w</literal>, <literal>a</literal>, and/or <literal>+</literal>).
<constant>STREAM_FILTER_READ</constant>,
<constant>STREAM_FILTER_WRITE</constant>, and/or
<constant>STREAM_FILTER_ALL</constant> can also be passed to the
<parameter>read_write</parameter> parameter to override this behavior.
See <function>stream_filter_append</function> for an example of
using this parameter.
</para>
<para>
As of PHP 5.1.0, this function returns a resource which
can be used to refer to this filter instance during a call
to <function>stream_filter_remove</function>.
Prior to PHP 5.1.0, this function returns &true; on success
or &false; on failure.
</para>
<note>
<title>When using custom (user) filters</title>
<simpara>
<function>stream_filter_register</function> must be called first
in order to register the desired user filter to <parameter>filtername</parameter>.
</simpara>
</note>
<note>
<simpara>
Stream data is read from resources (both local and remote) in chunks,
with any unconsumed data kept in internal buffers. When a new
filter is prepended to a stream, data in the internal buffers,
which has already been processed through other filters will
<emphasis>not</emphasis> be reprocessed through the new filter
at that time. This differs from the behavior of
<function>stream_filter_append</function>.
</simpara>
</note>
<simpara>
See also
<function>stream_filter_register</function>, and
<function>stream_filter_append</function>.
</simpara>
</refsect1>
</refentry>
<!-- $Revision: 1.13 $ -->
<refentry xml:id="function.stream-filter-prepend" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_prepend</refname>
<refpurpose>Attach a filter to a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_filter_prepend</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>read_write</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Adds <parameter>filtername</parameter> to the list of filters
attached to <parameter>stream</parameter>. This filter will be
added with the specified <parameter>params</parameter>
to the <emphasis>beginning</emphasis> of the list and
will therefore be called first during stream operations. To
add a filter to the end of the list, use
<function>stream_filter_append</function>.
</para>
<para>
By default, <function>stream_filter_prepend</function> will
attach the filter to the <literal>read filter chain</literal>
if the file was opened for reading (i.e. File Mode:
<literal>r</literal>, and/or <literal>+</literal>). The filter
will also be attached to the <literal>write filter chain</literal>
if the file was opened for writing (i.e. File Mode:
<literal>w</literal>, <literal>a</literal>, and/or <literal>+</literal>).
<constant>STREAM_FILTER_READ</constant>,
<constant>STREAM_FILTER_WRITE</constant>, and/or
<constant>STREAM_FILTER_ALL</constant> can also be passed to the
<parameter>read_write</parameter> parameter to override this behavior.
See <function>stream_filter_append</function> for an example of
using this parameter.
</para>
<para>
As of PHP 5.1.0, this function returns a resource which
can be used to refer to this filter instance during a call
to <function>stream_filter_remove</function>.
Prior to PHP 5.1.0, this function returns &true; on success
or &false; on failure.
</para>
<note>
<title>When using custom (user) filters</title>
<simpara>
<function>stream_filter_register</function> must be called first
in order to register the desired user filter to <parameter>filtername</parameter>.
</simpara>
</note>
<note>
<simpara>
Stream data is read from resources (both local and remote) in chunks,
with any unconsumed data kept in internal buffers. When a new
filter is prepended to a stream, data in the internal buffers,
which has already been processed through other filters will
<emphasis>not</emphasis> be reprocessed through the new filter
at that time. This differs from the behavior of
<function>stream_filter_append</function>.
</simpara>
</note>
<simpara>
See also
<function>stream_filter_register</function>, and
<function>stream_filter_append</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

357
reference/stream/functions/stream-filter-register.xml
View file

@ -1,166 +1,163 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<refentry xml:id="function.stream-filter-register" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_register</refname>
<refpurpose>
Register a stream filter implemented as a PHP class
derived from <literal>php_user_filter</literal>
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_filter_register</methodname>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam><type>string</type><parameter>classname</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_filter_register</function> allows you to implement
your own filter on any registered stream used with all the other
filesystem functions (such as <function>fopen</function>,
<function>fread</function> etc.).
</para>
<para>
To implement a filter, you need to define a class as an extension of
<literal>php_user_filter</literal> with a number of member functions
as defined below. When performing read/write operations on the stream
to which your filter is attached, PHP will pass the data through your
filter (and any other filters attached to that stream) so that the
data may be modified as desired. You must implement the methods
exactly as described below - doing otherwise will lead to undefined
behaviour.
</para>
<para>
<function>stream_filter_register</function> will return &false; if the
<parameter>filtername</parameter> is already defined.
</para>
<!-- $Revision: 1.14 $ -->
<refentry xml:id="function.stream-filter-register" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_register</refname>
<refpurpose>Register a stream filter implemented as a PHP class derived from <literal>php_user_filter</literal></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_filter_register</methodname>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam><type>string</type><parameter>classname</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_filter_register</function> allows you to implement
your own filter on any registered stream used with all the other
filesystem functions (such as <function>fopen</function>,
<function>fread</function> etc.).
</para>
<para>
To implement a filter, you need to define a class as an extension of
<literal>php_user_filter</literal> with a number of member functions
as defined below. When performing read/write operations on the stream
to which your filter is attached, PHP will pass the data through your
filter (and any other filters attached to that stream) so that the
data may be modified as desired. You must implement the methods
exactly as described below - doing otherwise will lead to undefined
behaviour.
</para>
<para>
<function>stream_filter_register</function> will return &false; if the
<parameter>filtername</parameter> is already defined.
</para>
<methodsynopsis>
<type>int</type><methodname>filter</methodname>
<methodparam><type>resource</type><parameter>in</parameter></methodparam>
<methodparam><type>resource</type><parameter>out</parameter></methodparam>
<methodparam><type>int</type><parameter role="reference">consumed</parameter></methodparam>
<methodparam><type>bool</type><parameter>closing</parameter></methodparam>
</methodsynopsis>
<para>
This method is called whenever data is read from or written to
the attached stream (such as with <function>fread</function> or <function>fwrite</function>).
<parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal>
which contains one or more <literal>bucket</literal> objects containing data to be filtered.
<parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal>
into which your modified buckets should be placed.
<parameter>consumed</parameter>, which must <emphasis>always</emphasis>
be declared by reference, should be incremented by the length of the data
which your filter reads in and alters. In most cases this means you will
increment <parameter>consumed</parameter> by $bucket->datalen for each $bucket.
If the stream is in the process of closing (and therefore this is the last pass
through the filterchain), the <parameter>closing</parameter> parameter will be
set to &true; The <methodname>filter</methodname> method must return one of
three values upon completion.
<methodsynopsis>
<type>int</type><methodname>filter</methodname>
<methodparam><type>resource</type><parameter>in</parameter></methodparam>
<methodparam><type>resource</type><parameter>out</parameter></methodparam>
<methodparam><type>int</type><parameter role="reference">consumed</parameter></methodparam>
<methodparam><type>bool</type><parameter>closing</parameter></methodparam>
</methodsynopsis>
<para>
This method is called whenever data is read from or written to
the attached stream (such as with <function>fread</function> or <function>fwrite</function>).
<parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal>
which contains one or more <literal>bucket</literal> objects containing data to be filtered.
<parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal>
into which your modified buckets should be placed.
<parameter>consumed</parameter>, which must <emphasis>always</emphasis>
be declared by reference, should be incremented by the length of the data
which your filter reads in and alters. In most cases this means you will
increment <parameter>consumed</parameter> by $bucket->datalen for each $bucket.
If the stream is in the process of closing (and therefore this is the last pass
through the filterchain), the <parameter>closing</parameter> parameter will be
set to &true; The <methodname>filter</methodname> method must return one of
three values upon completion.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Return Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>PSFS_PASS_ON</constant></entry>
<entry>
Filter processed successfully with data available in the
<parameter>out</parameter> <literal>bucket brigade</literal>.
</entry>
</row>
<row>
<entry><constant>PSFS_FEED_ME</constant></entry>
<entry>
Filter processed successfully, however no data was available to
return. More data is required from the stream or prior filter.
</entry>
</row>
<row>
<entry><constant>PSFS_ERR_FATAL</constant> (default)</entry>
<entry>
The filter experienced an unrecoverable error and cannot continue.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Return Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>PSFS_PASS_ON</constant></entry>
<entry>
Filter processed successfully with data available in the
<parameter>out</parameter> <literal>bucket brigade</literal>.
</entry>
</row>
<row>
<entry><constant>PSFS_FEED_ME</constant></entry>
<entry>
Filter processed successfully, however no data was available to
return. More data is required from the stream or prior filter.
</entry>
</row>
<row>
<entry><constant>PSFS_ERR_FATAL</constant> (default)</entry>
<entry>
The filter experienced an unrecoverable error and cannot continue.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<methodsynopsis>
<type>bool</type><methodname>onCreate</methodname>
<void/>
</methodsynopsis>
<simpara>
This method is called during instantiation of the filter class
object. If your filter allocates or initializes any other resources
(such as a buffer), this is the place to do it. Your implementation of
this method should return &false; on failure, or &true; on success.
</simpara>
<simpara>
When your filter is first instantiated, and
<literal>yourfilter-&gt;onCreate()</literal> is called, a number of properties
will be available as shown in the table below.
</simpara>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Property</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>FilterClass-&gt;filtername</literal></entry>
<entry>A string containing the name the filter was instantiated with.
Filters may be registered under multiple names or under wildcards.
Use this property to determine which name was used.</entry>
</row>
<row>
<entry><literal>FilterClass-&gt;params</literal></entry>
<entry>The contents of the <parameter>params</parameter> parameter passed
to <function>stream_filter_append</function>
or <function>stream_filter_prepend</function>.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<methodsynopsis>
<type>bool</type><methodname>onCreate</methodname>
<void/>
</methodsynopsis>
<simpara>
This method is called during instantiation of the filter class
object. If your filter allocates or initializes any other resources
(such as a buffer), this is the place to do it. Your implementation of
this method should return &false; on failure, or &true; on success.
</simpara>
<simpara>
When your filter is first instantiated, and
<literal>yourfilter-&gt;onCreate()</literal> is called, a number of properties
will be available as shown in the table below.
</simpara>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Property</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>FilterClass-&gt;filtername</literal></entry>
<entry>A string containing the name the filter was instantiated with.
Filters may be registered under multiple names or under wildcards.
Use this property to determine which name was used.</entry>
</row>
<row>
<entry><literal>FilterClass-&gt;params</literal></entry>
<entry>The contents of the <parameter>params</parameter> parameter passed
to <function>stream_filter_append</function>
or <function>stream_filter_prepend</function>.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<methodsynopsis>
<type>void</type><methodname>onClose</methodname>
<void/>
</methodsynopsis>
<para>
This method is called upon filter shutdown (typically, this is also
during stream shutdown), and is executed <emphasis>after</emphasis>
the <literal>flush</literal> method is called. If any resources
were allocated or initialzed during <literal>onCreate</literal>
this would be the time to destroy or dispose of them.
</para>
<methodsynopsis>
<type>void</type><methodname>onClose</methodname>
<void/>
</methodsynopsis>
<para>
This method is called upon filter shutdown (typically, this is also
during stream shutdown), and is executed <emphasis>after</emphasis>
the <literal>flush</literal> method is called. If any resources
were allocated or initialzed during <literal>onCreate</literal>
this would be the time to destroy or dispose of them.
</para>
<para>
The example below implements a filter named <literal>strtoupper</literal>
on the <literal>foo-bar.txt</literal> stream which will capitalize
all letter characters written to/read from that stream.
<para>
The example below implements a filter named <literal>strtoupper</literal>
on the <literal>foo-bar.txt</literal> stream which will capitalize
all letter characters written to/read from that stream.
<example>
<title>Filter for capitalizing characters on foo-bar.txt stream</title>
<programlisting role="php">
<example>
<title>Filter for capitalizing characters on foo-bar.txt stream</title>
<programlisting role="php">
<![CDATA[
<?php
/* Define our filter class */
class strtoupper_filter extends php_user_filter {
function filter($in, $out, &$consumed, $closing)
function filter($in, $out, &$consumed, $closing)
{
while ($bucket = stream_bucket_make_writeable($in)) {
$bucket->data = strtoupper($bucket->data);
@ -169,7 +166,7 @@ class strtoupper_filter extends php_user_filter {
}
return PSFS_PASS_ON;
}
}
}
/* Register our filter with PHP */
stream_filter_register("strtoupper", "strtoupper_filter")
@ -192,21 +189,21 @@ readfile("foo-bar.txt");
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
LINE1
WORD - 2
EASY AS 123
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Registering a generic filter class to match multiple filter names.</title>
<programlisting role="php">
</screen>
</example>
</para>
<para>
<example>
<title>Registering a generic filter class to match multiple filter names.</title>
<programlisting role="php">
<![CDATA[
<?php
@ -214,7 +211,7 @@ EASY AS 123
class string_filter extends php_user_filter {
var $mode;
function filter($in, $out, &$consumed, $closing)
function filter($in, $out, &$consumed, $closing)
{
while ($bucket = stream_bucket_make_writeable($in)) {
if ($this->mode == 1) {
@ -229,7 +226,7 @@ class string_filter extends php_user_filter {
return PSFS_PASS_ON;
}
function onCreate()
function onCreate()
{
if ($this->filtername == 'str.toupper') {
$this->mode = 1;
@ -243,7 +240,7 @@ class string_filter extends php_user_filter {
return true;
}
}
}
/* Register our filter with PHP */
stream_filter_register("str.*", "string_filter")
@ -251,7 +248,7 @@ stream_filter_register("str.*", "string_filter")
$fp = fopen("foo-bar.txt", "w");
/* Attach the registered filter to the stream just opened
/* Attach the registered filter to the stream just opened
We could alternately bind to str.tolower here */
stream_filter_append($fp, "str.toupper");
@ -266,26 +263,26 @@ fclose($fp);
readfile("foo-bar.txt");
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
LINE1
WORD - 2
EASY AS 123
]]>
</screen>
</example>
</para>
</screen>
</example>
</para>
<simpara>
See also
<function>stream_wrapper_register</function>,
<function>stream_filter_prepend</function>, and
<function>stream_filter_append</function>.
</simpara>
</refsect1>
</refentry>
<simpara>
See also
<function>stream_wrapper_register</function>,
<function>stream_filter_prepend</function>, and
<function>stream_filter_append</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

68
reference/stream/functions/stream-filter-remove.xml
View file

@ -1,27 +1,27 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<refentry xml:id="function.stream-filter-remove" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_remove</refname>
<refpurpose>Remove a filter from a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_filter_remove</methodname>
<methodparam><type>resource</type><parameter>stream_filter</parameter></methodparam>
</methodsynopsis>
<simpara>
Removes a stream filter previously added to a stream
with <function>stream_filter_prepend</function> or
<function>stream_filter_append</function>. Any data
remaining in the filter's internal buffer will be flushed
through to the next filter before removing it.
</simpara>
<para>
<example>
<title>Dynamicly refiltering a stream</title>
<programlisting role="php">
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-filter-remove" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_remove</refname>
<refpurpose>Remove a filter from a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_filter_remove</methodname>
<methodparam><type>resource</type><parameter>stream_filter</parameter></methodparam>
</methodsynopsis>
<simpara>
Removes a stream filter previously added to a stream
with <function>stream_filter_prepend</function> or
<function>stream_filter_append</function>. Any data
remaining in the filter's internal buffer will be flushed
through to the next filter before removing it.
</simpara>
<para>
<example>
<title>Dynamicly refiltering a stream</title>
<programlisting role="php">
<![CDATA[
<?php
/* Open a test file for reading and writing */
@ -44,17 +44,17 @@ Guvf vf a test
*/
?>
]]>
</programlisting>
</example>
</para>
<simpara>
See also
<function>stream_filter_register</function>,
<function>stream_filter_append</function>, and
<function>stream_filter_prepend</function>.
</simpara>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<simpara>
See also
<function>stream_filter_register</function>,
<function>stream_filter_append</function>, and
<function>stream_filter_prepend</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

158
reference/stream/functions/stream-get-contents.xml
View file

@ -1,70 +1,70 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<refentry xml:id="function.stream-get-contents" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_contents</refname>
<refpurpose>Reads remainder of a stream into a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_get_contents</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>maxlength</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Identical to <function>file_get_contents</function>, except that
<function>stream_get_contents</function> operates on an already open
stream resource and returns the remaining contents in a string, up to
<parameter>maxlength</parameter> bytes and starting at the specified
<parameter>offset</parameter>.
</para>
</refsect1>
<!-- $Revision: 1.7 $ -->
<refentry xml:id="function.stream-get-contents" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_contents</refname>
<refpurpose>Reads remainder of a stream into a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_get_contents</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>maxlength</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Identical to <function>file_get_contents</function>, except that
<function>stream_get_contents</function> operates on an already open
stream resource and returns the remaining contents in a string, up to
<parameter>maxlength</parameter> bytes and starting at the specified
<parameter>offset</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter> (<type>resource</type>)</term>
<listitem>
<para>
A stream resource (e.g. returned from <function>fopen</function>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>maxlength</parameter> (<type>integer</type>)</term>
<listitem>
<para>
The maximum bytes to read. Defaults to -1 (read all the remaining
buffer).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter> (<type>integer</type>)</term>
<listitem>
<para>
Seek to the specified offset before reading. Added in PHP 5.1.0.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>handle</parameter> (<type>resource</type>)</term>
<listitem>
<para>
A stream resource (e.g. returned from <function>fopen</function>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>maxlength</parameter> (<type>integer</type>)</term>
<listitem>
<para>
The maximum bytes to read. Defaults to -1 (read all the remaining
buffer).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter> (<type>integer</type>)</term>
<listitem>
<para>
Seek to the specified offset before reading. Added in PHP 5.1.0.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string, or &false; on failure.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string, or &false; on failure.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>stream_get_contents</function> example</title>
<programlisting role="php">
@ -88,23 +88,23 @@ if ($stream = fopen('http://www.example.net', 'r')) {
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>fgets</function></member>
<member><function>fread</function></member>
<member><function>fpassthru</function></member>
</simplelist>
</para>
&note.bin-safe;
</refsect1>
</refentry>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>fgets</function></member>
<member><function>fread</function></member>
<member><function>fpassthru</function></member>
</simplelist>
</para>
&note.bin-safe;
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

72
reference/stream/functions/stream-get-filters.xml
View file

@ -1,36 +1,36 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<refentry xml:id="function.stream-get-filters" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_filters</refname>
<refpurpose>Retrieve list of registered filters</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_filters</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns an indexed array containing the name of all stream filters
available on the running system.
</simpara>
<para>
<example>
<title>Using <function>stream_get_filters</function></title>
<programlisting role="php">
<!-- $Revision: 1.9 $ -->
<refentry xml:id="function.stream-get-filters" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_filters</refname>
<refpurpose>Retrieve list of registered filters</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_filters</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns an indexed array containing the name of all stream filters
available on the running system.
</simpara>
<para>
<example>
<title>Using <function>stream_get_filters</function></title>
<programlisting role="php">
<![CDATA[
<?php
$streamlist = stream_get_filters();
print_r($streamlist);
?>
]]>
</programlisting>
<para>
Output will be similar to the following.
Note: there may be more or fewer filters in your version of PHP.
</para>
<screen>
</programlisting>
<para>
Output will be similar to the following.
Note: there may be more or fewer filters in your version of PHP.
</para>
<screen>
<![CDATA[
Array (
[0] => string.rot13
@ -40,16 +40,16 @@ Array (
[4] => string.quoted-printable
)
]]>
</screen>
</example>
</para>
<para>
See also
<function>stream_filter_register</function>, and
<function>stream_get_wrappers</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<para>
See also
<function>stream_filter_register</function>, and
<function>stream_get_wrappers</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

74
reference/stream/functions/stream-get-line.xml
View file

@ -1,41 +1,41 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-get-line" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_line</refname>
<refpurpose>Gets line from stream resource up to a given delimiter</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_get_line</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>ending</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string of up to <parameter>length</parameter> bytes read from the file
pointed to by <parameter>handle</parameter>. Reading ends when
<parameter>length</parameter> bytes have been read, when the string specified by
<parameter>ending</parameter> is found (which is <emphasis>not</emphasis> included
in the return value), or on EOF (whichever comes first).
</para>
<para>
If an error occurs, returns &false;.
</para>
<simpara>
This function is nearly identical to <function>fgets</function>
except in that it allows end of line delimiters other than the
standard \n, \r, and \r\n, and does <emphasis>not</emphasis>
return the delimiter itself.
</simpara>
<para>
See also <function>fread</function>,
<function>fgets</function>, and
<function>fgetc</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.6 $ -->
<refentry xml:id="function.stream-get-line" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_line</refname>
<refpurpose>Gets line from stream resource up to a given delimiter</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_get_line</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>ending</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string of up to <parameter>length</parameter> bytes read from the file
pointed to by <parameter>handle</parameter>. Reading ends when
<parameter>length</parameter> bytes have been read, when the string specified by
<parameter>ending</parameter> is found (which is <emphasis>not</emphasis> included
in the return value), or on EOF (whichever comes first).
</para>
<para>
If an error occurs, returns &false;.
</para>
<simpara>
This function is nearly identical to <function>fgets</function>
except in that it allows end of line delimiters other than the
standard \n, \r, and \r\n, and does <emphasis>not</emphasis>
return the delimiter itself.
</simpara>
<para>
See also <function>fread</function>,
<function>fgets</function>, and
<function>fgetc</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

250
reference/stream/functions/stream-get-meta-data.xml
View file

@ -1,132 +1,132 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<refentry xml:id="function.stream-get-meta-data" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_meta_data</refname>
<refpurpose>Retrieves header/meta data from streams/file pointers</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_meta_data</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns information about an existing <parameter>stream</parameter>.
The stream can be any stream created by <function>fopen</function>,
<function>fsockopen</function> and <function>pfsockopen</function>.
The result array contains the following items:
</simpara>
<itemizedlist>
<listitem>
<para>
<parameter>timed_out</parameter> (bool) - &true; if the stream
timed out while waiting for data on the last call to
<function>fread</function> or <function>fgets</function>.
</para>
</listitem>
<listitem>
<para>
<parameter>blocked</parameter> (bool) - &true; if the stream is
in blocking IO mode. See <function>stream_set_blocking</function>.
</para>
</listitem>
<listitem>
<para>
<parameter>eof</parameter> (bool) - &true; if the stream has reached
end-of-file. Note that for socket streams this member can be &true;
even when <parameter>unread_bytes</parameter> is non-zero. To
determine if there is more data to be read, use
<function>feof</function> instead of reading this item.
</para>
</listitem>
<listitem>
<para>
<parameter>unread_bytes</parameter> (int) - the number of bytes
currently contained in the PHP's own internal buffer.
</para>
<note>
<simpara>
You shouldn't use this value in a script.
</simpara>
</note>
</listitem>
</itemizedlist>
<simpara>
The following items were added in PHP 4.3.0:
</simpara>
<itemizedlist>
<listitem>
<para>
<parameter>stream_type</parameter> (string) - a label describing
the underlying implementation of the stream.
</para>
</listitem>
<listitem>
<para>
<parameter>wrapper_type</parameter> (string) - a label describing
the protocol wrapper implementation layered over the stream.
See <xref linkend="wrappers"/> for more information about wrappers.
</para>
</listitem>
<listitem>
<para>
<parameter>wrapper_data</parameter> (mixed) - wrapper specific
data attached to this stream. See <xref linkend="wrappers"/> for
more information about wrappers and their wrapper data.
</para>
</listitem>
<listitem>
<para>
<parameter>filters</parameter> (array) - and array containing
the names of any filters that have been stacked onto this stream.
Documentation on filters can be found in the
<link linkend="filters">Filters appendix</link>.
</para>
</listitem>
</itemizedlist>
<!-- $Revision: 1.11 $ -->
<refentry xml:id="function.stream-get-meta-data" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_meta_data</refname>
<refpurpose>Retrieves header/meta data from streams/file pointers</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_meta_data</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns information about an existing <parameter>stream</parameter>.
The stream can be any stream created by <function>fopen</function>,
<function>fsockopen</function> and <function>pfsockopen</function>.
The result array contains the following items:
</simpara>
<itemizedlist>
<listitem>
<para>
<parameter>timed_out</parameter> (bool) - &true; if the stream
timed out while waiting for data on the last call to
<function>fread</function> or <function>fgets</function>.
</para>
</listitem>
<listitem>
<para>
<parameter>blocked</parameter> (bool) - &true; if the stream is
in blocking IO mode. See <function>stream_set_blocking</function>.
</para>
</listitem>
<listitem>
<para>
<parameter>eof</parameter> (bool) - &true; if the stream has reached
end-of-file. Note that for socket streams this member can be &true;
even when <parameter>unread_bytes</parameter> is non-zero. To
determine if there is more data to be read, use
<function>feof</function> instead of reading this item.
</para>
</listitem>
<listitem>
<para>
<parameter>unread_bytes</parameter> (int) - the number of bytes
currently contained in the PHP's own internal buffer.
</para>
<note>
<para>
This function was introduced in PHP 4.3.0, but prior to this version,
<function>socket_get_status</function> could be used to retrieve
the first four items, for <emphasis>socket based streams only</emphasis>.
</para>
<para>
In PHP 4.3.0 and later,
<function>socket_get_status</function> is an alias for this function.
</para>
</note>
<note>
<simpara>This function does NOT work on sockets created by the <link
linkend="ref.sockets">Socket extension</link>.
<simpara>
You shouldn't use this value in a script.
</simpara>
</note>
<simpara>
The following items were added in PHP 5.0.0:
</simpara>
<itemizedlist>
<listitem>
<para>
<parameter>mode</parameter> (string) - the type of access required for
this stream (see Table 1 of the <link
linkend="function.fopen">fopen()</link> reference)
</para>
</listitem>
<listitem>
<para>
<parameter>seekable</parameter> (bool) - whether the current stream can
be seeked.
</para>
</listitem>
<listitem>
<para>
<parameter>uri</parameter> (string) - the URI/filename associated with this
stream.
</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>
</listitem>
</itemizedlist>
<simpara>
The following items were added in PHP 4.3.0:
</simpara>
<itemizedlist>
<listitem>
<para>
<parameter>stream_type</parameter> (string) - a label describing
the underlying implementation of the stream.
</para>
</listitem>
<listitem>
<para>
<parameter>wrapper_type</parameter> (string) - a label describing
the protocol wrapper implementation layered over the stream.
See <xref linkend="wrappers"/> for more information about wrappers.
</para>
</listitem>
<listitem>
<para>
<parameter>wrapper_data</parameter> (mixed) - wrapper specific
data attached to this stream. See <xref linkend="wrappers"/> for
more information about wrappers and their wrapper data.
</para>
</listitem>
<listitem>
<para>
<parameter>filters</parameter> (array) - and array containing
the names of any filters that have been stacked onto this stream.
Documentation on filters can be found in the
<link linkend="filters">Filters appendix</link>.
</para>
</listitem>
</itemizedlist>
<note>
<para>
This function was introduced in PHP 4.3.0, but prior to this version,
<function>socket_get_status</function> could be used to retrieve
the first four items, for <emphasis>socket based streams only</emphasis>.
</para>
<para>
In PHP 4.3.0 and later,
<function>socket_get_status</function> is an alias for this function.
</para>
</note>
<note>
<simpara>This function does NOT work on sockets created by the <link
linkend="ref.sockets">Socket extension</link>.
</simpara>
</note>
<simpara>
The following items were added in PHP 5.0.0:
</simpara>
<itemizedlist>
<listitem>
<para>
<parameter>mode</parameter> (string) - the type of access required for
this stream (see Table 1 of the <link
linkend="function.fopen">fopen()</link> reference)
</para>
</listitem>
<listitem>
<para>
<parameter>seekable</parameter> (bool) - whether the current stream can
be seeked.
</para>
</listitem>
<listitem>
<para>
<parameter>uri</parameter> (string) - the URI/filename associated with this
stream.
</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

72
reference/stream/functions/stream-get-transports.xml
View file

@ -1,36 +1,36 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-get-transports" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_transports</refname>
<refpurpose>Retrieve list of registered socket transports</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_transports</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns an indexed array containing the name of all socket transports
available on the running system.
</simpara>
<para>
<example>
<title>Using <function>stream_get_transports</function></title>
<programlisting role="php">
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-get-transports" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_transports</refname>
<refpurpose>Retrieve list of registered socket transports</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_transports</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns an indexed array containing the name of all socket transports
available on the running system.
</simpara>
<para>
<example>
<title>Using <function>stream_get_transports</function></title>
<programlisting role="php">
<![CDATA[
<?php
$xportlist = stream_get_transports();
print_r($xportlist);
?>
]]>
</programlisting>
<para>
Output will be similar to the following.
Note: there may be more or fewer transports in your version of PHP.
</para>
<screen>
</programlisting>
<para>
Output will be similar to the following.
Note: there may be more or fewer transports in your version of PHP.
</para>
<screen>
<![CDATA[
Array (
[0] => tcp
@ -39,16 +39,16 @@ Array (
[3] => udg
)
]]>
</screen>
</example>
</para>
<para>
See also
<function>stream_get_filters</function>, and
<function>stream_get_wrappers</function>.
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
<para>
See also
<function>stream_get_filters</function>, and
<function>stream_get_wrappers</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

78
reference/stream/functions/stream-get-wrappers.xml
View file

@ -1,32 +1,32 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<refentry xml:id="function.stream-get-wrappers" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_wrappers</refname>
<refpurpose>Retrieve list of registered streams</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_wrappers</methodname>
<void/>
</methodsynopsis>
<para>
Returns an indexed array containing the name of all stream wrappers
available on the running system.
</para>
<para>
<example>
<title><function>stream_get_wrappers</function> example</title>
<programlisting role="php">
<!-- $Revision: 1.7 $ -->
<refentry xml:id="function.stream-get-wrappers" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_get_wrappers</refname>
<refpurpose>Retrieve list of registered streams</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_wrappers</methodname>
<void/>
</methodsynopsis>
<para>
Returns an indexed array containing the name of all stream wrappers
available on the running system.
</para>
<para>
<example>
<title><function>stream_get_wrappers</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
print_r(stream_get_wrappers());
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
@ -38,13 +38,13 @@ Array
[5] => compress.zlib
)
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Checking for the existence of a stream wrapper</title>
<programlisting role="php">
</screen>
</example>
</para>
<para>
<example>
<title>Checking for the existence of a stream wrapper</title>
<programlisting role="php">
<![CDATA[
<?php
// check for the existence of the bzip2 stream wrapper
@ -55,15 +55,15 @@ if (in_array('compress.bzip2', stream_get_wrappers())) {
}
?>
]]>
</programlisting>
</example>
</para>
<para>
See also
<function>stream_wrapper_register</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also
<function>stream_wrapper_register</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

30
reference/stream/functions/stream-register-wrapper.xml
View file

@ -1,19 +1,19 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<refentry xml:id="function.stream-register-wrapper" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_register_wrapper</refname>
<refpurpose>Alias of <function>stream_wrapper_register</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
This function is an alias of <function>stream_wrapper_register</function>.
This function is included for compatability with PHP 4.3.0 and PHP 4.3.1
only. <function>stream_wrapper_register</function> should be used instead.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.7 $ -->
<refentry xml:id="function.stream-register-wrapper" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_register_wrapper</refname>
<refpurpose>Alias of <function>stream_wrapper_register</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
This function is an alias of <function>stream_wrapper_register</function>.
This function is included for compatability with PHP 4.3.0 and PHP 4.3.1
only. <function>stream_wrapper_register</function> should be used instead.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

294
reference/stream/functions/stream-select.xml
View file

@ -1,104 +1,104 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_select</refname>
<refpurpose>Runs the equivalent of the select() system call on the given
arrays of streams with a timeout specified by tv_sec and tv_usec </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_select</methodname>
<methodparam><type>array</type><parameter role="reference">read</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">write</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">except</parameter></methodparam>
<methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>stream_select</function> function accepts arrays of streams and
waits for them to change status. Its operation is equivalent to that of
the <function>socket_select</function> function except in that it acts on streams.
</simpara>
<simpara>
The streams listed in the <parameter>read</parameter> array will be watched to
see if characters become available for reading (more precisely, to see if
a read will not block - in particular, a stream resource is also ready on
end-of-file, in which case an <function>fread</function> will return
a zero length string).
</simpara>
<simpara>
The streams listed in the <parameter>write</parameter> array will be
watched to see if a write will not block.
</simpara>
<simpara>
The streams listed in the <parameter>except</parameter> array will be
watched for high priority exceptional ("out-of-band") data arriving.
</simpara>
<note>
<para>
When <function>stream_select</function> returns, the arrays
<parameter>read</parameter>, <parameter>write</parameter> and
<parameter>except</parameter> are modified to indicate which stream
resource(s) actually changed status.
</para>
</note>
<simpara>
The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter>
together form the <emphasis>timeout</emphasis> parameter,
<parameter>tv_sec</parameter> specifies the number of seconds while
<parameter>tv_usec</parameter> the number of microseconds.
The <emphasis>timeout</emphasis> is an upper bound on the amount of time
that <function>stream_select</function> will wait before it returns.
If <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter> are
both set to <literal>0</literal>, <function>stream_select</function> will
not wait for data - instead it will return immediately, indicating the
current status of the streams.
If <parameter>tv_sec</parameter> is &null; <function>stream_select</function>
can block indefinitely, returning only when an event on one of the
watched streams occurs (or if a signal interrupts the system call).
</simpara>
<simpara>
On success <function>stream_select</function> returns the number of
stream resources contained in the modified arrays, which may be zero if
the timeout expires before anything interesting happens. On error &false;
is returned and a warning raised (this can happen if the system call is
interrupted by an incoming signal).
</simpara>
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.stream-select" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_select</refname>
<refpurpose>Runs the equivalent of the select() system call on the given
arrays of streams with a timeout specified by tv_sec and tv_usec </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_select</methodname>
<methodparam><type>array</type><parameter role="reference">read</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">write</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">except</parameter></methodparam>
<methodparam><type>int</type><parameter>tv_sec</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>tv_usec</parameter></methodparam>
</methodsynopsis>
<simpara>
The <function>stream_select</function> function accepts arrays of streams and
waits for them to change status. Its operation is equivalent to that of
the <function>socket_select</function> function except in that it acts on streams.
</simpara>
<simpara>
The streams listed in the <parameter>read</parameter> array will be watched to
see if characters become available for reading (more precisely, to see if
a read will not block - in particular, a stream resource is also ready on
end-of-file, in which case an <function>fread</function> will return
a zero length string).
</simpara>
<simpara>
The streams listed in the <parameter>write</parameter> array will be
watched to see if a write will not block.
</simpara>
<simpara>
The streams listed in the <parameter>except</parameter> array will be
watched for high priority exceptional ("out-of-band") data arriving.
</simpara>
<note>
<para>
When <function>stream_select</function> returns, the arrays
<parameter>read</parameter>, <parameter>write</parameter> and
<parameter>except</parameter> are modified to indicate which stream
resource(s) actually changed status.
</para>
</note>
<simpara>
The <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter>
together form the <emphasis>timeout</emphasis> parameter,
<parameter>tv_sec</parameter> specifies the number of seconds while
<parameter>tv_usec</parameter> the number of microseconds.
The <emphasis>timeout</emphasis> is an upper bound on the amount of time
that <function>stream_select</function> will wait before it returns.
If <parameter>tv_sec</parameter> and <parameter>tv_usec</parameter> are
both set to <literal>0</literal>, <function>stream_select</function> will
not wait for data - instead it will return immediately, indicating the
current status of the streams.
If <parameter>tv_sec</parameter> is &null; <function>stream_select</function>
can block indefinitely, returning only when an event on one of the
watched streams occurs (or if a signal interrupts the system call).
</simpara>
<simpara>
On success <function>stream_select</function> returns the number of
stream resources contained in the modified arrays, which may be zero if
the timeout expires before anything interesting happens. On error &false;
is returned and a warning raised (this can happen if the system call is
interrupted by an incoming signal).
</simpara>
<warning>
<para>
Using a timeout value of <literal>0</literal> allows you to
instantaneously poll the status of the streams, however, it is NOT a
good idea to use a <literal>0</literal> timeout value in a loop as it
will cause your script to consume too much CPU time.
</para>
<para>
It is much better to specify a timeout value of a few seconds, although
if you need to be checking and running other code concurrently, using a
timeout value of at least <literal>200000</literal> microseconds will
help reduce the CPU usage of your script.
</para>
<para>
Remember that the timeout value is the
maximum time that will elapse; <function>stream_select</function> will
return as soon as the requested streams are ready for use.
</para>
</warning>
<simpara>
You do not need to pass every array to
<function>stream_select</function>. You can leave it out and use an
empty array or &null; instead. Also do not forget that those arrays are
passed <emphasis>by reference</emphasis> and will be modified after
<function>stream_select</function> returns.
</simpara>
<para>
This example checks to see if data has arrived for reading on either
<parameter>$stream1</parameter> or <parameter>$stream2</parameter>.
Since the timeout value is <literal>0</literal> it will return
immediately:
<programlisting role="php">
<warning>
<para>
Using a timeout value of <literal>0</literal> allows you to
instantaneously poll the status of the streams, however, it is NOT a
good idea to use a <literal>0</literal> timeout value in a loop as it
will cause your script to consume too much CPU time.
</para>
<para>
It is much better to specify a timeout value of a few seconds, although
if you need to be checking and running other code concurrently, using a
timeout value of at least <literal>200000</literal> microseconds will
help reduce the CPU usage of your script.
</para>
<para>
Remember that the timeout value is the
maximum time that will elapse; <function>stream_select</function> will
return as soon as the requested streams are ready for use.
</para>
</warning>
<simpara>
You do not need to pass every array to
<function>stream_select</function>. You can leave it out and use an
empty array or &null; instead. Also do not forget that those arrays are
passed <emphasis>by reference</emphasis> and will be modified after
<function>stream_select</function> returns.
</simpara>
<para>
This example checks to see if data has arrived for reading on either
<parameter>$stream1</parameter> or <parameter>$stream2</parameter>.
Since the timeout value is <literal>0</literal> it will return
immediately:
<programlisting role="php">
<![CDATA[
<?php
/* Prepare the read array */
@ -112,31 +112,31 @@ if (false === ($num_changed_streams = stream_select($read, $write, $except, 0)))
}
?>
]]>
</programlisting>
</para>
<note>
<para>
Due to a limitation in the current Zend Engine it is not possible to pass a
constant modifier like &null; directly as a parameter to a function
which expects this parameter to be passed by reference. Instead use a
temporary variable or an expression with the leftmost member being a
temporary variable:
<programlisting role="php">
</programlisting>
</para>
<note>
<para>
Due to a limitation in the current Zend Engine it is not possible to pass a
constant modifier like &null; directly as a parameter to a function
which expects this parameter to be passed by reference. Instead use a
temporary variable or an expression with the leftmost member being a
temporary variable:
<programlisting role="php">
<![CDATA[
<?php
$e = NULL;
stream_select($r, $w, $e, 0);
?>
]]>
</programlisting>
</para>
</note>
<note>
<para>
Be sure to use the <literal>===</literal> operator when checking for an
error. Since the <function>stream_select</function> may return 0 the
comparison with <literal>==</literal> would evaluate to &true;:
<programlisting role="php">
</programlisting>
</para>
</note>
<note>
<para>
Be sure to use the <literal>===</literal> operator when checking for an
error. Since the <function>stream_select</function> may return 0 the
comparison with <literal>==</literal> would evaluate to &true;:
<programlisting role="php">
<![CDATA[
<?php
$e = NULL;
@ -145,35 +145,35 @@ if (false === stream_select($r, $w, $e, 0)) {
}
?>
]]>
</programlisting>
</para>
</note>
<note>
<para>
If you read/write to a stream returned in the arrays be aware that
they do not necessarily read/write the full amount of data you have
requested. Be prepared to even only be able to read/write a single
byte.
</para>
</note>
<note>
<para>
Windows compatibility: <function>stream_select</function> used on a
pipe returned from <function>proc_open</function> may cause data loss
under Windows 98.
</para>
<para>
Use of <function>stream_select</function> on
file descriptors returned by <function>proc_open</function> will fail
and return &false; under Windows.
</para>
</note>
<para>
See also
<function>stream_set_blocking</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</para>
</note>
<note>
<para>
If you read/write to a stream returned in the arrays be aware that
they do not necessarily read/write the full amount of data you have
requested. Be prepared to even only be able to read/write a single
byte.
</para>
</note>
<note>
<para>
Windows compatibility: <function>stream_select</function> used on a
pipe returned from <function>proc_open</function> may cause data loss
under Windows 98.
</para>
<para>
Use of <function>stream_select</function> on
file descriptors returned by <function>proc_open</function> will fail
and return &false; under Windows.
</para>
</note>
<para>
See also
<function>stream_set_blocking</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

88
reference/stream/functions/stream-set-blocking.xml
View file

@ -1,49 +1,49 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/network.xml, last change in rev 1.2 -->
<refentry xml:id="function.stream-set-blocking" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_set_blocking</refname>
<refpurpose>Set blocking/non-blocking mode on a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_set_blocking</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
If <parameter>mode</parameter> is 0, the given stream
will be switched to non-blocking mode, and if 1, it
will be switched to blocking mode. This affects calls like
<function>fgets</function> and <function>fread</function>
that read from the stream. In non-blocking mode an
<function>fgets</function> call will always return right away
while in blocking mode it will wait for data to become available
on the stream.
</para>
<para>
&return.success;
</para>
<para>
This function was previously called as
<function>set_socket_blocking</function> and later
<function>socket_set_blocking</function> but this usage is deprecated.
</para>
<note>
<simpara>
Prior to PHP 4.3, this function only worked on socket based streams.
Since PHP 4.3, this function works for any stream that supports
non-blocking mode (currently, regular files and socket streams).
</simpara>
</note>
<para>
See also
<function>stream_select</function>.
</para>
</refsect1>
</refentry>
<refentry xml:id="function.stream-set-blocking" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_set_blocking</refname>
<refpurpose>Set blocking/non-blocking mode on a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_set_blocking</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
If <parameter>mode</parameter> is 0, the given stream
will be switched to non-blocking mode, and if 1, it
will be switched to blocking mode. This affects calls like
<function>fgets</function> and <function>fread</function>
that read from the stream. In non-blocking mode an
<function>fgets</function> call will always return right away
while in blocking mode it will wait for data to become available
on the stream.
</para>
<para>
&return.success;
</para>
<para>
This function was previously called as
<function>set_socket_blocking</function> and later
<function>socket_set_blocking</function> but this usage is deprecated.
</para>
<note>
<simpara>
Prior to PHP 4.3, this function only worked on socket based streams.
Since PHP 4.3, this function works for any stream that supports
non-blocking mode (currently, regular files and socket streams).
</simpara>
</note>
<para>
See also
<function>stream_select</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

116
reference/stream/functions/stream-set-timeout.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/network.xml, last change in rev 1.18 -->
<refentry xml:id="function.stream-set-timeout" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_set_timeout</refname>
<refpurpose>Set timeout period on a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_set_timeout</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>seconds</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>microseconds</parameter></methodparam>
</methodsynopsis>
<para>
Sets the timeout value on <parameter>stream</parameter>,
expressed in the sum of <parameter>seconds</parameter> and
<parameter>microseconds</parameter>. &return.success;
</para>
<para>
When the stream times out, the 'timed_out' key of the array returned by
<function>stream_get_meta_data</function> is set to &true;, although no
error/warning is generated.
</para>
<para>
<example>
<title><function>stream_set_timeout</function> example</title>
<programlisting role="php">
<refentry xml:id="function.stream-set-timeout" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_set_timeout</refname>
<refpurpose>Set timeout period on a stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_set_timeout</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>seconds</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>microseconds</parameter></methodparam>
</methodsynopsis>
<para>
Sets the timeout value on <parameter>stream</parameter>,
expressed in the sum of <parameter>seconds</parameter> and
<parameter>microseconds</parameter>. &return.success;
</para>
<para>
When the stream times out, the 'timed_out' key of the array returned by
<function>stream_get_meta_data</function> is set to &true;, although no
error/warning is generated.
</para>
<para>
<example>
<title><function>stream_set_timeout</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = fsockopen("www.example.com", 80);
@ -51,36 +51,36 @@ if (!$fp) {
}
?>
]]>
</programlisting>
</example>
</para>
<note>
<simpara>
As of PHP 4.3, this function can (potentially) work on any kind of
stream. In PHP 4.3, socket based streams are still the only kind
supported in the PHP core, although streams from other extensions
may support this function.
</simpara>
</note>
<note>
<para>
This function doesn't work with advanced operations like
<function>stream_socket_recvfrom</function>, use
<function>stream_select</function> with timeout parameter instead.
</para>
</note>
<para>
This function was previously called as
<function>set_socket_timeout</function> and later
<function>socket_set_timeout</function> but this usage is deprecated.
</para>
<para>
See also
<function>fsockopen</function> and
<function>fopen</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<note>
<simpara>
As of PHP 4.3, this function can (potentially) work on any kind of
stream. In PHP 4.3, socket based streams are still the only kind
supported in the PHP core, although streams from other extensions
may support this function.
</simpara>
</note>
<note>
<para>
This function doesn't work with advanced operations like
<function>stream_socket_recvfrom</function>, use
<function>stream_select</function> with timeout parameter instead.
</para>
</note>
<para>
This function was previously called as
<function>set_socket_timeout</function> and later
<function>socket_set_timeout</function> but this usage is deprecated.
</para>
<para>
See also
<function>fsockopen</function> and
<function>fopen</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

92
reference/stream/functions/stream-set-write-buffer.xml
View file

@ -1,41 +1,41 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry xml:id="function.stream-set-write-buffer" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_set_write_buffer</refname>
<refpurpose>Sets file buffering on the given stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_set_write_buffer</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>buffer</parameter></methodparam>
</methodsynopsis>
<simpara>
Output using <function>fwrite</function> is normally buffered at
8K. This means that if there are two processes wanting to write
to the same output stream (a file), each is paused after 8K of
data to allow the other to write.
<function>stream_set_write_buffer</function>
sets the buffering for write operations on the given filepointer
<parameter>stream</parameter> to <parameter>buffer</parameter> bytes.
If <parameter>buffer</parameter> is 0 then write operations are
unbuffered. This ensures that all writes with
<function>fwrite</function> are completed before other processes
are allowed to write to that output stream.
</simpara>
<simpara>
The function returns 0 on success, or EOF if the request cannot
be honored.
</simpara>
<para>
The following example demonstrates how to use
<function>stream_set_write_buffer</function> to create an unbuffered stream.
<example>
<title><function>stream_set_write_buffer</function> example</title>
<programlisting role="php">
<refentry xml:id="function.stream-set-write-buffer" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_set_write_buffer</refname>
<refpurpose>Sets file buffering on the given stream</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_set_write_buffer</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>int</type><parameter>buffer</parameter></methodparam>
</methodsynopsis>
<simpara>
Output using <function>fwrite</function> is normally buffered at
8K. This means that if there are two processes wanting to write
to the same output stream (a file), each is paused after 8K of
data to allow the other to write.
<function>stream_set_write_buffer</function>
sets the buffering for write operations on the given filepointer
<parameter>stream</parameter> to <parameter>buffer</parameter> bytes.
If <parameter>buffer</parameter> is 0 then write operations are
unbuffered. This ensures that all writes with
<function>fwrite</function> are completed before other processes
are allowed to write to that output stream.
</simpara>
<simpara>
The function returns 0 on success, or EOF if the request cannot
be honored.
</simpara>
<para>
The following example demonstrates how to use
<function>stream_set_write_buffer</function> to create an unbuffered stream.
<example>
<title><function>stream_set_write_buffer</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = fopen($file, "w");
@ -46,17 +46,17 @@ if ($fp) {
}
?>
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</para>
<simpara>
See also
<function>fopen</function> and
<function>fwrite</function>.
</simpara>
</refsect1>
</refentry>
<simpara>
See also
<function>fopen</function> and
<function>fwrite</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

100
reference/stream/functions/stream-socket-accept.xml
View file

@ -1,55 +1,53 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<refentry xml:id="function.stream-socket-accept" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_accept</refname>
<refpurpose>
Accept a connection on a socket created by <function>stream_socket_server</function>
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_socket_accept</methodname>
<methodparam><type>resource</type><parameter>server_socket</parameter></methodparam>
<methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">peername</parameter></methodparam>
</methodsynopsis>
<para>
Accept a connection on a socket previously created by
<function>stream_socket_server</function>. If
<parameter>timeout</parameter> is specified, the default
socket accept timeout will be overridden with the time
specified in seconds. The name (address) of the client
which connected will be passed back in <parameter>peername</parameter>
if included and available from the selected transport.
</para>
<simpara>
<parameter>peername</parameter> can also be determined later
using <function>stream_socket_get_name</function>.
</simpara>
<simpara>
If the call fails, it will return &false;.
</simpara>
<warning>
<para>
This function should not be used with UDP server sockets. Instead, use
<function>stream_socket_recvfrom</function> and
<function>stream_socket_sendto</function>.
</para>
</warning>
<para>
See also <function>stream_socket_server</function>,
<function>stream_socket_get_name</function>,
<function>stream_set_blocking</function>,
<function>stream_set_timeout</function>,
<function>fgets</function>,
<function>fgetss</function>, <function>fwrite</function>,
<function>fclose</function>, <function>feof</function>, and
the <link linkend="ref.curl">Curl extension</link>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.9 $ -->
<refentry xml:id="function.stream-socket-accept" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_accept</refname>
<refpurpose>Accept a connection on a socket created by <function>stream_socket_server</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_socket_accept</methodname>
<methodparam><type>resource</type><parameter>server_socket</parameter></methodparam>
<methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">peername</parameter></methodparam>
</methodsynopsis>
<para>
Accept a connection on a socket previously created by
<function>stream_socket_server</function>. If
<parameter>timeout</parameter> is specified, the default
socket accept timeout will be overridden with the time
specified in seconds. The name (address) of the client
which connected will be passed back in <parameter>peername</parameter>
if included and available from the selected transport.
</para>
<simpara>
<parameter>peername</parameter> can also be determined later
using <function>stream_socket_get_name</function>.
</simpara>
<simpara>
If the call fails, it will return &false;.
</simpara>
<warning>
<para>
This function should not be used with UDP server sockets. Instead, use
<function>stream_socket_recvfrom</function> and
<function>stream_socket_sendto</function>.
</para>
</warning>
<para>
See also <function>stream_socket_server</function>,
<function>stream_socket_get_name</function>,
<function>stream_set_blocking</function>,
<function>stream_set_timeout</function>,
<function>fgets</function>,
<function>fgetss</function>, <function>fwrite</function>,
<function>fclose</function>, <function>feof</function>, and
the <link linkend="ref.curl">Curl extension</link>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

236
reference/stream/functions/stream-socket-client.xml
View file

@ -1,92 +1,90 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.stream-socket-client" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_client</refname>
<refpurpose>
Open Internet or Unix domain socket connection
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_socket_client</methodname>
<methodparam><type>string</type><parameter>remote_socket</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter role="reference">errno</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">errstr</parameter></methodparam>
<methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Initiates a stream or datagram connection to the destination specified
by <parameter>remote_socket</parameter>. The type of socket created
is determined by the transport specified using standard URL formatting:
<literal>transport://target</literal>. For Internet Domain sockets
(AF_INET) such as TCP and UDP, the <literal>target</literal> portion
of the <parameter>remote_socket</parameter> parameter should consist of
a hostname or IP address followed by a colon and a port number. For Unix
domain sockets, the <parameter>target</parameter> portion should point
to the socket file on the filesystem.
<!-- $Revision: 1.16 $ -->
<refentry xml:id="function.stream-socket-client" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_client</refname>
<refpurpose>Open Internet or Unix domain socket connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_socket_client</methodname>
<methodparam><type>string</type><parameter>remote_socket</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter role="reference">errno</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">errstr</parameter></methodparam>
<methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Initiates a stream or datagram connection to the destination specified
by <parameter>remote_socket</parameter>. The type of socket created
is determined by the transport specified using standard URL formatting:
<literal>transport://target</literal>. For Internet Domain sockets
(AF_INET) such as TCP and UDP, the <literal>target</literal> portion
of the <parameter>remote_socket</parameter> parameter should consist of
a hostname or IP address followed by a colon and a port number. For Unix
domain sockets, the <parameter>target</parameter> portion should point
to the socket file on the filesystem.
The optional <parameter>timeout</parameter> can be used to
set a timeout in seconds for the connect system call.
The optional <parameter>timeout</parameter> can be used to
set a timeout in seconds for the connect system call.
<parameter>flags</parameter> is a bitmask field which may be set to any
combination of connection flags. Currently the selection of connection
flags is limited to <constant>STREAM_CLIENT_CONNECT</constant> (default),
<constant>STREAM_CLIENT_ASYNC_CONNECT</constant> and
<constant>STREAM_CLIENT_PERSISTENT</constant>.
</para>
<note>
<simpara>
If you need to set a timeout for reading/writing data over the socket,
use <function>stream_set_timeout</function>, as the <parameter>timeout</parameter>
parameter to <function>stream_socket_client</function> only applies while
connecting the socket.
</simpara>
</note>
<note>
<simpara>
The timeout parameter only applies if you are not making an asynchronous
connection attempt.
</simpara>
</note>
<para>
<function>stream_socket_client</function> returns a
stream resource which may
be used together with the other file functions (such as
<function>fgets</function>, <function>fgetss</function>,
<function>fwrite</function>, <function>fclose</function>, and
<function>feof</function>).
</para>
<para>
If the call fails, it will return &false; and if the optional
<parameter>errno</parameter> and <parameter>errstr</parameter>
arguments are present they will be set to indicate the actual
system level error that occurred in the system-level
<literal>connect()</literal> call. If the value returned in
<parameter>errno</parameter> is <literal>0</literal> and the
function returned &false;, it is an indication that the error
occurred before the <literal>connect()</literal> call. This is
most likely due to a problem initializing the socket. Note that
the <parameter>errno</parameter> and
<parameter>errstr</parameter> arguments will always be passed by
reference.
</para>
<para>
Depending on the environment, the Unix domain or the optional
connect timeout may not be available. A list of available
transports can be retrieved using <function>stream_get_transports</function>.
See <xref linkend="transports"/> for a list of built in transports.
</para>
<para>
The stream will by default be opened in blocking mode. You can
switch it to non-blocking mode by using
<function>stream_set_blocking</function>.
<example>
<title><function>stream_socket_client</function> Example</title>
<programlisting role="php">
<parameter>flags</parameter> is a bitmask field which may be set to any
combination of connection flags. Currently the selection of connection
flags is limited to <constant>STREAM_CLIENT_CONNECT</constant> (default),
<constant>STREAM_CLIENT_ASYNC_CONNECT</constant> and
<constant>STREAM_CLIENT_PERSISTENT</constant>.
</para>
<note>
<simpara>
If you need to set a timeout for reading/writing data over the socket,
use <function>stream_set_timeout</function>, as the <parameter>timeout</parameter>
parameter to <function>stream_socket_client</function> only applies while
connecting the socket.
</simpara>
</note>
<note>
<simpara>
The timeout parameter only applies if you are not making an asynchronous
connection attempt.
</simpara>
</note>
<para>
<function>stream_socket_client</function> returns a
stream resource which may
be used together with the other file functions (such as
<function>fgets</function>, <function>fgetss</function>,
<function>fwrite</function>, <function>fclose</function>, and
<function>feof</function>).
</para>
<para>
If the call fails, it will return &false; and if the optional
<parameter>errno</parameter> and <parameter>errstr</parameter>
arguments are present they will be set to indicate the actual
system level error that occurred in the system-level
<literal>connect()</literal> call. If the value returned in
<parameter>errno</parameter> is <literal>0</literal> and the
function returned &false;, it is an indication that the error
occurred before the <literal>connect()</literal> call. This is
most likely due to a problem initializing the socket. Note that
the <parameter>errno</parameter> and
<parameter>errstr</parameter> arguments will always be passed by
reference.
</para>
<para>
Depending on the environment, the Unix domain or the optional
connect timeout may not be available. A list of available
transports can be retrieved using <function>stream_get_transports</function>.
See <xref linkend="transports"/> for a list of built in transports.
</para>
<para>
The stream will by default be opened in blocking mode. You can
switch it to non-blocking mode by using
<function>stream_set_blocking</function>.
<example>
<title><function>stream_socket_client</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = stream_socket_client("tcp://www.example.com:80", $errno, $errstr, 30);
@ -101,13 +99,13 @@ if (!$fp) {
}
?>
]]>
</programlisting>
</example>
The example below shows how to retrieve the day and time
from the UDP service "daytime" (port 13) in your own machine.
<example>
<title>Using UDP connection</title>
<programlisting role="php">
</programlisting>
</example>
The example below shows how to retrieve the day and time
from the UDP service "daytime" (port 13) in your own machine.
<example>
<title>Using UDP connection</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = stream_socket_client("udp://127.0.0.1:13", $errno, $errstr);
@ -120,32 +118,32 @@ if (!$fp) {
}
?>
]]>
</programlisting>
</example>
<warning>
<simpara>
UDP sockets will sometimes appear to have opened without an error,
even if the remote host is unreachable. The error will only
become apparent when you read or write data to/from the socket.
The reason for this is because UDP is a "connectionless" protocol,
which means that the operating system does not try to establish
a link for the socket until it actually needs to send or receive data.
</simpara>
</warning>
</para>
&ipv6.brackets;
<para>
See also <function>stream_socket_server</function>,
<function>stream_set_blocking</function>,
<function>stream_set_timeout</function>,
<function>stream_select</function>,
<function>fgets</function>,
<function>fgetss</function>, <function>fwrite</function>,
<function>fclose</function>, <function>feof</function>, and
the <link linkend="ref.curl">Curl extension</link>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<warning>
<simpara>
UDP sockets will sometimes appear to have opened without an error,
even if the remote host is unreachable. The error will only
become apparent when you read or write data to/from the socket.
The reason for this is because UDP is a "connectionless" protocol,
which means that the operating system does not try to establish
a link for the socket until it actually needs to send or receive data.
</simpara>
</warning>
</para>
&ipv6.brackets;
<para>
See also <function>stream_socket_server</function>,
<function>stream_set_blocking</function>,
<function>stream_set_timeout</function>,
<function>stream_select</function>,
<function>fgets</function>,
<function>fgetss</function>, <function>fwrite</function>,
<function>fclose</function>, <function>feof</function>, and
the <link linkend="ref.curl">Curl extension</link>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

120
reference/stream/functions/stream-socket-enable-crypto.xml
View file

@ -1,63 +1,61 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-socket-enable-crypto" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_enable_crypto</refname>
<refpurpose>
Turns encryption on/off on an already connected socket
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>stream_socket_enable_crypto</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>bool</type><parameter>enable</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>crypto_type</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>session_stream</parameter></methodparam>
</methodsynopsis>
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-socket-enable-crypto" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_enable_crypto</refname>
<refpurpose>Turns encryption on/off on an already connected socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>stream_socket_enable_crypto</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>bool</type><parameter>enable</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>crypto_type</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>session_stream</parameter></methodparam>
</methodsynopsis>
<simpara>
When called with the <parameter>crypto_type</parameter> parameter,
<function>stream_socket_enable_crypto</function> will setup
encryption on the stream using the specified method.
</simpara>
<simpara>
When called with the <parameter>crypto_type</parameter> parameter,
<function>stream_socket_enable_crypto</function> will setup
encryption on the stream using the specified method.
</simpara>
<para>
Valid values for <parameter>crypto_type</parameter>
<itemizedlist>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv2_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv3_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv23_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_TLS_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv2_SERVER</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv3_SERVER</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv23_SERVER</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_TLS_SERVER</constant></simpara></listitem>
</itemizedlist>
</para>
<para>
Valid values for <parameter>crypto_type</parameter>
<itemizedlist>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv2_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv3_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv23_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_TLS_CLIENT</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv2_SERVER</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv3_SERVER</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_SSLv23_SERVER</constant></simpara></listitem>
<listitem><simpara><constant>STREAM_CRYPTO_METHOD_TLS_SERVER</constant></simpara></listitem>
</itemizedlist>
</para>
<simpara>
Once the crypto settings are established, cryptography can be turned
on and off dynamically by passing &true; or &false; in the
<parameter>enable</parameter> parameter.
</simpara>
<simpara>
Once the crypto settings are established, cryptography can be turned
on and off dynamically by passing &true; or &false; in the
<parameter>enable</parameter> parameter.
</simpara>
<simpara>
If this stream should be seeded with settings from an already established
crypto enabled stream, pass that stream's resource variable
in the fourth parameter.
</simpara>
<simpara>
If this stream should be seeded with settings from an already established
crypto enabled stream, pass that stream's resource variable
in the fourth parameter.
</simpara>
<simpara>
Returns &true; on success, &false; if negotiation has failed or
<literal>0</literal> if there isn't enough data and you should try again
(only for non-blocking sockets).
</simpara>
<simpara>
Returns &true; on success, &false; if negotiation has failed or
<literal>0</literal> if there isn't enough data and you should try again
(only for non-blocking sockets).
</simpara>
<example>
<title><function>stream_socket_enable_crypto</function> Example</title>
<programlisting role="php">
<example>
<title><function>stream_socket_enable_crypto</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = stream_socket_client("tcp://myproto.example.com:31337", $errno, $errstr, 30);
@ -76,15 +74,15 @@ while ($motd = fgets($fp)) {
fclose($fp);
?>
]]>
</programlisting>
</example>
</programlisting>
</example>
<simpara>
<xref linkend="ref.openssl"/>, and
<xref linkend="transports"/>
</simpara>
</refsect1>
</refentry>
<simpara>
<xref linkend="ref.openssl"/>, and
<xref linkend="transports"/>
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

50
reference/stream/functions/stream-socket-get-name.xml
View file

@ -1,29 +1,29 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-socket-get-name" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_get_name</refname>
<refpurpose>Retrieve the name of the local or remote sockets</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_socket_get_name</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>bool</type><parameter>want_peer</parameter></methodparam>
</methodsynopsis>
<para>
Returns the local or remote name of a given socket connection.
If <parameter>want_peer</parameter> is set to &true; the remote
socket name will be returned, if it is set to &false; the local
socket name will be returned.
</para>
<para>
See also
<function>stream_socket_accept</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.5 $ -->
<refentry xml:id="function.stream-socket-get-name" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_get_name</refname>
<refpurpose>Retrieve the name of the local or remote sockets</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_socket_get_name</methodname>
<methodparam><type>resource</type><parameter>handle</parameter></methodparam>
<methodparam><type>bool</type><parameter>want_peer</parameter></methodparam>
</methodsynopsis>
<para>
Returns the local or remote name of a given socket connection.
If <parameter>want_peer</parameter> is set to &true; the remote
socket name will be returned, if it is set to &false; the local
socket name will be returned.
</para>
<para>
See also
<function>stream_socket_accept</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

148
reference/stream/functions/stream-socket-recvfrom.xml
View file

@ -1,54 +1,54 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<refentry xml:id="function.stream-socket-recvfrom" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_recvfrom</refname>
<refpurpose>Receives data from a socket, connected or not </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_socket_recvfrom</methodname>
<methodparam><type>resource</type><parameter>socket</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">address</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>stream_socket_recvfrom</function> accepts
data from a remote socket up to <parameter>length</parameter> bytes.
If <parameter>address</parameter> is provided it will be populated with
the address of the remote socket.
</para>
<para>
The value of <parameter>flags</parameter> can be any combination
of the following:
<table>
<title>possible values for <parameter>flags</parameter></title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>STREAM_OOB</constant></entry>
<entry>
Process OOB (out-of-band) data.
</entry>
</row>
<row>
<entry><constant>STREAM_PEEK</constant></entry>
<entry>
Retrieve data from the socket, but do not consume the buffer.
Subsequent calls to <function>fread</function> or
<function>stream_socket_recvfrom</function> will see
the same data.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<example>
<title><function>stream_socket_recvfrom</function> Example</title>
<programlisting role="php">
<!-- $Revision: 1.9 $ -->
<refentry xml:id="function.stream-socket-recvfrom" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_recvfrom</refname>
<refpurpose>Receives data from a socket, connected or not </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stream_socket_recvfrom</methodname>
<methodparam><type>resource</type><parameter>socket</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">address</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>stream_socket_recvfrom</function> accepts
data from a remote socket up to <parameter>length</parameter> bytes.
If <parameter>address</parameter> is provided it will be populated with
the address of the remote socket.
</para>
<para>
The value of <parameter>flags</parameter> can be any combination
of the following:
<table>
<title>possible values for <parameter>flags</parameter></title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>STREAM_OOB</constant></entry>
<entry>
Process OOB (out-of-band) data.
</entry>
</row>
<row>
<entry><constant>STREAM_PEEK</constant></entry>
<entry>
Retrieve data from the socket, but do not consume the buffer.
Subsequent calls to <function>fread</function> or
<function>stream_socket_recvfrom</function> will see
the same data.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<example>
<title><function>stream_socket_recvfrom</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
/* Open a server socket to port 1234 on localhost */
@ -71,31 +71,31 @@ fclose($socket);
fclose($server);
?>
]]>
</programlisting>
</example>
<note>
<para>
If a message received is longer than the <parameter>length</parameter>
parameter, excess bytes may be discarded depending on the type of socket
the message is received from (such as UDP).
</para>
</note>
<note>
<para>
Calls to <function>stream_socket_recvfrom</function> on socket-based
streams, after calls to buffer-based stream functions (like
<function>fread</function> or <function>stream_get_line</function>) read
data directly from the socket and bypass the stream buffer.
</para>
</note>
<para>
See also
<function>stream_socket_sendto</function>,
<function>stream_socket_client</function>, and
<function>stream_socket_server</function>.
</programlisting>
</example>
<note>
<para>
If a message received is longer than the <parameter>length</parameter>
parameter, excess bytes may be discarded depending on the type of socket
the message is received from (such as UDP).
</para>
</note>
<note>
<para>
Calls to <function>stream_socket_recvfrom</function> on socket-based
streams, after calls to buffer-based stream functions (like
<function>fread</function> or <function>stream_get_line</function>) read
data directly from the socket and bypass the stream buffer.
</para>
</refsect1>
</refentry>
</note>
<para>
See also
<function>stream_socket_sendto</function>,
<function>stream_socket_client</function>, and
<function>stream_socket_server</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

104
reference/stream/functions/stream-socket-sendto.xml
View file

@ -1,46 +1,46 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<refentry xml:id="function.stream-socket-sendto" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_sendto</refname>
<refpurpose>Sends a message to a socket, whether it is connected or not </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_socket_sendto</methodname>
<methodparam><type>resource</type><parameter>socket</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>address</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>stream_socket_sendto</function> sends
the data specified by <parameter>data</parameter> through the
socket specified by <parameter>socket</parameter>. The address
specified when the socket stream was created will be used unless
an alternate address is specified in <parameter>address</parameter>.
</para>
<para>
The value of <parameter>flags</parameter> can be any combination
of the following:
<table>
<title>possible values for <parameter>flags</parameter></title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>STREAM_OOB</constant></entry>
<entry>
Process OOB (out-of-band) data.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<example>
<title><function>stream_socket_sendto</function> Example</title>
<programlisting role="php">
<!-- $Revision: 1.4 $ -->
<refentry xml:id="function.stream-socket-sendto" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_sendto</refname>
<refpurpose>Sends a message to a socket, whether it is connected or not </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>stream_socket_sendto</methodname>
<methodparam><type>resource</type><parameter>socket</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>address</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>stream_socket_sendto</function> sends
the data specified by <parameter>data</parameter> through the
socket specified by <parameter>socket</parameter>. The address
specified when the socket stream was created will be used unless
an alternate address is specified in <parameter>address</parameter>.
</para>
<para>
The value of <parameter>flags</parameter> can be any combination
of the following:
<table>
<title>possible values for <parameter>flags</parameter></title>
<tgroup cols="2">
<tbody>
<row>
<entry><constant>STREAM_OOB</constant></entry>
<entry>
Process OOB (out-of-band) data.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<example>
<title><function>stream_socket_sendto</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
/* Open a socket to port 1234 on localhost */
@ -56,16 +56,16 @@ stream_socket_sendto($socket, "Out of Band data.", STREAM_OOB);
fclose($socket);
?>
]]>
</programlisting>
</example>
<para>
See also
<function>stream_socket_recvfrom</function>,
<function>stream_socket_client</function>, and
<function>stream_socket_server</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also
<function>stream_socket_recvfrom</function>,
<function>stream_socket_client</function>, and
<function>stream_socket_server</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

192
reference/stream/functions/stream-socket-server.xml
View file

@ -1,72 +1,70 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
<refentry xml:id="function.stream-socket-server" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_server</refname>
<refpurpose>
Create an Internet or Unix domain server socket
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_socket_server</methodname>
<methodparam><type>string</type><parameter>local_socket</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter role="reference">errno</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">errstr</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Creates a stream or datagram socket on the specified
<parameter>local_socket</parameter>. The type of socket created
is determined by the transport specified using standard URL formatting:
<literal>transport://target</literal>. For Internet Domain sockets
(AF_INET) such as TCP and UDP, the <literal>target</literal> portion
of the <parameter>remote_socket</parameter> parameter should consist of
a hostname or IP address followed by a colon and a port number. For Unix
domain sockets, the <parameter>target</parameter> portion should point
to the socket file on the filesystem.
<!-- $Revision: 1.19 $ -->
<refentry xml:id="function.stream-socket-server" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_socket_server</refname>
<refpurpose>Create an Internet or Unix domain server socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>stream_socket_server</methodname>
<methodparam><type>string</type><parameter>local_socket</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter role="reference">errno</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">errstr</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<para>
Creates a stream or datagram socket on the specified
<parameter>local_socket</parameter>. The type of socket created
is determined by the transport specified using standard URL formatting:
<literal>transport://target</literal>. For Internet Domain sockets
(AF_INET) such as TCP and UDP, the <literal>target</literal> portion
of the <parameter>remote_socket</parameter> parameter should consist of
a hostname or IP address followed by a colon and a port number. For Unix
domain sockets, the <parameter>target</parameter> portion should point
to the socket file on the filesystem.
<parameter>flags</parameter> is a bitmask field which may be set to any
combination of socket creation flags. The default value of flags is
<constant>STREAM_SERVER_BIND</constant> | <constant>STREAM_SERVER_LISTEN</constant>.
</para>
<note>
<para>
For UDP sockets, you must use <constant>STREAM_SERVER_BIND</constant> as
the <parameter>flags</parameter> parameter.
</para>
</note>
<para>
This function only creates a socket, to begin accepting connections
use <function>stream_socket_accept</function>.
</para>
<para>
If the call fails, it will return &false; and if the optional
<parameter>errno</parameter> and <parameter>errstr</parameter>
arguments are present they will be set to indicate the actual
system level error that occurred in the system-level
<literal>socket()</literal>, <literal>bind()</literal>, and
<literal>listen()</literal> calls. If the value returned in
<parameter>errno</parameter> is <literal>0</literal> and the
function returned &false;, it is an indication that the error
occurred before the <literal>bind()</literal> call. This is
most likely due to a problem initializing the socket. Note that
the <parameter>errno</parameter> and
<parameter>errstr</parameter> arguments will always be passed by
reference.
</para>
<para>
Depending on the environment, Unix domain sockets may not be available.
A list of available transports can be retrieved using
<function>stream_get_transports</function>. See
<xref linkend="transports"/> for a list of bulitin transports.
</para>
<para>
<example>
<title>Using TCP server sockets</title>
<programlisting role="php">
<parameter>flags</parameter> is a bitmask field which may be set to any
combination of socket creation flags. The default value of flags is
<constant>STREAM_SERVER_BIND</constant> | <constant>STREAM_SERVER_LISTEN</constant>.
</para>
<note>
<para>
For UDP sockets, you must use <constant>STREAM_SERVER_BIND</constant> as
the <parameter>flags</parameter> parameter.
</para>
</note>
<para>
This function only creates a socket, to begin accepting connections
use <function>stream_socket_accept</function>.
</para>
<para>
If the call fails, it will return &false; and if the optional
<parameter>errno</parameter> and <parameter>errstr</parameter>
arguments are present they will be set to indicate the actual
system level error that occurred in the system-level
<literal>socket()</literal>, <literal>bind()</literal>, and
<literal>listen()</literal> calls. If the value returned in
<parameter>errno</parameter> is <literal>0</literal> and the
function returned &false;, it is an indication that the error
occurred before the <literal>bind()</literal> call. This is
most likely due to a problem initializing the socket. Note that
the <parameter>errno</parameter> and
<parameter>errstr</parameter> arguments will always be passed by
reference.
</para>
<para>
Depending on the environment, Unix domain sockets may not be available.
A list of available transports can be retrieved using
<function>stream_get_transports</function>. See
<xref linkend="transports"/> for a list of bulitin transports.
</para>
<para>
<example>
<title>Using TCP server sockets</title>
<programlisting role="php">
<![CDATA[
<?php
$socket = stream_socket_server("tcp://0.0.0.0:8000", $errno, $errstr);
@ -81,21 +79,21 @@ if (!$socket) {
}
?>
]]>
</programlisting>
</example>
</para>
<para>
The example below shows how to act as a time server which can respond
to time queries as shown in an example on <function>stream_socket_client</function>.
<note>
<simpara>
Most systems require root access to create a server socket on a port
below 1024.
</simpara>
</note>
<example>
<title>Using UDP server sockets</title>
<programlisting role="php">
</programlisting>
</example>
</para>
<para>
The example below shows how to act as a time server which can respond
to time queries as shown in an example on <function>stream_socket_client</function>.
<note>
<simpara>
Most systems require root access to create a server socket on a port
below 1024.
</simpara>
</note>
<example>
<title>Using UDP server sockets</title>
<programlisting role="php">
<![CDATA[
<?php
$socket = stream_socket_server("udp://127.0.0.1:1113", $errno, $errstr, STREAM_SERVER_BIND);
@ -112,21 +110,21 @@ do {
?>
]]>
</programlisting>
</example>
</para>
&ipv6.brackets;
<para>
See also <function>stream_socket_client</function>,
<function>stream_set_blocking</function>,
<function>stream_set_timeout</function>,
<function>fgets</function>,
<function>fgetss</function>, <function>fwrite</function>,
<function>fclose</function>, <function>feof</function>, and
the <link linkend="ref.curl">Curl extension</link>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
&ipv6.brackets;
<para>
See also <function>stream_socket_client</function>,
<function>stream_set_blocking</function>,
<function>stream_set_timeout</function>,
<function>fgets</function>,
<function>fgetss</function>, <function>fwrite</function>,
<function>fclose</function>, <function>feof</function>, and
the <link linkend="ref.curl">Curl extension</link>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

792
reference/stream/functions/stream-wrapper-register.xml
View file

@ -1,426 +1,426 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<refentry xml:id="function.stream-wrapper-register" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_wrapper_register</refname>
<refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_wrapper_register</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
<methodparam><type>string</type><parameter>classname</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_wrapper_register</function> allows you to implement
your own protocol handlers and streams for use with all the other
filesystem functions (such as <function>fopen</function>,
<function>fread</function> etc.).
</para>
<para>
To implement a wrapper, you need to define a class with a number of
member functions, as defined below. When someone fopens your stream,
PHP will create an instance of <parameter>classname</parameter> and
then call methods on that instance. You must implement the methods
exactly as described below - doing otherwise will lead to undefined
behaviour.
</para>
<note>
<simpara>
As of PHP 5.0.0 the instance of
<parameter>classname</parameter> will be populated with a
<parameter>context</parameter> property referencing a
<literal>Context Resource</literal> which may be accessed
with <function>stream_context_get_options</function>.
If no context was passed to the stream creation function,
<parameter>context</parameter> will be set to &null;.
</simpara>
</note>
<para>
<function>stream_wrapper_register</function> will return &false; if the
<parameter>protocol</parameter> already has a handler.
</para>
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.stream-wrapper-register" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_wrapper_register</refname>
<refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_wrapper_register</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
<methodparam><type>string</type><parameter>classname</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_wrapper_register</function> allows you to implement
your own protocol handlers and streams for use with all the other
filesystem functions (such as <function>fopen</function>,
<function>fread</function> etc.).
</para>
<para>
To implement a wrapper, you need to define a class with a number of
member functions, as defined below. When someone fopens your stream,
PHP will create an instance of <parameter>classname</parameter> and
then call methods on that instance. You must implement the methods
exactly as described below - doing otherwise will lead to undefined
behaviour.
</para>
<note>
<simpara>
As of PHP 5.0.0 the instance of
<parameter>classname</parameter> will be populated with a
<parameter>context</parameter> property referencing a
<literal>Context Resource</literal> which may be accessed
with <function>stream_context_get_options</function>.
If no context was passed to the stream creation function,
<parameter>context</parameter> will be set to &null;.
</simpara>
</note>
<para>
<function>stream_wrapper_register</function> will return &false; if the
<parameter>protocol</parameter> already has a handler.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_open</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
<methodparam><type>string</type><parameter>opened_path</parameter></methodparam>
</methodsynopsis>
<para>
This method is called immediately after your stream object is
created. <parameter>path</parameter> specifies the URL that was
passed to <function>fopen</function> and that this object is
expected to retrieve. You can use <function>parse_url</function>
to break it apart.
</para>
<para>
<parameter>mode</parameter> is the mode used to open the file,
as detailed for <function>fopen</function>. You are responsible
for checking that <parameter>mode</parameter> is valid for the
<parameter>path</parameter> requested.
</para>
<para>
<parameter>options</parameter> holds additional flags set
by the streams API. It can hold one or more of the following
values OR'd together.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Flag</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>STREAM_USE_PATH</entry>
<entry>If <parameter>path</parameter> is relative, search
for the resource using the include_path.
</entry>
</row>
<row>
<entry>STREAM_REPORT_ERRORS</entry>
<entry>If this flag is set, you are responsible for raising
errors using <function>trigger_error</function> during
opening of the stream. If this flag is not set, you
should not raise any errors.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
If the <parameter>path</parameter> is opened successfully,
and STREAM_USE_PATH is set in <parameter>options</parameter>,
you should set <parameter>opened_path</parameter> to the full
path of the file/resource that was actually opened.
</para>
<para>
If the requested resource was opened successfully, you should
return &true;, otherwise you should return &false;
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_open</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
<methodparam><type>string</type><parameter>opened_path</parameter></methodparam>
</methodsynopsis>
<para>
This method is called immediately after your stream object is
created. <parameter>path</parameter> specifies the URL that was
passed to <function>fopen</function> and that this object is
expected to retrieve. You can use <function>parse_url</function>
to break it apart.
</para>
<para>
<parameter>mode</parameter> is the mode used to open the file,
as detailed for <function>fopen</function>. You are responsible
for checking that <parameter>mode</parameter> is valid for the
<parameter>path</parameter> requested.
</para>
<para>
<parameter>options</parameter> holds additional flags set
by the streams API. It can hold one or more of the following
values OR'd together.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Flag</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>STREAM_USE_PATH</entry>
<entry>If <parameter>path</parameter> is relative, search
for the resource using the include_path.
</entry>
</row>
<row>
<entry>STREAM_REPORT_ERRORS</entry>
<entry>If this flag is set, you are responsible for raising
errors using <function>trigger_error</function> during
opening of the stream. If this flag is not set, you
should not raise any errors.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
If the <parameter>path</parameter> is opened successfully,
and STREAM_USE_PATH is set in <parameter>options</parameter>,
you should set <parameter>opened_path</parameter> to the full
path of the file/resource that was actually opened.
</para>
<para>
If the requested resource was opened successfully, you should
return &true;, otherwise you should return &false;
</para>
<methodsynopsis>
<type>void</type><methodname>stream_close</methodname>
<void/>
</methodsynopsis>
<para>
This method is called when the stream is closed, using
<function>fclose</function>. You must release any resources
that were locked or allocated by the stream.
</para>
<methodsynopsis>
<type>void</type><methodname>stream_close</methodname>
<void/>
</methodsynopsis>
<para>
This method is called when the stream is closed, using
<function>fclose</function>. You must release any resources
that were locked or allocated by the stream.
</para>
<methodsynopsis>
<type>string</type><methodname>stream_read</methodname>
<methodparam><type>int</type><parameter>count</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>fread</function>
and <function>fgets</function> calls on the stream. You
must return up-to <parameter>count</parameter> bytes of data
from the current read/write position as a string.
If there are less than <parameter>count</parameter>
bytes available, return as many as are available. If no
more data is available, return either &false; or an
empty string.
You must also update the read/write position of the stream
by the number of bytes that were successfully read.
</para>
<methodsynopsis>
<type>string</type><methodname>stream_read</methodname>
<methodparam><type>int</type><parameter>count</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>fread</function>
and <function>fgets</function> calls on the stream. You
must return up-to <parameter>count</parameter> bytes of data
from the current read/write position as a string.
If there are less than <parameter>count</parameter>
bytes available, return as many as are available. If no
more data is available, return either &false; or an
empty string.
You must also update the read/write position of the stream
by the number of bytes that were successfully read.
</para>
<methodsynopsis>
<type>int</type><methodname>stream_write</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>fwrite</function>
calls on the stream. You should store <parameter>data</parameter>
into the underlying storage used by your stream. If there is not
enough room, try to store as many bytes as possible.
You should return the number of bytes that were successfully
stored in the stream, or 0 if none could be stored.
You must also update the read/write position of the stream
by the number of bytes that were successfully written.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_eof</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>feof</function>
calls on the stream. You should return &true; if the read/write
position is at the end of the stream and if no more data is available
to be read, or &false; otherwise.
</para>
<methodsynopsis>
<type>int</type><methodname>stream_write</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>fwrite</function>
calls on the stream. You should store <parameter>data</parameter>
into the underlying storage used by your stream. If there is not
enough room, try to store as many bytes as possible.
You should return the number of bytes that were successfully
stored in the stream, or 0 if none could be stored.
You must also update the read/write position of the stream
by the number of bytes that were successfully written.
</para>
<methodsynopsis>
<type>int</type><methodname>stream_tell</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>ftell</function>
calls on the stream. You should return the current read/write
position of the stream.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_eof</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>feof</function>
calls on the stream. You should return &true; if the read/write
position is at the end of the stream and if no more data is available
to be read, or &false; otherwise.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_seek</methodname>
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
<methodparam><type>int</type><parameter>whence</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>fseek</function>
calls on the stream. You should update the read/write position
of the stream according to <parameter>offset</parameter> and
<parameter>whence</parameter>. See <function>fseek</function>
for more information about these parameters.
Return &true; if the position was updated, &false; otherwise.
</para>
<methodsynopsis>
<type>int</type><methodname>stream_tell</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>ftell</function>
calls on the stream. You should return the current read/write
position of the stream.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_flush</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>fflush</function>
calls on the stream. If you have cached data in your stream
but not yet stored it into the underlying storage, you should
do so now.
Return &true; if the cached data was successfully stored (or
if there was no data to store), or &false; if the data could
not be stored.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_seek</methodname>
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
<methodparam><type>int</type><parameter>whence</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>fseek</function>
calls on the stream. You should update the read/write position
of the stream according to <parameter>offset</parameter> and
<parameter>whence</parameter>. See <function>fseek</function>
for more information about these parameters.
Return &true; if the position was updated, &false; otherwise.
</para>
<methodsynopsis>
<type>array</type><methodname>stream_stat</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>fstat</function>
calls on the stream and should return an array containing the same
values as appropriate for the stream.
</para>
<methodsynopsis>
<type>bool</type><methodname>stream_flush</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>fflush</function>
calls on the stream. If you have cached data in your stream
but not yet stored it into the underlying storage, you should
do so now.
Return &true; if the cached data was successfully stored (or
if there was no data to store), or &false; if the data could
not be stored.
</para>
<methodsynopsis>
<type>bool</type><methodname>unlink</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>unlink</function>
calls on URL paths associated with the wrapper and should attempt
to delete the item specified by <parameter>path</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support unlinking.
</para>
<note>
<simpara>
Userspace wrapper unlink method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>array</type><methodname>stream_stat</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>fstat</function>
calls on the stream and should return an array containing the same
values as appropriate for the stream.
</para>
<methodsynopsis>
<type>bool</type><methodname>rename</methodname>
<methodparam><type>string</type><parameter>path_from</parameter></methodparam>
<methodparam><type>string</type><parameter>path_to</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>rename</function>
calls on URL paths associated with the wrapper and should attempt
to rename the item specified by <parameter>path_from</parameter>
to the specification given by <parameter>path_to</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support renaming.
</para>
<note>
<simpara>
Userspace wrapper rename method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>bool</type><methodname>unlink</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>unlink</function>
calls on URL paths associated with the wrapper and should attempt
to delete the item specified by <parameter>path</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support unlinking.
</para>
<note>
<simpara>
Userspace wrapper unlink method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>bool</type><methodname>mkdir</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>mkdir</function>
calls on URL paths associated with the wrapper and should attempt
to create the directory specified by <parameter>path</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support
creating directories. Posible values for <parameter>options</parameter>
include <constant>STREAM_REPORT_ERRORS</constant> and
<constant>STREAM_MKDIR_RECURSIVE</constant>.
</para>
<note>
<simpara>
Userspace wrapper mkdir method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>bool</type><methodname>rename</methodname>
<methodparam><type>string</type><parameter>path_from</parameter></methodparam>
<methodparam><type>string</type><parameter>path_to</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>rename</function>
calls on URL paths associated with the wrapper and should attempt
to rename the item specified by <parameter>path_from</parameter>
to the specification given by <parameter>path_to</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support renaming.
</para>
<note>
<simpara>
Userspace wrapper rename method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>bool</type><methodname>rmdir</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>rmdir</function>
calls on URL paths associated with the wrapper and should attempt
to remove the directory specified by <parameter>path</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support
removing directories. Possible values for <parameter>options</parameter>
include <constant>STREAM_REPORT_ERRORS</constant>.
</para>
<note>
<simpara>
Userspace wrapper rmdir method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>bool</type><methodname>mkdir</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>mkdir</function>
calls on URL paths associated with the wrapper and should attempt
to create the directory specified by <parameter>path</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support
creating directories. Posible values for <parameter>options</parameter>
include <constant>STREAM_REPORT_ERRORS</constant> and
<constant>STREAM_MKDIR_RECURSIVE</constant>.
</para>
<note>
<simpara>
Userspace wrapper mkdir method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>bool</type><methodname>dir_opendir</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This method is called immediately when your stream object is created for
examining directory contents with <function>opendir</function>.
<parameter>path</parameter> specifies the URL that was
passed to <function>opendir</function> and that this object is
expected to explore. You can use <function>parse_url</function>
to break it apart.
</para>
<methodsynopsis>
<type>bool</type><methodname>rmdir</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>rmdir</function>
calls on URL paths associated with the wrapper and should attempt
to remove the directory specified by <parameter>path</parameter>.
It should return &true; on success or &false; on failure.
In order for the appropriate error message to be returned,
do not define this method if your wrapper does not support
removing directories. Possible values for <parameter>options</parameter>
include <constant>STREAM_REPORT_ERRORS</constant>.
</para>
<note>
<simpara>
Userspace wrapper rmdir method is not supported prior to
PHP 5.0.0.
</simpara>
</note>
<methodsynopsis>
<type>array</type><methodname>url_stat</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>stat</function>
calls on the URL paths associated with the wrapper and should
return as many elements in common with the system function as
possible. Unknown or unavailable values should be set to a
rational value (usually <constant>0</constant>).
</para>
<para>
<parameter>flags</parameter> holds additional flags set
by the streams API. It can hold one or more of the following
values OR'd together.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Flag</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>STREAM_URL_STAT_LINK</entry>
<entry>
For resources with the ability to link to other resource
(such as an HTTP Location: forward, or a filesystem
symlink). This flag specified that only information
about the link itself should be returned, not the
resource pointed to by the link. This flag is set in
response to calls to <function>lstat</function>,
<function>is_link</function>, or <function>filetype</function>.
</entry>
</row>
<row>
<entry>STREAM_URL_STAT_QUIET</entry>
<entry>If this flag is set, your wrapper should not raise any
errors. If this flag is not set, you are responsible for
reporting errors using the <function>trigger_error</function>
function during stating of the path.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<methodsynopsis>
<type>bool</type><methodname>dir_opendir</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
This method is called immediately when your stream object is created for
examining directory contents with <function>opendir</function>.
<parameter>path</parameter> specifies the URL that was
passed to <function>opendir</function> and that this object is
expected to explore. You can use <function>parse_url</function>
to break it apart.
</para>
<methodsynopsis>
<type>string</type><methodname>dir_readdir</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>readdir</function>
and should return a string representing the next filename in the
location opened by <function>dir_opendir</function>.
</para>
<methodsynopsis>
<type>array</type><methodname>url_stat</methodname>
<methodparam><type>string</type><parameter>path</parameter></methodparam>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This method is called in response to <function>stat</function>
calls on the URL paths associated with the wrapper and should
return as many elements in common with the system function as
possible. Unknown or unavailable values should be set to a
rational value (usually <constant>0</constant>).
</para>
<para>
<parameter>flags</parameter> holds additional flags set
by the streams API. It can hold one or more of the following
values OR'd together.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Flag</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>STREAM_URL_STAT_LINK</entry>
<entry>
For resources with the ability to link to other resource
(such as an HTTP Location: forward, or a filesystem
symlink). This flag specified that only information
about the link itself should be returned, not the
resource pointed to by the link. This flag is set in
response to calls to <function>lstat</function>,
<function>is_link</function>, or <function>filetype</function>.
</entry>
</row>
<row>
<entry>STREAM_URL_STAT_QUIET</entry>
<entry>If this flag is set, your wrapper should not raise any
errors. If this flag is not set, you are responsible for
reporting errors using the <function>trigger_error</function>
function during stating of the path.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<methodsynopsis>
<type>bool</type><methodname>dir_rewinddir</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>rewinddir</function>
and should reset the output generated by <function>dir_readdir</function>.
i.e.: The next call to <function>dir_readdir</function> should return
the first entry in the location returned by <function>dir_opendir</function>.
</para>
<methodsynopsis>
<type>string</type><methodname>dir_readdir</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>readdir</function>
and should return a string representing the next filename in the
location opened by <function>dir_opendir</function>.
</para>
<methodsynopsis>
<type>bool</type><methodname>dir_closedir</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>closedir</function>.
You should release any resources which were locked or allocated during
the opening and use of the directory stream.
</para>
<methodsynopsis>
<type>bool</type><methodname>dir_rewinddir</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>rewinddir</function>
and should reset the output generated by <function>dir_readdir</function>.
i.e.: The next call to <function>dir_readdir</function> should return
the first entry in the location returned by <function>dir_opendir</function>.
</para>
<methodsynopsis>
<type>bool</type><methodname>dir_closedir</methodname>
<void/>
</methodsynopsis>
<para>
This method is called in response to <function>closedir</function>.
You should release any resources which were locked or allocated during
the opening and use of the directory stream.
</para>
<para>
The example below implements a var:// protocol handler that
allows read/write access to a named global variable using
standard filesystem stream functions such as <function>fread</function>.
The var:// protocol implemented below, given the URL
"var://foo" will read/write data to/from $GLOBALS["foo"].
<para>
The example below implements a var:// protocol handler that
allows read/write access to a named global variable using
standard filesystem stream functions such as <function>fread</function>.
The var:// protocol implemented below, given the URL
"var://foo" will read/write data to/from $GLOBALS["foo"].
<example>
<title>A Stream for reading/writing global variables</title>
<programlisting role="php">
<example>
<title>A Stream for reading/writing global variables</title>
<programlisting role="php">
<![CDATA[
<?php
class VariableStream {
var $position;
var $varname;
function stream_open($path, $mode, $options, &$opened_path)
function stream_open($path, $mode, $options, &$opened_path)
{
$url = parse_url($path);
$this->varname = $url["host"];
$this->position = 0;
return true;
}
function stream_read($count)
function stream_read($count)
{
$ret = substr($GLOBALS[$this->varname], $this->position, $count);
$this->position += strlen($ret);
return $ret;
}
function stream_write($data)
function stream_write($data)
{
$left = substr($GLOBALS[$this->varname], 0, $this->position);
$right = substr($GLOBALS[$this->varname], $this->position + strlen($data));
@ -429,17 +429,17 @@ class VariableStream {
return strlen($data);
}
function stream_tell()
function stream_tell()
{
return $this->position;
}
function stream_eof()
function stream_eof()
{
return $this->position >= strlen($GLOBALS[$this->varname]);
}
function stream_seek($offset, $whence)
function stream_seek($offset, $whence)
{
switch ($whence) {
case SEEK_SET:
@ -450,7 +450,7 @@ class VariableStream {
return false;
}
break;
case SEEK_CUR:
if ($offset >= 0) {
$this->position += $offset;
@ -459,7 +459,7 @@ class VariableStream {
return false;
}
break;
case SEEK_END:
if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {
$this->position = strlen($GLOBALS[$this->varname]) + $offset;
@ -468,7 +468,7 @@ class VariableStream {
return false;
}
break;
default:
return false;
}
@ -479,7 +479,7 @@ stream_wrapper_register("var", "VariableStream")
or die("Failed to register protocol");
$myvar = "";
$fp = fopen("var://myvar", "r+");
fwrite($fp, "line1\n");
@ -495,12 +495,12 @@ var_dump($myvar);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

36
reference/stream/functions/stream-wrapper-restore.xml
View file

@ -1,22 +1,22 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<refentry xml:id="function.stream-wrapper-restore" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_wrapper_restore</refname>
<refpurpose>Restores a previously unregistered built-in wrapper</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_wrapper_restore</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
</methodsynopsis>
<para>
Restores a built-in wrapper previously unregistered with
<function>stream_wrapper_unregister</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.3 $ -->
<refentry xml:id="function.stream-wrapper-restore" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_wrapper_restore</refname>
<refpurpose>Restores a previously unregistered built-in wrapper</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_wrapper_restore</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
</methodsynopsis>
<para>
Restores a built-in wrapper previously unregistered with
<function>stream_wrapper_unregister</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

42
reference/stream/functions/stream-wrapper-unregister.xml
View file

@ -1,25 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<refentry xml:id="function.stream-wrapper-unregister" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_wrapper_unregister</refname>
<refpurpose>Unregister a URL wrapper</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_wrapper_unregister</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_wrapper_unregister</function> allows you to
disable an already defined stream wrapper. Once the wrapper
has been disabled you may override it with a user-defined wrapper
using <function>stream_wrapper_register</function> or
reenable it later on with <function>stream_wrapper_restore</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.3 $ -->
<refentry xml:id="function.stream-wrapper-unregister" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_wrapper_unregister</refname>
<refpurpose>Unregister a URL wrapper</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>stream_wrapper_unregister</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_wrapper_unregister</function> allows you to
disable an already defined stream wrapper. Once the wrapper
has been disabled you may override it with a user-defined wrapper
using <function>stream_wrapper_register</function> or
reenable it later on with <function>stream_wrapper_restore</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

22
reference/uodbc/functions/odbc-binmode.xml
View file

@ -1,23 +1,23 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/uodbc.xml, last change in rev 1.2 -->
<refentry xml:id="function.odbc-binmode" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>odbc_binmode</refname>
<refpurpose>Handling of binary column data</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>odbc_binmode</methodname>
<methodparam><type>resource</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<refpurpose>Handling of binary column data</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>odbc_binmode</methodname>
<methodparam><type>resource</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>mode</parameter></methodparam>
</methodsynopsis>
<para>
(ODBC SQL types affected: BINARY, VARBINARY, LONGVARBINARY)
</para>
<itemizedlist>
<listitem>
<listitem>
<simpara>
ODBC_BINMODE_PASSTHRU: Passthru BINARY data
</simpara>

8
reference/uodbc/functions/odbc-execute.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/uodbc.xml, last change in rev 1.5 -->
<refentry xml:id="function.odbc-execute" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
@ -53,9 +53,9 @@
<simpara>
If you wish to store a string which actually begins and ends with
single quotes, you must add a space or other non-single-quote character
to the beginning or end of the parameter, which will prevent the
parameter from being taken as a file name. If this is not an option,
then you must use another mechanism to store the string, such as
to the beginning or end of the parameter, which will prevent the
parameter from being taken as a file name. If this is not an option,
then you must use another mechanism to store the string, such as
executing the query directly with <function>odbc_exec</function>).
</simpara>
</listitem>

20
reference/uodbc/functions/odbc-longreadlen.xml
View file

@ -1,18 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/uodbc.xml, last change in rev 1.2 -->
<refentry xml:id="function.odbc-longreadlen" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>odbc_longreadlen</refname>
<refpurpose>Handling of LONG columns</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>odbc_longreadlen</methodname>
<methodparam><type>resource</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<refpurpose>Handling of LONG columns</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>odbc_longreadlen</methodname>
<methodparam><type>resource</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
<para>
(ODBC SQL types affected: LONG, LONGVARBINARY) The number of
bytes returned to PHP is controlled by the parameter length. If it

72
reference/uodbc/functions/odbc-next-result.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/uodbc.xml, last change in rev 1.29 -->
<refentry xml:id='function.odbc-next-result' xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>odbc_next_result</refname>
<refpurpose>Checks if multiple results are available</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>odbc_next_result</methodname>
<methodparam><type>resource</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
<function>odbc_next_result</function> returns &true; if there are more result sets
available as well as allowing access to the next result set via
<function>odbc_fetch_array</function>, <function>odbc_fetch_row</function>,
<function>odbc_result</function>, etc.
</para>
<para>
This function returns &false; on error.
</para>
<para>
The argument is a valid result identifier returned by <function>odbc_exec</function>.
</para>
<para>
<example>
<title><function>odbc_next_result</function></title>
<programlisting role="php">
<refentry xml:id='function.odbc-next-result' xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>odbc_next_result</refname>
<refpurpose>Checks if multiple results are available</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>odbc_next_result</methodname>
<methodparam><type>resource</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
<function>odbc_next_result</function> returns &true; if there are more result sets
available as well as allowing access to the next result set via
<function>odbc_fetch_array</function>, <function>odbc_fetch_row</function>,
<function>odbc_result</function>, etc.
</para>
<para>
This function returns &false; on error.
</para>
<para>
The argument is a valid result identifier returned by <function>odbc_exec</function>.
</para>
<para>
<example>
<title><function>odbc_next_result</function></title>
<programlisting role="php">
<![CDATA[
<?php
$r_Connection = odbc_connect($dsn, $username, $password);
@ -65,9 +65,9 @@ echo "Try for a fourth result set ";
var_dump(odbc_next_result($r_Results));
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Dump first result set array(1) {
["A"]=>
@ -88,11 +88,11 @@ Dump third result set array(1) {
bool(false)
Try for a fourth result set bool(false)
]]>
</screen>
</example>
</para>
</refsect1>
</refentry>
</screen>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables: