Revise docs a little; document the non-greedy fread semantics when reading from

network streams and fifos.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@129235 c90b9560-bf6c-de11-be94-00142212c4b1

reference/filesystem/functions/file-get-contents.xml

@@ -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>
@@ -18,6 +18,11 @@
      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;
     <note>

reference/filesystem/functions/fopen.xml

@@ -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 @@ $handle = fopen ("c:\\data\\info.txt", "r");
      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>

reference/filesystem/functions/fread.xml

@@ -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>
@@ -36,12 +36,19 @@ fclose ($handle);
      </informalexample>
     </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 @@ fclose ($handle);
       </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>,