[PHP-DOC] cvs: phpdoc /en/reference/filesystem/functions file-get-contents.xml fopen.xml fread.xml

[Wez Furlong]

wez             Thu May 29 16:10:20 2003 EDT

  Modified files:              
    /phpdoc/en/reference/filesystem/functions   file-get-contents.xml 
                                                fopen.xml fread.xml 
  Log:
  Revise docs a little; document the non-greedy fread semantics when reading from
  network streams and fifos.
  
  
  
Index: phpdoc/en/reference/filesystem/functions/file-get-contents.xml
diff -u phpdoc/en/reference/filesystem/functions/file-get-contents.xml:1.8 
phpdoc/en/reference/filesystem/functions/file-get-contents.xml:1.9
--- phpdoc/en/reference/filesystem/functions/file-get-contents.xml:1.8  Mon May 19 
16:26:58 2003
+++ phpdoc/en/reference/filesystem/functions/file-get-contents.xml      Thu May 29 
16:10:20 2003
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.130 -->
   <refentry id="function.file-get-contents">
    <refnamediv>
@@ -17,6 +17,11 @@
     <para> 
      Identical to <function>file</function>, except that
      <function>file_get_contents</function> returns the file in a string.
+    </para>
+    <para>
+     <function>file_get_contents</function> is the preferred way to read the
+     contents of a file into a string.  It will use memory mapping techniques if
+     support by your OS to enhance performance.
     </para>
     &note.bin-safe;
     &tip.fopen-wrapper;
Index: phpdoc/en/reference/filesystem/functions/fopen.xml
diff -u phpdoc/en/reference/filesystem/functions/fopen.xml:1.13 
phpdoc/en/reference/filesystem/functions/fopen.xml:1.14
--- phpdoc/en/reference/filesystem/functions/fopen.xml:1.13     Sat May 24 16:43:53 
2003
+++ phpdoc/en/reference/filesystem/functions/fopen.xml  Thu May 29 16:10:20 2003
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fopen">
    <refnamediv>
@@ -189,11 +189,13 @@
      See also <xref linkend="wrappers"/>,
      <function>fclose</function>,
      <function>fgets</function>, 
+     <function>fread</function>,
+     <function>fwrite</function>,
      <function>fsockopen</function>,
      <function>file</function>,
      <function>file_exists</function>,
      <function>is_readable</function>,
-     <function>socket_set_timeout</function>, and
+     <function>stream_set_timeout</function>, and
      <function>popen</function>.
     </simpara>
    </refsect1>
Index: phpdoc/en/reference/filesystem/functions/fread.xml
diff -u phpdoc/en/reference/filesystem/functions/fread.xml:1.6 
phpdoc/en/reference/filesystem/functions/fread.xml:1.7
--- phpdoc/en/reference/filesystem/functions/fread.xml:1.6      Sun Jan 12 21:54:28 
2003
+++ phpdoc/en/reference/filesystem/functions/fread.xml  Thu May 29 16:10:20 2003
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.25 -->
   <refentry id="function.fread">
    <refnamediv>
@@ -37,11 +37,18 @@
     </para>
     <note>
      <para>
+      If you just want to get the contents of a file into a string, use
+      <function>file_get_contents</function> as it has much better performance
+      than the code above.
+     </para>
+    </note>
+    <warning>
+     <para>
       On systems which differentiate between binary and text files 
       (i.e. Windows) the file must be opened with 'b' included in
       <function>fopen</function> mode parameter.
      </para>
-    </note>
+    </warning>
     <para>
      <informalexample>
       <programlisting role="php">
@@ -56,6 +63,39 @@
       </programlisting>
      </informalexample>
     </para>
+
+    <note>
+     <para>
+      When reading from network streams or pipes, such as those returned when
+      reading <link linkend="features.remote-files">remote files</link> or from
+      <function>popen</function> and <function>proc_open</function>, reading
+      will stop after a packet is available.  This means that you should
+      collect the data together in chunks as shown in the example below.
+     </para>
+    </note>
+    <para>
+     <informalexample>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$handle = fopen ("http://www.php.net/";, "rb");
+$contents = "";
+do {
+    $data = fread ($handle, filesize ($filename));
+    if (strlen($data) == 0) {
+        break;
+    }
+    $contents .= $data;
+}
+fclose ($handle);
+?>
+]]>
+      </programlisting>
+     </informalexample>
+    </para>
+
+     
+    
     <simpara>
      See also <function>fwrite</function>, <function>fopen</function>,
      <function>fsockopen</function>, <function>popen</function>,



-- 
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php