<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <wez@thebrainroom.com>
  Please contact me before making any major amendments to the
  content of this section.  Splitting/Merging are fine if they are
  required for php-doc restructuring purposes - just drop me a line
  if you make a change (so I can update my local copy).
-->
 <sect1 id="streams.common-api">
   <title>Streams Common API Reference</title>
  
  <refentry id="streams.php-stream-stat-path">
   <refnamediv>
    <refname>php_stream_stat_path</refname>
    <refpurpose>Gets the status for a file or URL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_stat_path</methodname>
      <methodparam><type>char *</type><parameter>path</parameter></methodparam>
      <methodparam><type>php_stream_statbuf *</type><parameter>ssb</parameter></methodparam>
     </methodsynopsis>
     <para>
      <function>php_stream_stat_path</function> examines the file or URL specified by <parameter>path</parameter>
      and returns information such as file size, access and creation times and so on.
      The return value is 0 on success, -1 on error.
      For more information about the information returned, see
      <link linkend="streams.struct-php-stream-statbuf">php_stream_statbuf</link>.
     </para>
    </refsect1>
  </refentry>
  
  <refentry id="streams.php-stream-stat">
   <refnamediv>
    <refname>php_stream_stat</refname>
    <refpurpose>Gets the status for the underlying storage associated with a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_stat</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>php_stream_statbuf *</type><parameter>ssb</parameter></methodparam>
     </methodsynopsis>
     <para>
      <function>php_stream_stat</function> examines the storage to which <parameter>stream</parameter>
      is bound, and returns information such as file size, access and creation times and so on.
      The return value is 0 on success, -1 on error.
      For more information about the information returned, see
      <link linkend="streams.struct-php-stream-statbuf">php_stream_statbuf</link>.
     </para>
    </refsect1>
  </refentry>
  
  
  <refentry id="streams.php-stream-open-wrapper">
   <refnamediv>
    <refname>php_stream_open_wrapper</refname>
    <refpurpose>Opens a stream on a file or URL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>php_stream *</type><methodname>php_stream_open_wrapper</methodname>
      <methodparam><type>char *</type><parameter>path</parameter></methodparam>
      <methodparam><type>char *</type><parameter>mode</parameter></methodparam>
      <methodparam><type>int</type><parameter>options</parameter></methodparam>
      <methodparam><type>char **</type><parameter>opened</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_open_wrapper</function> opens a stream on the file, URL or
     other wrapped resource specified by <parameter>path</parameter>.  Depending on
     the value of <parameter>mode</parameter>, the stream may be opened for reading,
     writing, appending or combinations of those. See the table below for the different
     modes that can be used; in addition to the characters listed below, you may
     include the character 'b' either as the second or last character in the mode string.
     The presence of the 'b' character informs the relevant stream implementation to
     open the stream in a binary safe mode.
    </para>
    <para>
     The 'b' character is ignored on all POSIX conforming systems which treat
     binary and text files in the same way.  It is a good idea to specify the 'b'
     character whenever your stream is accessing data where the full 8 bits
     are important, so that your code will work when compiled on a system
     where the 'b' flag is important.
    </para>
    <para>
     Any local files created by the streams API will have their initial permissions set
     according to the operating system defaults - under Unix based systems
     this means that the umask of the process will be used.  Under Windows,
     the file will be owned by the creating process.
     Any remote files will be created according to the URL wrapper that was
     used to open the file, and the credentials supplied to the remote server.
    </para>
    <para>
     <variablelist>
      <varlistentry>
       <term>
        <constant>r</constant> 
       </term>
       <listitem>
        <simpara>
         Open text file for reading.  The stream is positioned at the beginning of
         the file.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>
        <constant>r+</constant> 
       </term>
       <listitem>
        <simpara>
         Open text file for reading and writing.  The stream is positioned at the beginning of
         the file.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>
        <constant>w</constant> 
       </term>
       <listitem>
        <simpara>
         Truncate the file to zero length or create text file for writing.
         The stream is positioned at the beginning of the file.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>
        <constant>w+</constant> 
       </term>
       <listitem>
        <simpara>
         Open text file for reading and writing.  The file is created if
         it does not exist, otherwise it is truncated. The stream is positioned at
         the beginning of the file.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>
        <constant>a</constant> 
       </term>
       <listitem>
        <simpara>
         Open for writing.  The file is created if it does not exist.
         The stream is positioned at the end of the file.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>
        <constant>a+</constant> 
       </term>
       <listitem>
        <simpara>
         Open text file for reading and writing.  The file is created if
         it does not exist. The stream is positioned at the end of the file.
        </simpara>
       </listitem>
      </varlistentry>
      
     </variablelist>    
    </para>    
    <para>
     <parameter>options</parameter> affects how the path/URL of the stream is
     interpreted, safe mode checks and actions taken if there is an error during opening
     of the stream.  See <link linkend="streams.options">Stream open options</link> for
     more information about options.
    </para>
    <para>
     If <parameter>opened</parameter> is not NULL, it will be set to a string containing
     the name of the actual file/resource that was opened.  This is important when the
     options include <constant>USE_PATH</constant>, which causes the include_path to be searched for the
     file.  You, the caller, are responsible for calling <function>efree</function> on
     the filename returned in this parameter.
    </para>
    <note>
     <simpara>
      If you specified <constant>STREAM_MUST_SEEK</constant> in <parameter>options</parameter>,
      the path returned in <parameter>opened</parameter> may not be the name of the
      actual stream that was returned to you.  It will, however, be the name of the original
      resource from which the seekable stream was manufactured.
     </simpara>
    </note>
   </refsect1>
  </refentry>
  
  
  <refentry id="streams.php-stream-read">
   <refnamediv>
    <refname>php_stream_read</refname>
    <refpurpose>Read a number of bytes from a stream into a buffer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>size_t</type><methodname>php_stream_read</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>char *</type><parameter>buf</parameter></methodparam>
      <methodparam><type>size_t</type><parameter>count</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_read</function> reads up to <parameter>count</parameter>
     bytes of data from <parameter>stream</parameter> and copies them into the
     buffer <parameter>buf</parameter>.
    </para>
    <para>
     <function>php_stream_read</function> returns the number of bytes that were
     read successfully.  There is no distinction between a failed read or an end-of-file
     condition - use <function>php_stream_eof</function> to test for an <constant>EOF</constant>.
    </para>
    <para>
     The internal position of the stream is advanced by the number of bytes that were
     read, so that subsequent reads will continue reading from that point.
    </para>
    <para>
     If less than <parameter>count</parameter> bytes are available to be read, this
     call will block (or wait) until the required number are available, depending on the
     blocking status of the stream.  By default, a stream is opened in blocking mode.
     When reading from regular files, the blocking mode will not usually make any
     difference: when the stream reaches the <constant>EOF</constant>
     <function>php_stream_read</function> will return a value less than
     <parameter>count</parameter>, and 0 on subsequent reads.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-write">
   <refnamediv>
    <refname>php_stream_write</refname>
    <refpurpose>Write a number of bytes from a buffer to a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>size_t</type><methodname>php_stream_write</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>const char *</type><parameter>buf</parameter></methodparam>
      <methodparam><type>size_t</type><parameter>count</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_write</function> writes <parameter>count</parameter>
     bytes of data from <parameter>buf</parameter> into <parameter>stream</parameter>.
    </para>
    <para>
     <function>php_stream_write</function> returns the number of bytes that were
     written successfully.  If there was an error, the number of bytes written will be
     less than <parameter>count</parameter>.
    </para>
    <para>
     The internal position of the stream is advanced by the number of bytes that were
     written, so that subsequent writes will continue writing from that point.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-eof">
   <refnamediv>
    <refname>php_stream_eof</refname>
    <refpurpose>Check for an end-of-file condition on a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_eof</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_eof</function> checks for an end-of-file condition
     on <parameter>stream</parameter>.
    </para>
    <para>
     <function>php_stream_eof</function> returns the 1 to indicate
     <constant>EOF</constant>,  0 if there is no <constant>EOF</constant> and -1 to indicate an error.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-getc">
   <refnamediv>
    <refname>php_stream_getc</refname>
    <refpurpose>Read a single byte from a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_getc</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_getc</function> reads a single character from
     <parameter>stream</parameter> and returns it as an unsigned char cast
     as an int, or <constant>EOF</constant> if the end-of-file is reached, or an error occurred.
    </para>
    <para>
     <function>php_stream_getc</function> may block in the same way as
     <function>php_stream_read</function> blocks.
    </para>
    <para>
     The internal position of the stream is advanced by 1 if successful.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-gets">
   <refnamediv>
    <refname>php_stream_gets</refname>
    <refpurpose>Read a line of data from a stream into a buffer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>char *</type><methodname>php_stream_gets</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>char *</type><parameter>buf</parameter></methodparam>
      <methodparam><type>size_t</type><parameter>maxlen</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_gets</function> reads up to <parameter>count</parameter>-1
     bytes of data from <parameter>stream</parameter> and copies them into the
     buffer <parameter>buf</parameter>.  Reading stops after an <constant>EOF</constant>
     or a newline.  If a newline is read, it is stored in <parameter>buf</parameter> as part of
     the returned data.  A NUL terminating character is stored as the last character
     in the buffer.
    </para>
    <para>
     <function>php_stream_read</function> returns <parameter>buf</parameter>
     when successful or NULL otherwise.
    </para>
    <para>
     The internal position of the stream is advanced by the number of bytes that were
     read, so that subsequent reads will continue reading from that point.
    </para>
    <para>
     This function may block in the same way as <function>php_stream_read</function>.     
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-close">
   <refnamediv>
    <refname>php_stream_close</refname>
    <refpurpose>Close a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_close</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_close</function> safely closes <parameter>stream</parameter>
     and releases the resources associated with it.  After <parameter>stream</parameter>
     has been closed, it's value is undefined and should not be used.
    </para>
    <para>
     <function>php_stream_close</function> returns 0 if the stream was closed or
     <constant>EOF</constant> to indicate an error.  Regardless of the success of the call,
     <parameter>stream</parameter> is undefined and should not be used after a call to
      this function.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-flush">
   <refnamediv>
    <refname>php_stream_flush</refname>
    <refpurpose>Flush stream buffers to storage</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_flush</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_flush</function> causes any data held in
     write buffers in <parameter>stream</parameter> to be committed to the
     underlying storage.
    </para>
    <para>
     <function>php_stream_flush</function> returns 0 if the buffers were flushed,
     or if the buffers did not need to be flushed, but returns <constant>EOF</constant>
     to indicate an error.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-seek">
   <refnamediv>
    <refname>php_stream_seek</refname>
    <refpurpose>Reposition a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_seek</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>off_t</type><parameter>offset</parameter></methodparam>
      <methodparam><type>int</type><parameter>whence</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_seek</function> repositions the internal
     position of <parameter>stream</parameter>.
     The new position is determined by adding the <parameter>offset</parameter>
     to the position indicated by <parameter>whence</parameter>.
     If <parameter>whence</parameter> is set to <constant>SEEK_SET</constant>,
     <constant>SEEK_CUR</constant> or <constant>SEEK_END</constant> the offset
     is relative to the start of the stream, the current position or the end of the stream, respectively.
    </para>
    <para>
     <function>php_stream_seek</function> returns 0 on success, but -1 if there was an error.
    </para>
    <note>
     <para>
     Not all streams support seeking, although the streams API will emulate a seek if
     <parameter>whence</parameter> is set to <constant>SEEK_CUR</constant>
     and <parameter>offset</parameter> is positive, by calling <function>php_stream_read</function>
     to read (and discard) <parameter>offset</parameter> bytes.
      </para>
      <para>
      The emulation is only applied when the underlying stream implementation does not
      support seeking.  If the stream is (for example) a file based stream that is wrapping
      a non-seekable pipe, the streams api will not apply emulation because the file based
      stream implements a seek operation; the seek will fail and an error result will be
      returned to the caller.
      </para>
    </note>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-tell">
   <refnamediv>
    <refname>php_stream_tell</refname>
    <refpurpose>Determine the position of a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>off_t</type><methodname>php_stream_tell</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_tell</function> returns the internal position of
     <parameter>stream</parameter>, relative to the start of the stream.
     If there is an error, -1 is returned.
     </para>
   </refsect1>
  </refentry>

 <refentry id="streams.php-stream-copy-to-stream">
   <refnamediv>
    <refname>php_stream_copy_to_stream</refname>
    <refpurpose>Copy data from one stream to another</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>size_t</type><methodname>php_stream_copy_to_stream</methodname>
      <methodparam><type>php_stream *</type><parameter>src</parameter></methodparam>
      <methodparam><type>php_stream *</type><parameter>dest</parameter></methodparam>
      <methodparam><type>size_t</type><parameter>maxlen</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_copy_to_stream</function> attempts to read up to <parameter>maxlen</parameter>
      bytes of data from <parameter>src</parameter> and write them to <parameter>dest</parameter>,
      and returns the number of bytes that were successfully copied.
    </para>
    <para>
     If you want to copy all remaining data from the <parameter>src</parameter> stream, pass the
     constant <constant>PHP_STREAM_COPY_ALL</constant> as the value of <parameter>maxlen</parameter>.
    </para>
    <note>
     <simpara>
      This function will attempt to copy the data in the most efficient manner, using memory mapped
      files when possible.
     </simpara>
    </note>
   </refsect1>
  </refentry>

 <refentry id="streams.php-stream-copy-to-mem">
   <refnamediv>
    <refname>php_stream_copy_to_mem</refname>
    <refpurpose>Copy data from stream and into an allocated buffer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>size_t</type><methodname>php_stream_copy_to_mem</methodname>
      <methodparam><type>php_stream *</type><parameter>src</parameter></methodparam>
      <methodparam><type>char **</type><parameter>buf</parameter></methodparam>
      <methodparam><type>size_t</type><parameter>maxlen</parameter></methodparam>
      <methodparam><type>int</type><parameter>persistent</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_copy_to_mem</function> allocates a buffer <parameter>maxlen</parameter>+1
     bytes in length using <function>pemalloc</function> (passing <parameter>persistent</parameter>).
     It then reads <parameter>maxlen</parameter> bytes from <parameter>src</parameter> and stores
     them in the allocated buffer.
    </para>
    <para>
     The allocated buffer is returned in <parameter>buf</parameter>, and the number of bytes successfully
     read.  You, the caller, are responsible for freeing the buffer by passing it and <parameter>persistent</parameter>
     to <function>pefree</function>.
    </para>
    <para>
     If you want to copy all remaining data from the <parameter>src</parameter> stream, pass the
     constant <constant>PHP_STREAM_COPY_ALL</constant> as the value of <parameter>maxlen</parameter>.
    </para>
    <note>
     <simpara>
      This function will attempt to copy the data in the most efficient manner, using memory mapped
      files when possible.
     </simpara>
    </note>
   </refsect1>
  </refentry>

 <refentry id="streams.php-stream-make-seekable">
   <refnamediv>
    <refname>php_stream_make_seekable</refname>
    <refpurpose>Convert a stream into a stream is seekable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_make_seekable</methodname>
      <methodparam><type>php_stream *</type><parameter>origstream</parameter></methodparam>
      <methodparam><type>php_stream **</type><parameter>newstream</parameter></methodparam>
      <methodparam><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_make_seekable</function> checks if <parameter>origstream</parameter> is
     seekable.   If it is not, it will copy the data into a new temporary stream.
     If successful, <parameter>newstream</parameter> is always set to the stream that is valid to use, even if the original
     stream was seekable.
    </para>
    <para>
     <parameter>flags</parameter> allows you to specify your preference for the seekable stream that is
     returned: use <constant>PHP_STREAM_NO_PREFERENCE</constant> to use the default seekable stream
     (which uses a dynamically expanding memory buffer, but switches to temporary file backed storage
     when the stream size becomes large), or use <constant>PHP_STREAM_PREFER_STDIO</constant> to
     use "regular" temporary file backed storage.
    </para>
    <para>
     <table>
      <title><function>php_stream_make_seekable</function> return values</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Value</entry>
         <entry>Meaning</entry>
        </row>
       </thead>
       <tbody>

        <row>
         <entry>PHP_STREAM_UNCHANGED</entry>
         <entry>Original stream was seekable anyway. <parameter>newstream</parameter> is set to the value
          of <parameter>origstream</parameter>.
         </entry>
        </row>

        <row>
         <entry>PHP_STREAM_RELEASED</entry>
         <entry>Original stream was not seekable and has been released. <parameter>newstream</parameter> is set to the
          new seekable stream.  You should not access <parameter>origstream</parameter> anymore.
         </entry>
        </row>

        <row>
         <entry>PHP_STREAM_FAILED</entry>
         <entry>An error occurred while attempting conversion. <parameter>newstream</parameter> is set to NULL;
          <parameter>origstream</parameter> is still valid.
         </entry>
        </row>

        <row>
         <entry>PHP_STREAM_CRITICAL</entry>
         <entry>An error occurred while attempting conversion that has left <parameter>origstream</parameter> in
         an indeterminate state. <parameter>newstream</parameter> is set to NULL and it is highly recommended
         that you close <parameter>origstream</parameter>.
         </entry>
        </row>
         
       </tbody>
      </tgroup>
     </table>
    </para>
    <note>
     <simpara>
      If you need to seek and write to the stream, it does not make sense to use this function, because the stream
      it returns is not guaranteed to be bound to the same resource as the original stream.
     </simpara>
    </note>
    <note>
     <simpara>
      If you only need to seek forwards, there is no need to call this function, as the streams API will emulate
      forward seeks when the whence parameter is <constant>SEEK_CUR</constant>.
     </simpara>
    </note>
    <note>
     <simpara>
      If <parameter>origstream</parameter> is network based, this function will block until the whole contents
      have been downloaded.
      </simpara>
    </note>
    <note>
     <simpara>
      NEVER call this function with an <parameter>origstream</parameter> that is reference by a file pointer
      in a PHP script!  This function may cause the underlying stream to be closed which could cause a crash
      when the script next accesses the file pointer!
     </simpara>
    </note>
    <note>
     <simpara>
     In many cases, this function can only succeed when <parameter>origstream</parameter> is a newly opened
     stream with no data buffered in the stream layer.  For that reason, and because this function is complicated to
     use correctly, it is recommended that you use <function>php_stream_open_wrapper</function> and pass in
     <constant>PHP_STREAM_MUST_SEEK</constant> in your options instead of calling this function directly.
     </simpara>
    </note>
    </refsect1>
  </refentry>


<refentry id="streams.php-stream-cast">
   <refnamediv>
    <refname>php_stream_cast</refname>
    <refpurpose>Convert a stream into another form, such as a FILE* or socket</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_cast</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>castas</parameter></methodparam>
      <methodparam><type>void **</type><parameter>ret</parameter></methodparam>
      <methodparam><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_cast</function> attempts to convert <parameter>stream</parameter> into
     a resource indicated by <parameter>castas</parameter>.
     If <parameter>ret</parameter> is NULL, the stream is queried to find out if such a conversion is
     possible, without actually performing the conversion (however, some internal stream state *might*
     be changed in this case).
     If <parameter>flags</parameter> is set to <constant>REPORT_ERRORS</constant>, an error
     message will be displayed is there is an error during conversion.
    </para>
    <note>
        <para>
         This function returns <constant>SUCCESS</constant> for success or <constant>FAILURE</constant>
         for failure.  Be warned that you must explicitly compare the return value with <constant>SUCCESS</constant>
         or <constant>FAILURE</constant> because of the underlying values of those constants. A simple
         boolean expression will not be interpreted as you intended.
        </para>
    </note>
    <para>
     <table>
      <title>Resource types for <parameter>castas</parameter></title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Value</entry>
         <entry>Meaning</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>PHP_STREAM_AS_STDIO</entry>
         <entry>Requests an ANSI FILE* that represents the stream</entry>
        </row>
        <row>
         <entry>PHP_STREAM_AS_FD</entry>
         <entry>Requests a POSIX file descriptor that represents the stream</entry>
        </row>
        <row>
         <entry>PHP_STREAM_AS_SOCKETD</entry>
         <entry>Requests a network socket descriptor that represents the stream</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     In addition to the basic resource types above, the conversion process can be altered by using the
     following flags by using the OR operator to combine the resource type with one or more of the
     following values:
     <table>
      <title>Resource types for <parameter>castas</parameter></title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Value</entry>
         <entry>Meaning</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>PHP_STREAM_CAST_TRY_HARD</entry>
         <entry>Tries as hard as possible, at the expense of additional resources, to ensure that the conversion succeeds</entry>
        </row>
        <row>
         <entry>PHP_STREAM_CAST_RELEASE</entry>
         <entry>Informs the streams API that some other code (possibly a third party library) will be responsible for closing the
         underlying handle/resource.  This causes the <parameter>stream</parameter> to be closed in such a way the underlying
         handle is preserved and returned in <parameter>ret</parameter>.  If this function succeeds, <parameter>stream</parameter>
         should be considered closed and should no longer be used.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <note>
     <simpara>
      If your system supports <function>fopencookie</function> (systems using glibc 2 or later), the streams API
      will always be able to synthesize an ANSI FILE* pointer over any stream.
      While this is tremendously useful for passing any PHP stream to any third-party libraries, such behaviour is not
      portable.  You are requested to consider the portability implications before distributing you extension.
      If the fopencookie synthesis is not desirable, you should query the stream to see if it naturally supports FILE*
      by using <function>php_stream_is</function>
     </simpara>
    </note>
    <note>
     <simpara>
      If you ask a socket based stream for a FILE*, the streams API will use <function>fdopen</function> to
      create it for you.  Be warned that doing so may cause data that was buffered in the streams layer to be
      lost if you intermix streams API calls with ANSI stdio calls.
     </simpara>
    </note>
    <para>
     See also <function>php_stream_is</function> and <function>php_stream_can_cast</function>.
    </para>
   </refsect1>
  </refentry>
 
<refentry id="streams.php-stream-can-cast">
   <refnamediv>
    <refname>php_stream_can_cast</refname>
    <refpurpose>Determines if a stream can be converted into another form, such as a FILE* or socket</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_can_cast</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>castas</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function is equivalent to calling <function>php_stream_cast</function> with <parameter>ret</parameter>
     set to NULL and <parameter>flags</parameter> set to 0.
     It returns <constant>SUCCESS</constant> if the stream can be converted into the form requested, or
     <constant>FAILURE</constant> if the conversion cannot be performed.
    </para>
    <note>
     <simpara>
      Although this function will not perform the conversion, some internal stream state *might* be
      changed by this call.
     </simpara>
    </note>
    <note>
     <simpara>
      You must explicitly compare the return value of this function with one of the constants, as described
      in <function>php_stream_cast</function>.
      </simpara>
    </note>
    <para>
     See also <function>php_stream_cast</function> and <function>php_stream_is</function>.
    </para>
   </refsect1>
  </refentry>

<refentry id="streams.php-stream-is-persistent">
   <refnamediv>
    <refname>php_stream_is_persistent</refname>
    <refpurpose>Determines if a stream is a persistent stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_is_persistent</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_is_persistent</function> returns 1 if the stream is a persistent stream,
     0 otherwise.
    </para>
 </refsect1>
</refentry>

<refentry id="streams.php-stream-is">
   <refnamediv>
    <refname>php_stream_is</refname>
    <refpurpose>Determines if a stream is of a particular type</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_stream_is</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
      <methodparam><type>int</type><parameter>istype</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_is</function> returns 1 if <parameter>stream</parameter> is of
     the type specified by <parameter>istype</parameter>, or 0 otherwise.
    <table>
      <title>Values for <parameter>istype</parameter></title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Value</entry>
         <entry>Meaning</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>PHP_STREAM_IS_STDIO</entry>
         <entry>The stream is implemented using the stdio implementation</entry>
        </row>
        <row>
         <entry>PHP_STREAM_IS_SOCKET</entry>
         <entry>The stream is implemented using the network socket implementation</entry>
        </row>
        <row>
         <entry>PHP_STREAM_IS_USERSPACE</entry>
         <entry>The stream is implemented using the userspace object implementation</entry>
        </row>
        <row>
         <entry>PHP_STREAM_IS_MEMORY</entry>
         <entry>The stream is implemented using the grow-on-demand memory stream implementation</entry>
        </row>
       </tbody>
      </tgroup>
     </table>

    </para>
    <note>
     <simpara>
      The PHP_STREAM_IS_XXX "constants" are actually defined as pointers to the underlying
      stream operations structure.  If your extension (or some other extension) defines additional
      streams, it should also declare a PHP_STREAM_IS_XXX constant in it's header file that you
      can use as the basis of this comparison.
      </simpara>
    </note>
    <note>
     <simpara>
      This function is implemented as a simple (and fast) pointer comparison, and does not change
      the stream state in any way.
     </simpara>
    </note>
    <para>
     See also <function>php_stream_cast</function> and <function>php_stream_can_cast</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="streams.php-stream-passthru">
   <refnamediv>
    <refname>php_stream_passthru</refname>
    <refpurpose>Outputs all remaining data from a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>size_t</type><methodname>php_stream_passthru</methodname>
      <methodparam><type>php_stream *</type><parameter>stream</parameter></methodparam>
     </methodsynopsis>
     <para>
      <function>php_stream_passthru</function> outputs all remaining data from <parameter>stream</parameter>
      to the active output buffer and returns the number of bytes output.
      If buffering is disabled, the data is written straight to the output, which is the browser making the
      request in the case of PHP on a web server, or stdout for CLI based PHP.
      This function will use memory mapped files if possible to help improve performance.
     </para>
    </refsect1>
  </refentry>

  <refentry id="streams.php-register-url-stream-wrapper">
   <refnamediv>
    <refname>php_register_url_stream_wrapper</refname>
    <refpurpose>Registers a wrapper with the Streams API</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_register_url_stream_wrapper</methodname>
      <methodparam><type>char *</type><parameter>protocol</parameter></methodparam>
      <methodparam><type>php_stream_wrapper *</type><parameter>wrapper</parameter></methodparam>
      <methodparam><type>TSRMLS_DC</type><parameter></parameter></methodparam>
     </methodsynopsis>
     <para>
      <function>php_register_url_stream_wrapper</function> registers <parameter>wrapper</parameter>
      as the handler for the protocol specified by <parameter>protocol</parameter>.
     </para>
     <note>
      <simpara>
       If you call this function from a loadable module, you *MUST* call <function>php_unregister_url_stream_wrapper</function>
       in your module shutdown function, otherwise PHP will crash.
      </simpara>
     </note>
    </refsect1>
  </refentry>

  <refentry id="streams.php-unregister-url-stream-wrapper">
   <refnamediv>
    <refname>php_unregister_url_stream_wrapper</refname>
    <refpurpose>Unregisters a wrapper from the Streams API</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>int</type><methodname>php_unregister_url_stream_wrapper</methodname>
      <methodparam><type>char *</type><parameter>protocol</parameter></methodparam>
      <methodparam><type>TSRMLS_DC</type><parameter></parameter></methodparam>
     </methodsynopsis>
     <para>
      <function>php_unregister_url_stream_wrapper</function> unregisters the wrapper
      associated with <parameter>protocol</parameter>.
     </para>
    </refsect1>
  </refentry>

  <refentry id="streams.php-stream-open-wrapper-ex">
   <refnamediv>
    <refname>php_stream_open_wrapper_ex</refname>
    <refpurpose>Opens a stream on a file or URL, specifying context</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>php_stream *</type><methodname>php_stream_open_wrapper_ex</methodname>
      <methodparam><type>char *</type><parameter>path</parameter></methodparam>
      <methodparam><type>char *</type><parameter>mode</parameter></methodparam>
      <methodparam><type>int</type><parameter>options</parameter></methodparam>
      <methodparam><type>char **</type><parameter>opened</parameter></methodparam>
      <methodparam><type>php_stream_context *</type><parameter>context</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_open_wrapper_ex</function> is exactly like
     <function>php_stream_open_wrapper</function>, but allows you to specify a
     php_stream_context object using <parameter>context</parameter>.
     To find out more about stream contexts, see
     <link linkend="stream.contexts">Stream Contexts</link>.
    </para>
    </refsect1>
    </refentry>

  <refentry id="streams.php-stream-open-wrapper-as-file">
   <refnamediv>
    <refname>php_stream_open_wrapper_as_file</refname>
    <refpurpose>Opens a stream on a file or URL, and converts to a FILE*</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis role="c">
      <type>FILE *</type><methodname>php_stream_open_wrapper_as_file</methodname>
      <methodparam><type>char *</type><parameter>path</parameter></methodparam>
      <methodparam><type>char *</type><parameter>mode</parameter></methodparam>
      <methodparam><type>int</type><parameter>options</parameter></methodparam>
      <methodparam><type>char **</type><parameter>opened</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_open_wrapper_as_file</function> is exactly like
     <function>php_stream_open_wrapper</function>, but converts the stream
     into an ANSI stdio FILE* and returns that instead of the stream.
     This is a convenient shortcut for extensions that pass FILE* to third-party libraries.
    </para>
   </refsect1>
  </refentry>
  <refentry id="streams.php-stream-filter-register-factory">
   <refnamediv>
    <refname>php_stream_filter_register_factory</refname>
    <refpurpose>Registers a filter factory with the Streams API</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <methodsynopsis role="c">
     <type>int</type><methodname>php_stream_filter_register_factory</methodname>
     <methodparam><type>const char *</type><parameter>filterpattern</parameter></methodparam>
     <methodparam><type>php_stream_filter_factory *</type><parameter>factory</parameter></methodparam>
    </methodsynopsis>
    <para>
     Use this function to register a filter factory with the name given by
     <parameter>filterpattern</parameter>.  <parameter>filterpattern</parameter>
     can be either a normal string name (i.e. <literal>myfilter</literal>) or
     a global pattern (i.e. <literal>myfilterclass.*</literal>) to allow a single
     filter to perform different operations depending on the exact name of the filter
     invoked (i.e. <literal>myfilterclass.foo</literal>, <literal>myfilterclass.bar</literal>,
     etc...)
    </para>
    <note>
     <simpara>
      Filters registered by a loadable extension must be certain to call
      php_stream_filter_unregister_factory() during MSHUTDOWN.
     </simpara>
    </note>
   </refsect1>
  </refentry>
  <refentry id="streams.php-stream-filter-unregister-factory">
   <refnamediv>
    <refname>php_stream_filter_unregister_factory</refname>
    <refpurpose>Deregisters a filter factory with the Streams API</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <methodsynopsis role="c">
     <type>int</type><methodname>php_stream_filter_unregister_factory</methodname>
     <methodparam><type>const char *</type><parameter>filterpattern</parameter></methodparam>
    </methodsynopsis>
    <para>
     Deregisters the <parameter>filterfactory</parameter> specified by the
     <parameter>filterpattern</parameter> making it no longer available for use.
    </para>
    <note>
     <simpara>
      Filters registered by a loadable extension must be certain to call
      php_stream_filter_unregister_factory() during MSHUTDOWN.
     </simpara>
    </note>
   </refsect1>
  </refentry>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->