From 195ea36a31a4415cb878b0d9b9e8b27d01bfebd6 Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@php.net>
Date: Thu, 26 Sep 2002 13:56:54 +0000
Subject: [PATCH] Document/tidy up/clarify some more streams related
 information. Add notes about URL support for GD functions.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@97008 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language-snippets.ent                         | 20 +++++++++----
 language/control-structures.xml               |  7 +++--
 reference/filesystem/functions/copy.xml       |  4 ++-
 reference/filesystem/functions/file.xml       |  3 +-
 reference/filesystem/functions/fpassthru.xml  | 12 ++++++--
 reference/filesystem/functions/readfile.xml   | 30 ++++---------------
 .../image/functions/imagecreatefromgd.xml     |  4 ++-
 .../image/functions/imagecreatefromgd2.xml    |  4 ++-
 .../functions/imagecreatefromgd2part.xml      |  4 ++-
 .../image/functions/imagecreatefromgif.xml    |  4 ++-
 .../image/functions/imagecreatefromjpeg.xml   |  4 ++-
 .../image/functions/imagecreatefrompng.xml    |  4 ++-
 .../image/functions/imagecreatefromwbmp.xml   |  4 ++-
 .../image/functions/imagecreatefromxbm.xml    |  4 ++-
 .../image/functions/imagecreatefromxpm.xml    |  4 ++-
 reference/image/reference.xml                 |  4 +--
 16 files changed, 67 insertions(+), 49 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index cc44254c6f..2fca1f5eb1 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -16,9 +16,9 @@ Use this function at your own risk.</simpara></warning>'>
 currently not documented; only the argument list is
 available.</simpara></warning>'>
 
-<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>The Windows
-version of <literal>PHP</literal> currently does not support accessing
-remote files via this function, even if
+<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>Windows
+versions of <literal>PHP</literal> prior to PHP 4.3 do not
+support accessing remote files via this function, even if
 <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is enabled.
 </para></warning>'>
 
@@ -29,8 +29,11 @@ the output of this function, and save it in a
 <type>string</type> (for example).</simpara></tip>'>
 
 <!ENTITY tip.fopen-wrapper '<tip><simpara>You can use a URL as a
-filename with this function if the "fopen wrappers" have been enabled.
-See <function>fopen</function> for more details.</simpara></tip>'>
+filename with this function if the <link linkend="ini.allow-url-fopen"
+>fopen wrappers</link> have been enabled.
+See <function>fopen</function> for more details on how to specify
+the filename and <xref linkend="wrappers"/> for a list of supported
+URL protocols.</simpara></tip>'>
 
 <!ENTITY return.success 'Returns &true; on success or &false; on failure.'>
 
@@ -50,6 +53,13 @@ is not (yet) binary safe!</simpara></warning>'>
 <!ENTITY note.bin-safe '<note><simpara>This function is
 binary-safe.</simpara></note>'>
 
+<!ENTITY note.line-endings '<note><simpara>If you are having problems
+with <literal>PHP</literal> not recognizing the line endings when
+reading files either on or created by a Macintosh computer, you
+might want to enable the <link linkend="ini.auto-detect-line-endings"
+>auto_detect_line_endings</link> run-time configuration option.</simpara>
+</note>'>
+
 <!ENTITY note.no-windows '<note><simpara>This function is not
 implemented on Windows platforms.</simpara></note>'>
 
diff --git a/language/control-structures.xml b/language/control-structures.xml
index 49b18f900e..0708e3f1d2 100644
--- a/language/control-structures.xml
+++ b/language/control-structures.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.64 $ -->
+<!-- $Revision: 1.65 $ -->
  <chapter id="control-structures">
   <title>Control Structures</title>
 
@@ -1185,8 +1185,9 @@ echo "A $color $fruit";   // A green
    <simpara>
      If "<link linkend="ini.allow-url-fopen">URL fopen wrappers</link>"
      are enabled in PHP (which they are in the default configuration),
-     you can specify the file to be included using an URL (via HTTP)
-     instead of a local pathname.  If the target server interprets
+     you can specify the file to be included using an URL (via HTTP or
+     other supported wrapper - see <xref linkend="wrappers"/> for a list
+     of protocols) instead of a local pathname.  If the target server interprets
      the target file as PHP code, variables may be passed to the included
      file using an URL request string as used with HTTP GET.  This is
      not strictly speaking the same thing as including the file and having
diff --git a/reference/filesystem/functions/copy.xml b/reference/filesystem/functions/copy.xml
index 77d7c33466..ad3d0b762e 100644
--- a/reference/filesystem/functions/copy.xml
+++ b/reference/filesystem/functions/copy.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.copy">
    <refnamediv>
@@ -32,6 +32,8 @@ if (!copy($file, $file.'.bak')) {
       As of PHP 4.3.0, both <parameter>source</parameter> and
       <parameter>dest</parameter> may be URLs if the "fopen wrappers"
       have been enabled.  See <function>fopen</function> for more details.
+      If <parameter>dest</parameter> is an URL, the copy operation may
+      fail if the wrapper does not support overwriting of existing files.
      </para>
     </note>
     <warning>
diff --git a/reference/filesystem/functions/file.xml b/reference/filesystem/functions/file.xml
index 72d65d4d6c..fe11d574b1 100644
--- a/reference/filesystem/functions/file.xml
+++ b/reference/filesystem/functions/file.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.file">
    <refnamediv>
@@ -26,6 +26,7 @@
       ending present.
      </para>
     </note>
+    &note.line-endings;
     <para>
      You can use the optional second parameter and set it to "1", if
      you want to search for the file in the <link
diff --git a/reference/filesystem/functions/fpassthru.xml b/reference/filesystem/functions/fpassthru.xml
index 2f27f88930..9f631e06a9 100644
--- a/reference/filesystem/functions/fpassthru.xml
+++ b/reference/filesystem/functions/fpassthru.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fpassthru">
    <refnamediv>
@@ -14,7 +14,7 @@
      </methodsynopsis>
     <simpara>
      Reads to EOF on the given file pointer from the current position and
-     writes the results to standard output.
+     writes the results to the output buffer.
     </simpara>
     <simpara>
      If an error occurs, <function>fpassthru</function> returns
@@ -30,7 +30,8 @@
      <parameter>fp</parameter> useless).
     </simpara>
     <simpara>
-     If you just want to dump the contents of a file to stdout you may
+     If you just want to dump the contents of a file to the output buffer,
+     without first modifying it or seeking to a particular offset, you may
      want to use the <function>readfile</function>, which saves you
      the <function>fopen</function> call.
     </simpara>
@@ -41,6 +42,11 @@
       appending a <literal>b</literal> to the mode used in the call to
       <function>fopen</function>.
      </para>
+     <para>
+      You are encouraged to use the <literal>b</literal> flag when dealing
+      with binary files, even if your system does not require it, so that
+      your scripts will be more portable.
+     </para>
     </note>
     <simpara>
      See also <function>readfile</function>,
diff --git a/reference/filesystem/functions/readfile.xml b/reference/filesystem/functions/readfile.xml
index ca78e5d575..95b7951f69 100644
--- a/reference/filesystem/functions/readfile.xml
+++ b/reference/filesystem/functions/readfile.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.readfile">
    <refnamediv>
@@ -14,34 +14,14 @@
       <methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
      </methodsynopsis>
     <para>
-     Reads a file and writes it to standard output.
+     Reads a file and writes it to the output buffer.
     </para>
     <para>
      Returns the number of bytes read from the file. If an error
      occurs, &false; is returned and unless the function was called as
      @readfile, an error message is printed.
     </para>
-    <para>
-     If <parameter>filename</parameter> begins with "http://"
-     (not case sensitive), an HTTP 1.0 connection is opened to the
-     specified server and the text of the response is written to
-     standard output.
-    </para>
-    <para>
-     Versions prior to PHP 4.0.5 do not handle HTTP redirects. Because
-     of this, directories must include trailing slashes.
-    </para>
-    <para>
-     If <parameter>filename</parameter> begins with "ftp://"
-     (not case sensitive), an ftp connection to the specified server is
-     opened and the requested file is written to standard output. If the server
-     does not support passive mode ftp, this will fail.
-    </para>
-    <para>
-     If <parameter>filename</parameter> begins with neither
-     of these strings, the file will be opened from the filesystem and
-     its contents written to standard output.
-    </para>
+    &tip.fopen-wrapper;
     <para>
      You can use the optional second parameter and set it to "1", if
      you want to search for the file in the <link
@@ -50,8 +30,8 @@
     <para>
      See also <function>fpassthru</function>,
      <function>file</function>, <function>fopen</function>,
-     <function>include</function>, <function>require</function>, and
-     <function>virtual</function>.
+     <function>include</function>, <function>require</function>,
+     <function>virtual</function> and <xref linkend="wrappers"/>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/image/functions/imagecreatefromgd.xml b/reference/image/functions/imagecreatefromgd.xml
index 01e10ebbf8..b8a75e6de0 100644
--- a/reference/image/functions/imagecreatefromgd.xml
+++ b/reference/image/functions/imagecreatefromgd.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.67 -->
   <refentry id='function.imagecreatefromgd'>
    <refnamediv>
@@ -15,6 +15,8 @@
     <para>
      &warn.undocumented.func;
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromgd2.xml b/reference/image/functions/imagecreatefromgd2.xml
index eb1a57465b..47977b9155 100644
--- a/reference/image/functions/imagecreatefromgd2.xml
+++ b/reference/image/functions/imagecreatefromgd2.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.67 -->
   <refentry id='function.imagecreatefromgd2'>
    <refnamediv>
@@ -15,6 +15,8 @@
     <para>
      &warn.undocumented.func;
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromgd2part.xml b/reference/image/functions/imagecreatefromgd2part.xml
index 3e975ae399..e69f57914d 100644
--- a/reference/image/functions/imagecreatefromgd2part.xml
+++ b/reference/image/functions/imagecreatefromgd2part.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.67 -->
   <refentry id='function.imagecreatefromgd2part'>
    <refnamediv>
@@ -19,6 +19,8 @@
     <para>
      &warn.undocumented.func;
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromgif.xml b/reference/image/functions/imagecreatefromgif.xml
index eba73d61c1..7fb22c4a2e 100644
--- a/reference/image/functions/imagecreatefromgif.xml
+++ b/reference/image/functions/imagecreatefromgif.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.2 -->
   <refentry id="function.imagecreatefromgif">
    <refnamediv>
@@ -51,6 +51,8 @@ function LoadGif ($imgname) {
       </para>
      </note>
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromjpeg.xml b/reference/image/functions/imagecreatefromjpeg.xml
index 2586488cf5..cb2722282a 100644
--- a/reference/image/functions/imagecreatefromjpeg.xml
+++ b/reference/image/functions/imagecreatefromjpeg.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.4 -->
   <refentry id="function.imagecreatefromjpeg">
    <refnamediv>
@@ -44,6 +44,8 @@ function LoadJpeg ($imgname) {
       </programlisting>
      </example>
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefrompng.xml b/reference/image/functions/imagecreatefrompng.xml
index bc401d525c..97788f8667 100644
--- a/reference/image/functions/imagecreatefrompng.xml
+++ b/reference/image/functions/imagecreatefrompng.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.4 -->
   <refentry id="function.imagecreatefrompng">
    <refnamediv>
@@ -44,6 +44,8 @@ function LoadPNG ($imgname) {
       </programlisting>
      </example>
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromwbmp.xml b/reference/image/functions/imagecreatefromwbmp.xml
index 3273a64ac8..8441c35f40 100644
--- a/reference/image/functions/imagecreatefromwbmp.xml
+++ b/reference/image/functions/imagecreatefromwbmp.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.30 -->
   <refentry id="function.imagecreatefromwbmp">
    <refnamediv>
@@ -50,6 +50,8 @@ function LoadWBMP ($imgname) {
       against GD-1.8 or later.
      </para>
     </note>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromxbm.xml b/reference/image/functions/imagecreatefromxbm.xml
index 4852e22d2f..bff8f37627 100644
--- a/reference/image/functions/imagecreatefromxbm.xml
+++ b/reference/image/functions/imagecreatefromxbm.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.61 -->
   <refentry id="function.imagecreatefromxbm">
    <refnamediv>
@@ -16,6 +16,8 @@
      <function>imagecreatefromxbm</function> returns an image identifier
      representing the image obtained from the given filename.
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/functions/imagecreatefromxpm.xml b/reference/image/functions/imagecreatefromxpm.xml
index 5bf7f7bdcd..3c62da9440 100644
--- a/reference/image/functions/imagecreatefromxpm.xml
+++ b/reference/image/functions/imagecreatefromxpm.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.61 -->
   <refentry id="function.imagecreatefromxpm">
    <refnamediv>
@@ -16,6 +16,8 @@
      <function>imagecreatefromxpm</function> returns an image identifier
      representing the image obtained from the given filename.
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 
diff --git a/reference/image/reference.xml b/reference/image/reference.xml
index f1e89f50b8..3225b5a6ae 100644
--- a/reference/image/reference.xml
+++ b/reference/image/reference.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <reference id="ref.image">
  <title>Image functions</title>
  <titleabbrev>Image</titleabbrev>
@@ -40,7 +40,7 @@
      greater than gd-1.6 support png, not gif.
       <note>
        <simpara>
-        Since PHP 4.3 there is a bundeled version of the GD lib. This bundeled
+        Since PHP 4.3 there is a bundled version of the GD lib. This bundled
         version has some additional features like alpha blending and should
         be used in preference to the external library since it's codebase is
         better maintained and more stable.