wez Sat Jun 7 10:12:51 2003 EDT
Modified files:
/phpdoc/en/reference/filesystem/functions fopen.xml
Log:
Explain a bit more about the nightmare that is the text-mode-translation, the
spawn of satan.
Index: phpdoc/en/reference/filesystem/functions/fopen.xml
diff -u phpdoc/en/reference/filesystem/functions/fopen.xml:1.14
phpdoc/en/reference/filesystem/functions/fopen.xml:1.15
--- phpdoc/en/reference/filesystem/functions/fopen.xml:1.14 Thu May 29 16:10:20
2003
+++ phpdoc/en/reference/filesystem/functions/fopen.xml Sat Jun 7 10:12:51 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
+<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
<refentry id="function.fopen">
<refnamediv>
@@ -122,25 +122,61 @@
</para>
<note>
<para>
- On systems that differentiate between binary ('b') and text ('t') mode
- translation (such as Windows), the <parameter>mode</parameter> may contain
- either the letter 'b' or the letter 't' as the last character to force
- the translation mode to be either binary or text mode respectively.
+ Different operating system families have different line-ending
+ conventions. When you write a text file and want to insert a line
+ break, you need to use the correct line-ending character(s) for your
+ operating system. Unix based systems use <literal>\n</literal> as the
+ line ending character, Windows based systems use <literal>\r\n</literal>
+ as the line ending characters and Macintosh based systems use
+ <literal>\r</literal> as the the line ending character.
</para>
<para>
- The default translation mode depends on the SAPI that you are using, so
- you are encouraged to always specify the appropriate flag; you will
- usually always want to specify 'b' if you intend for your script to be
- portable between different platforms.
+ If you use the wrong line ending characters when writing your files, you
+ might find that other applications that open those files will "look
+ funny".
+ </para>
+ <para>
+ Windows offers a text-mode translation flag (<literal>'t'</literal>)
+ which will transparently translate <literal>\n</literal> to
+ <literal>\r\n</literal> when working with the file. In contrast, you
+ can also use <literal>'b'</literal> to force binary mode, which will not
+ translate your data. To use these flags, specify either
+ <literal>'b'</literal> or <literal>'t'</literal> as the last character
+ of the <parameter>mode</parameter> parameter.
+ </para>
+ <para>
+ The default translation mode depends on the SAPI and version of PHP that
+ you are using, so you are encouraged to always specify the appropriate
+ flag for portability reasons. You should use the <literal>'t'</literal>
+ mode if you are working with plain-text files and you use
+ <literal>\n</literal> to delimit your line endings in your script, but
+ expect your files to be readable with applications such as notepad. You
+ should use the <literal>'b'</literal> in all other cases.
</para>
<para>
If you do not specify the 'b' flag when working with binary files, you
- will experience strange problems with your data, including broken image
+ may experience strange problems with your data, including broken image
files and strange problems with <literal>\r\n</literal> characters.
</para>
<para>
- <emphasis>It is strongly recommended that you always use the 'b' flag
- when opening files with <function>fopen</function></emphasis>.
+ <emphasis>For portability, it is strongly recommended that you always
+ use the 'b' flag when opening files with <function>fopen</function>.
+ </emphasis>
+ </para>
+ <para>
+ <emphasis>Again, for portability, it is also strongly recommended that
+ you re-write code that uses or relies upon the <literal>'t'</literal>
+ mode so that it uses the correct line endings and
+ <literal>'b'</literal> mode instead.
+ </emphasis>
+ </para>
+ <para>
+ <emphasis>As of PHP 4.3.2, the default mode is set to binary for all
+ platforms that distinguish between binary and text mode. If you are
+ having problems with your scripts after upgrading, try using the
+ <literal>'t'</literal> flag as a workaround until you have made your
+ script more portable as mentioned above.
+ </emphasis>
</para>
</note>
<para>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
