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

Moved current streams documentation to its own reference section. Added reference manual page for streams.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@110041 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sara Golemon 2003-01-03 02:37:56 +00:00
parent dfafcb1274
commit 6fec56a107
5 changed files with 0 additions and 657 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,120 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.stream-get-meta-data">
<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>file_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>socket_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 read buffer.
</para>
</listitem>
</itemizedlist>
<simpara>
The following items were added in PHP 4.3:
</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.
Filters are currently undocumented.
</para>
</listitem>
</itemizedlist>
<note>
<para>
This function was introduced in PHP 4.3, 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 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>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

320
reference/filesystem/functions/stream-register-wrapper.xml
View file

@ -1,320 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.141 -->
<refentry id="function.stream-register-wrapper">
<refnamediv>
<refname>stream_register_wrapper</refname>
<refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>boolean</type><methodname>stream_register_wrapper</methodname>
<methodparam><type>string</type><parameter>protocol</parameter></methodparam>
<methodparam><type>string</type><parameter>classname</parameter></methodparam>
</methodsynopsis>
<para>
<function>stream_register_wrapper</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>
<para>
<function>stream_register_wrapper</function> will return &false; if the
<parameter>protocol</parameter> already has a handler.
</para>
<methodsynopsis>
<type>boolean</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>
<methodparam><type>void</type><parameter></parameter></methodparam>
</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>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>boolean</type><methodname>stream_eof</methodname>
<methodparam><type>void</type><parameter></parameter></methodparam>
</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_tell</methodname>
<methodparam><type>void</type><parameter></parameter></methodparam>
</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>boolean</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>boolean</type><methodname>stream_flush</methodname>
<methodparam><type>void</type><parameter></parameter></methodparam>
</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>
<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">
<![CDATA[
class VariableStream {
var $position;
var $varname;
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)
{
$ret = substr($GLOBALS[$this->varname], $this->position, $count);
$this->position += strlen($ret);
return $ret;
}
function stream_write($data)
{
$left = substr($GLOBALS[$this->varname], 0, $this->position);
$right = substr($GLOBALS[$this->varname], $this->position + strlen($data));
$GLOBALS[$this->varname] = $left . $data . $right;
$this->position += strlen($data);
return strlen($data);
}
function stream_tell()
{
return $this->position;
}
function stream_eof()
{
return $this->position >= strlen($GLOBALS[$this->varname]);
}
function stream_seek($offset, $whence)
{
switch($whence) {
case SEEK_SET:
if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) {
$this->position = $offset;
return true;
} else {
return false;
}
break;
case SEEK_CUR:
if ($offset >= 0) {
$this->position += $offset;
return true;
} else {
return false;
}
break;
case SEEK_END:
if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {
$this->position = strlen($GLOBALS[$this->varname]) + $offset;
return true;
} else {
return false;
}
break;
default:
return false;
}
}
}
stream_register_wrapper("var", "VariableStream")
or die("Failed to register protocol");
$myvar = "";
$fp = fopen("var://myvar", "r+");
fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");
rewind($fp);
while(!feof($fp)) {
echo fgets($fp);
}
fclose($fp);
var_dump($myvar);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

60
reference/filesystem/functions/stream-set-blocking.xml
View file

@ -1,60 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- splitted from ./en/functions/network.xml, last change in rev 1.2 -->
<refentry id="function.stream-set-blocking">
<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 &false;, the given stream
will be switched to non-blocking mode, and if &true;, 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>
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>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

81
reference/filesystem/functions/stream-set-timeout.xml
View file

@ -1,81 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/network.xml, last change in rev 1.18 -->
<refentry id="function.stream-set-timeout">
<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><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>.
<example>
<title><function>stream_set_timeout</function> Example</title>
<programlisting role="php">
<![CDATA[
<?php
$fp = fsockopen("www.example.com", 80);
if(!$fp) {
echo "Unable to open\n";
} else {
fputs($fp, "GET / HTTP/1.0\n\n");
$start = time();
stream_set_timeout($fp, 2);
$res = fread($fp, 2000);
var_dump(stream_get_meta_data($fp));
fclose($fp);
print $res;
}
?>
]]>
</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>
<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:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

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

@ -1,76 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.stream-set-write-buffer">
<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[
$fp = fopen($file, "w");
if ($fp) {
stream_set_write_buffer($fp, 0);
fputs($fp, $output);
fclose($fp);
}
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>fopen</function> and <function>fwrite</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->