Sophie: php-manual-en-4.3.0-2mdk noarch

php-manual-en-4.3.0-2mdk.noarch.rpm

<HTML
><HEAD
><TITLE
>Stream functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Function Reference"
HREF="funcref.html"><LINK
REL="PREVIOUS"
TITLE="socket_writev"
HREF="function.socket-writev.html"><LINK
REL="NEXT"
TITLE="stream_context_create"
HREF="function.stream-context-create.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="reference"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.socket-writev.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.stream-context-create.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="reference"
><A
NAME="ref.stream"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
>XCVIII. Stream functions</H1
><DIV
CLASS="PARTINTRO"
><A
NAME="AEN88218"
></A
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.intro"
></A
>Introduction</H1
><P
>&#13;     Streams were introduced with <TT
CLASS="literal"
>PHP</TT
> 4.3.0 as
     a way of generalizing file, network, data compression, and other
     opperations which share a common set of functions and uses.  In
     its simplest definition, a <TT
CLASS="literal"
>stream</TT
> is a 
     <TT
CLASS="literal"
>resource</TT
> object which exhibits streamable 
     behavior.  That is, it can be read from or written to in a linear 
     fashion, and may be able to <A
HREF="function.fseek.html"
><B
CLASS="function"
>fseek()</B
></A
> to an
     arbitrary locations within the stream.
    </P
><P
>&#13;     A <TT
CLASS="literal"
>wrapper</TT
> is additional code which tells the stream how to handle
     specific protocols/encodings.  For example, the <TT
CLASS="literal"
>http</TT
>
     wrapper knows how to translate a URL into an <TT
CLASS="literal"
>HTTP/1.0</TT
>
     request for a file on a remote server.  There are many wrappers
     built into <TT
CLASS="literal"
>PHP</TT
> by default (See <A
HREF="wrappers.html"
>Appendix I</A
>),
     and additional, custom wrappers may be added either within a
     PHP script using <A
HREF="function.stream-register-wrapper.html"
><B
CLASS="function"
>stream_register_wrapper()</B
></A
>,
     or directly from an extension using the API Reference in <A
HREF="streams.html"
>Chapter 43</A
>.
     Because any variety of wrapper may be added to <TT
CLASS="literal"
>PHP</TT
>, 
     there is no set limit on what can be done with them.  To access the list
     of currently registered wrappers, use <A
HREF="function.stream-get-wrappers.html"
><B
CLASS="function"
>stream_get_wrappers()</B
></A
>.
    </P
><P
>&#13;     A <TT
CLASS="literal"
>filter</TT
> is a final piece of code which may perform
     opperations on data as it is being read from or written to a stream.
     Any number of filters may be stacked onto a stream. Custom
     filters can be defined in a <TT
CLASS="literal"
>PHP</TT
> script using
     <A
HREF="function.stream-register-filter.html"
><B
CLASS="function"
>stream_register_filter()</B
></A
> or in an extension using the
     API Reference in <A
HREF="streams.html"
>Chapter 43</A
>.  To access the list of currently 
     registered filters, use <A
HREF="function.stream-get-filters.html"
><B
CLASS="function"
>stream_get_filters()</B
></A
>.
    </P
><P
>&#13;     A stream is referenced as: <TT
CLASS="parameter"
><I
>scheme</I
></TT
>://<TT
CLASS="parameter"
><I
>target</I
></TT
>
     <P
></P
><UL
><LI
><P
>&#13;        <TT
CLASS="parameter"
><I
>scheme</I
></TT
>(string) -
        The name of the wrapper to be used.  Examples include: file, 
        http, https, ftp, ftps, compress.zlib, compress.bz2, and php.  See 
        <A
HREF="wrappers.html"
>Appendix I</A
> for a list of PHP builtin wrappers.  If
        no wrapper is specified, the function default is used (typically
        <TT
CLASS="literal"
>file</TT
>://).
       </P
></LI
><LI
><P
>&#13;        <TT
CLASS="parameter"
><I
>target</I
></TT
> - 
        Depends on the wrapper used.  For filesystem related streams this is
        typically a path and filename of the desired file.  For network related 
        streams this is typically a hostname, often with a path appended.  Again, see
        <A
HREF="wrappers.html"
>Appendix I</A
> for a description of targets for builtin streams.
       </P
></LI
></UL
>
    </P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.requirements"
></A
>Requirements</H1
><P
>No external libraries are needed to build this extension.</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.installation"
></A
>Installation</H1
><P
>&#13;     Streams are an integral part of <TT
CLASS="literal"
>PHP</TT
>
     as of version 4.3.0.  No steps are required to enable them.
    </P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.configuration"
></A
>Runtime Configuration</H1
><P
>This extension has no configuration directives defined in <TT
CLASS="filename"
>php.ini</TT
>.</P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.resources"
></A
>Stream Classes</H1
><P
>&#13;     User designed wrappers can be registered via <A
HREF="function.stream-register-wrapper.html"
><B
CLASS="function"
>stream_register_wrapper()</B
></A
>,
     using the class definition shown on that manual page.
    </P
><P
>&#13;     <TT
CLASS="literal"
>class</TT
> php_user_filter is predefined and is an abstract
     baseclass for use with user defined filters.  See the manual page for
     <A
HREF="function.stream-register-filter.html"
><B
CLASS="function"
>stream_register_filter()</B
></A
> for details on implementing
     user defined filters.
    </P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.constants"
></A
>Predefined Constants</H1
><P
>&#13;     <DIV
CLASS="informaltable"
><A
NAME="AEN88276"
></A
><P
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Constant</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>STREAM_USE_PATH</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>Flag</TT
> indicating if the <TT
CLASS="literal"
>stream</TT
>
          used the include path.
         </TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="constant"
><B
>STREAM_REPORT_ERRORS</B
></TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="literal"
>Flag</TT
> indicating if the <TT
CLASS="literal"
>wrapper</TT
>
          is responsible for raising errors using <A
HREF="function.trigger-error.html"
><B
CLASS="function"
>trigger_error()</B
></A
> 
          during opening of the stream.  If this flag is not set, you
          should not raise any errors.
         </TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
    </P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.errors"
></A
>Stream Errors</H1
><P
>&#13;     As with any file or socket related function, an opperation on a stream
     may fail for a variety of normal reasons (i.e.: Unable to connect to remote
     host, file not found, etc...).  A stream related call may also fail because
     the desired stream is not registered on the running system.  See the array returned
     by <A
HREF="function.stream-get-wrappers.html"
><B
CLASS="function"
>stream_get_wrappers()</B
></A
> for a list of streams supported by your
     installation of <TT
CLASS="literal"
>PHP</TT
>.  As with most PHP internal functions
     if a failure occours an <TT
CLASS="constant"
><B
>E_WARNING</B
></TT
> message will be generated
     describing the nature of the error.
    </P
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stream.examples"
></A
>Examples</H1
><P
>&#13;     <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN88305"
></A
><P
><B
>Example 1. Using <A
HREF="function.file-get-contents.html"
><B
CLASS="function"
>file_get_contents()</B
></A
>
       to retrieve data from multiple sources</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?php
/* Read local file from /home/bar */
$localfile = file_get_contents("/home/bar/foo.txt");

/* Identical to above, explicitly naming FILE scheme */
$localfile = file_get_contents("file:///home/bar/foo.txt");

/* Read remote file from www.example.com using HTTP */
$httpfile  = file_get_contents("http://www.example.com/foo.txt");

/* Read remote file from www.example.com using HTTPS */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");

/* Read remote file from ftp.example.com using FTP */
$ftpfile   = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");

/* Read remote file from ftp.example.com using FTPS */
$ftpsfile  = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
    </P
><P
>&#13;     <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN88310"
></A
><P
><B
>Example 2. Making a POST request to an https server</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?php
/* Send POST request to https://secure.example.com/form_action.php
 * Include form elements named "foo" and "bar" with dummy values
 */

$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n";

$data = "foo=" . urlencode("Value for Foo") . "&#38;bar=" . urlencode("Value for Bar");

fputs($sock, "POST /form_action.php HTTP/1.0\r\n");
fputs($sock, "Host: secure.example.com\r\n");
fputs($sock, "Content-type: application/x-www-url-encoded\r\n");
fputs($sock, "Content-length: " . strlen($data) . "\r\n");
fputs($sock, "Accept: */*\r\n");
fputs($sock, "\r\n");
fputs($sock, "$data\r\n");
fputs($sock, "\r\n");

$headers = "";
while ($str = trim(fgets($sock, 4096)))
  $headers .= "$str\n";

print "\n";

$body = "";
while (!feof($sock))
  $body .= fgets($sock, 4096);

fclose($sock);
?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
    </P
><P
>&#13;     <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN88314"
></A
><P
><B
>Example 3. Writting data to a compressed file</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?php
/* Create a compressed file containing an arbitrarty string
 * File can be read back using compress.zlib stream or just
 * decompressed from the command line using 'gzip -d foo-bar.txt.gz'
 */
$fp = fopen("compress.zlib://foo-bar.txt.gz","wb");
if (!$fp) die("Unable to create file.");

fwrite($fp, "This is a test.\n");

fclose($fp);
?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
    </P
></DIV
></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="function.stream-context-create.html"
>stream_context_create</A
>&nbsp;--&nbsp;Create a streams context</DT
><DT
><A
HREF="function.stream-context-get-options.html"
>stream_context_get_options</A
>&nbsp;--&nbsp;Retrieve options for a stream/wrapper/context</DT
><DT
><A
HREF="function.stream-context-set-option.html"
>stream_context_set_option</A
>&nbsp;--&nbsp;Sets an option for a stream/wrapper/context</DT
><DT
><A
HREF="function.stream-context-set-params.html"
>stream_context_set_params</A
>&nbsp;--&nbsp;Set parameters for a stream/wrapper/context</DT
><DT
><A
HREF="function.stream-filter-append.html"
>stream_filter_append</A
>&nbsp;--&nbsp;Attach a filter to a stream.</DT
><DT
><A
HREF="function.stream-filter-prepend.html"
>stream_filter_prepend</A
>&nbsp;--&nbsp;Attach a filter to a stream.</DT
><DT
><A
HREF="function.stream-get-filters.html"
>stream_get_filters</A
>&nbsp;--&nbsp;Retrieve list of registered filters</DT
><DT
><A
HREF="function.stream-get-meta-data.html"
>stream_get_meta_data</A
>&nbsp;--&nbsp;Retrieves header/meta data from streams/file pointers</DT
><DT
><A
HREF="function.stream-get-wrappers.html"
>stream_get_wrappers</A
>&nbsp;--&nbsp;Retrieve list of registered streams</DT
><DT
><A
HREF="function.stream-register-filter.html"
>stream_register_filter</A
>&nbsp;--&nbsp;Register a stream filter implemented as a PHP class derived from <TT
CLASS="literal"
>php_user_filter</TT
></DT
><DT
><A
HREF="function.stream-register-wrapper.html"
>stream_register_wrapper</A
>&nbsp;--&nbsp;Register a URL wrapper implemented as a PHP class</DT
><DT
><A
HREF="function.stream-select.html"
>stream_select</A
>&nbsp;--&nbsp;Runs the equivalent of the select() system call on the given 
     arrays of streams with a timeout specified by tv_sec and tv_usec </DT
><DT
><A
HREF="function.stream-set-blocking.html"
>stream_set_blocking</A
>&nbsp;--&nbsp;Set blocking/non-blocking mode on a stream</DT
><DT
><A
HREF="function.stream-set-timeout.html"
>stream_set_timeout</A
>&nbsp;--&nbsp;Set timeout period on a stream</DT
><DT
><A
HREF="function.stream-set-write-buffer.html"
>stream_set_write_buffer</A
>&nbsp;--&nbsp;Sets file buffering on the given stream</DT
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.socket-writev.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.stream-context-create.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>socket_writev</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="funcref.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>stream_context_create</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>