From 99b8c8a977414a8dd62da92aece05f023cc1f93b Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@php.net>
Date: Sun, 19 Jan 2003 10:11:24 +0000
Subject: [PATCH] Check in these docs that have been lying around for a while.
 By no means complete, but better than not having them.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@112662 c90b9560-bf6c-de11-be94-00142212c4b1
---
 chapters/streams.dir.xml     |  4 +-
 chapters/streams.structs.xml | 29 +++++++++++-
 chapters/streams.xml         | 92 +++++++++++++++++++++++++++++++++++-
 3 files changed, 122 insertions(+), 3 deletions(-)

diff --git a/chapters/streams.dir.xml b/chapters/streams.dir.xml
index 7d27d5ecc4..22c50618b6 100755
--- a/chapters/streams.dir.xml
+++ b/chapters/streams.dir.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- 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
@@ -53,6 +53,8 @@
      from <parameter>dirstream</parameter> and stores it into <parameter>ent</parameter>.
      If the function succeeds, the return value is <parameter>ent</parameter>.
      If the function fails, the return value is NULL.
+     See <link linkend="streams.struct-php-stream-dirent">php_stream_dirent</link> for more
+     details about the information returned for each directory entry.
      </para>
    </refsect1>
   </refentry>
diff --git a/chapters/streams.structs.xml b/chapters/streams.structs.xml
index 4336a68d6d..e1bc721bc5 100755
--- a/chapters/streams.structs.xml
+++ b/chapters/streams.structs.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- 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
@@ -45,6 +45,33 @@
    </refsect1>
   </refentry>
  
+  <refentry id="streams.struct-php-stream-ops">
+    <refnamediv>
+        <refname>struct php_stream_ops</refname>
+        <refpurpose>Holds member functions for a stream implementation</refpurpose>
+    </refnamediv>
+    <refsect1>
+     <title>Description</title>
+     <programlisting role="c">
+        typedef struct _php_stream_ops {
+             /* all streams MUST implement these operations */
+             size_t (*write)(php_stream *stream, const char *buf, size_t count TSRMLS_DC);
+             size_t (*read)(php_stream *stream, char *buf, size_t count TSRMLS_DC);
+             int (*close)(php_stream *stream, int close_handle TSRMLS_DC);
+             int (*flush)(php_stream *stream TSRMLS_DC);
+             
+             const char *label; /* name describing this class of stream */
+             
+             /* these operations are optional, and may be set to NULL if the stream does not
+              * support a particular operation */
+            int (*seek)(php_stream *stream, off_t offset, int whence TSRMLS_DC);
+            char *(*gets)(php_stream *stream, char *buf, size_t size TSRMLS_DC);
+            int (*cast)(php_stream *stream, int castas, void **ret TSRMLS_DC);
+            int (*stat)(php_stream *stream, php_stream_statbuf *ssb TSRMLS_DC);
+        } php_stream_ops;
+     </programlisting>
+    </refsect1>
+  </refentry>
 
 
  </sect1>
diff --git a/chapters/streams.xml b/chapters/streams.xml
index bf5871b9e3..e92e7b1470 100755
--- a/chapters/streams.xml
+++ b/chapters/streams.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- 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
@@ -179,6 +179,96 @@ if (stream) {
    
   </para>
  </sect1>
+
+ <sect1 id="streams.resources">
+  <title>Streams as Resources</title>
+  <para>
+   All streams are registered as resources when they are created.  This ensures
+   that they will be properly cleaned up even if there is some fatal error.
+   All of the filesystem functions in PHP operate on streams resources - that
+   means that your extensions can accept regular PHP file pointers as
+   parameters to, and return streams from their functions.
+   The streams API makes this process as painless as possible:
+  </para>
+  <para>
+     <example>
+      <title>How to accept a stream as a parameter</title>
+      <programlisting role="c">
+<![CDATA[
+PHP_FUNCTION(example_write_hello)
+{
+    zval *zstream;
+    php_stream *stream;
+    
+    if (FAILURE == zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "r", &zstream))
+        return;
+    
+    php_stream_from_zval(stream, &zstream);
+
+    /* you can now use the stream.  However, you do not "own" the
+        stream, the script does.  That means you MUST NOT close the
+        stream, because it will cause PHP to crash! */
+
+    php_stream_write(stream, "hello\n");
+        
+    RETURN_TRUE();
+}
+]]>
+      </programlisting>
+     </example>
+  </para>
+  <para>
+     <example>
+      <title>How to return a stream from a function</title>
+      <programlisting role="c">
+<![CDATA[
+PHP_FUNCTION(example_open_php_home_page)
+{
+    php_stream *stream;
+    
+    stream = php_stream_open_wrapper("http://www.php.net", "rb", REPORT_ERRORS, NULL);
+    
+    php_stream_to_zval(stream, return_value);
+
+    /* after this point, the stream is "owned" by the script.
+        If you close it now, you will crash PHP! */
+}
+]]>
+      </programlisting>
+     </example>
+  </para>
+  <para>
+   Since streams are automatically cleaned up, it'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'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.
+  </para>
+  <note>
+   <simpara>
+    Always use a debug build of PHP when developing an extension
+    (<option>--enable-debug</option> when running configure), as a lot of
+    effort has been made to warn you about memory and stream leaks.
+   </simpara>
+  </note>
+  <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's several lines of code that are not
+   strictly needed.  To save yourself the touble 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 <function>php_stream_auto_cleanup</function>.
+  </para>
+ </sect1>
+
  
 &chapters.streams.common;
 &chapters.streams.dir;