From 8befa0e8fef3a54a3226e3b8c3ebda3dcad9c7f8 Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@php.net>
Date: Thu, 29 May 2003 20:10:20 +0000
Subject: [PATCH] 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
---
 .../functions/file-get-contents.xml           |  7 ++-
 reference/filesystem/functions/fopen.xml      |  6 ++-
 reference/filesystem/functions/fread.xml      | 44 ++++++++++++++++++-
 3 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/reference/filesystem/functions/file-get-contents.xml b/reference/filesystem/functions/file-get-contents.xml
index cb061fb336..9bc5637215 100644
--- a/reference/filesystem/functions/file-get-contents.xml
+++ b/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>
diff --git a/reference/filesystem/functions/fopen.xml b/reference/filesystem/functions/fopen.xml
index 147098dcfa..3a140ff22a 100644
--- a/reference/filesystem/functions/fopen.xml
+++ b/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>
diff --git a/reference/filesystem/functions/fread.xml b/reference/filesystem/functions/fread.xml
index 3c284e2efe..9ae3528a45 100644
--- a/reference/filesystem/functions/fread.xml
+++ b/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>,