internals2.ze1.streams.html

php的帮助文档,涉及到PHP的案例和基本语法,以及实际应用内容

     </div>
  </p>
  <p class="para">
     <div class="example">
      <p><b>Example #3 How to return a stream from a function</b></p>
      <div class="example-contents">
<div class="cdata"><pre>
PHP_FUNCTION(example_open_php_home_page)
{
    php_stream *stream;
    
    stream = php_stream_open_wrapper(&quot;http://www.php.net&quot;, &quot;rb&quot;, REPORT_ERRORS, NULL);
    
    php_stream_to_zval(stream, return_value);

    /* after this point, the stream is &quot;owned&quot; by the script.
        If you close it now, you will crash PHP! */
}
</pre></div>
      </div>

     </div>
  </p>
  <p class="para">
   Since streams are automatically cleaned up, it&#039;s tempting to think that we can get
   away with being sloppy programmers and not bother to close the streams when we
   are done with them.  Although such an approach might work, it is not a good idea
   for a number of reasons: streams hold locks on system resources while they are
   open, so leaving a file open after you have finished with it could prevent other
   processes from accessing it.  If a script deals with a large number of files,
   the accumulation of the resources used, both in terms of memory and the
   sheer number of open files, can cause web server requests to fail.  Sounds
   bad, doesn&#039;t it?  The streams API includes some magic that helps you to
   keep your code clean - if a stream is not closed by your code when it should
   be, you will find some helpful debugging information in you web server error
   log.
  </p>
  <blockquote><p><b class="note">Note</b>: 
   <span class="simpara">
    Always use a debug build of PHP when developing an extension
    (<span class="option">--enable-debug</span> when running configure), as a lot of
    effort has been made to warn you about memory and stream leaks.
   </span>
  </p></blockquote>
  <p class="para">
   In some cases, it is useful to keep a stream open for the duration of a request,
   to act as a log or trace file for example.  Writing the code to safely clean up
   such a stream is not difficult, but it&#039;s several lines of code that are not
   strictly needed.  To save yourself the trouble of writing the code, you
   can mark a stream as being OK for auto cleanup.  What this means is
   that the streams API will not emit a warning when it is time to auto-cleanup
   a stream.  To do this, you can use <b>php_stream_auto_cleanup()</b>.
  </p>
 </div>

 



 <div id="internals2.ze1.streams.constants" class="sect2">
  <h3 class="title">Streams open options</h3>
  
  <p class="para">
   These constants affect the operation of stream factory functions.
   <dl>

    <dt>

     <span class="term">
      <b><tt>IGNORE_PATH</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       This is the default option for streams; it requests that the include_path is
       not to be searched for the requested file.
      </span>
     </dd>

    </dt>


    <dt>

     <span class="term">
      <b><tt>USE_PATH</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       Requests that the include_path is to be searched for the requested file.
      </span>
     </dd>

    </dt>


    <dt>

     <span class="term">
      <b><tt>IGNORE_URL</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       Requests that registered URL wrappers are to be ignored when opening the
       stream.  Other non-URL wrappers will be taken into consideration when
       decoding the path.  There is no opposite form for this flag; the streams
       API will use all registered wrappers by default.
      </span>
     </dd>

    </dt>


    <dt>

     <span class="term">
      <b><tt>IGNORE_URL_WIN</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       On Windows systems, this is equivalent to IGNORE_URL.
       On all other systems, this flag has no effect.
      </span>
     </dd>

    </dt>

    
    <dt>

     <span class="term">
      <b><tt>ENFORCE_SAFE_MODE</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       Requests that the underlying stream implementation perform safe_mode
       checks on the file before opening the file.  Omitting this flag will skip
       safe_mode checks and allow opening of any file that the PHP process
       has rights to access.
      </span>
     </dd>

    </dt>


    <dt>

     <span class="term">
      <b><tt>REPORT_ERRORS</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       If this flag is set, and there was an error during the opening of the file
       or URL, the streams API will call the php_error function for you.  This
       is useful because the path may contain username/password information
       that should not be displayed in the browser output (it would be a
       security risk to do so).  When the streams API raises the error, it first
       strips username/password information from the path, making the error
       message safe to display in the browser.
      </span>
     </dd>

    </dt>


    <dt>

     <span class="term">
      <b><tt>STREAM_MUST_SEEK</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       This flag is useful when your extension really must be able to randomly
       seek around in a stream.  Some streams may not be seekable in their
       native form, so this flag asks the streams API to check to see if the
       stream does support seeking.  If it does not, it will copy the stream
       into temporary storage (which may be a temporary file or a memory
       stream) which does support seeking.
       Please note that this flag is not useful when you want to seek the
       stream and write to it, because the stream you are accessing might
       not be bound to the actual resource you requested.
      </span>
      <blockquote><p><b class="note">Note</b>: 
       <span class="simpara">
        If the requested resource is network based, this flag will cause the
        opener to block until the whole contents have been downloaded.
        </span>
      </p></blockquote>        
     </dd>

    </dt>


    <dt>

     <span class="term">
      <b><tt>STREAM_WILL_CAST</tt></b> 
     </span>

     <dd>

      <span class="simpara">
       If your extension is using a third-party library that expects a FILE* or
       file descriptor, you can use this flag to request the streams API to
       open the resource but avoid buffering.  You can then use
       <b>php_stream_cast()</b> to retrieve the FILE* or
       file descriptor that the library requires.
      </span>
      <span class="simpara">
       The is particularly useful when accessing HTTP URLs where the start
       of the actual stream data is found after an indeterminate offset into
       the stream.
      </span>
      <span class="simpara">
       Since this option disables buffering at the streams API level, you
       may experience lower performance when using streams functions
       on the stream; this is deemed acceptable because you have told
       streams that you will be using the functions to match the underlying
       stream implementation.
       Only use this option when you are sure you need it.
      </span>
     </dd>

    </dt>

   </dl>
    
  </p>
 </div>




</div><hr /><div style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="internals2.ze1.html">Zend Engine 1</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="internals2.ze1.zendapi.html">Zend API: Hacking the Core of PHP</a></div>
 <div class="up"><a href="internals2.ze1.html">Zend Engine 1</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>