[ID 20000225.001] Suggested new wording for binmode() perlfunc entry

This is a bug report for perl from mgjv@martien.heliotrope.home,
generated with the help of perlbug 1.26 running under perl 5.00503.


-----------------------------------------------------------------
[Please enter your report here]

The wording of the entry for binmode() in the perlfunc man page is
slightly OS-biased, and not clear enough for many people. The 5.5.660
version is a lot better than the 5.005_03, but still leaves some room
for improvement (apart from containing an error).

=item binmode FILEHANDLE

Arranges for FILEHANDLE to be read or written in "binary" mode on
systems where the run-time libraries distinguish between binary and
text files.  If FILEHANDLE is an expression, the value is taken as the
name of the filehandle.  binmode() should be called after open() but
before any I/O is done on the filehandle.  The only way to reset
binary mode on a filehandle is to reopen the file.

On many systems binmode() has no effect, and on some systems it is
necessary when you're not working with a text file.  For the sake of
cross-platform portability it is a good idea to always use it when
appropriate, and to never use it when it isn't appropriate.

In other words:  Regardless of platform, use binmode() on binary
files, and do not use binmode() on text files.

The operating system, device drivers, C libraries, and Perl run-time
system all work together to let the programmer treat a single
character (C<\n>) as the line terminator, irrespective of the external
representation.  On many operating systems, the native text file
representation matches the internal representation, but on some
platforms the external representation of C<\n> is made up of more than
one character.

Mac OS and all variants of Unix use a single character to end each line
in the external representation of text (even though that single
character is not necessarily the same across these platforms).
Consequently binmode() has no effect on these operating systems.  In
other systems like VMS, MS-DOS and the various flavors of MS-Windows
your program sees a C<\n> as a simple C<\cJ>, but what's stored in text
files are the two characters C<\cM\cJ>.  That means that, if you don't
use binmode() on these systems, C<\cM\cJ> sequences on disk will be
converted to C<\n> on input, and any C<\n> in your program will be
converted back to C<\cM\cJ> on output.  This is what you want for text
files, but it can be disastrous for binary files.

Another consequence of using binmode() (on some systems) is that
special end-of-file markers will be seen as part of the data stream.
For systems from the Microsoft family this means that if your binary
data contains C<\cZ>, the I/O subsystem will ragard it as the end of
the file, unless you use binmode().

binmode() is not only important for readline() and print() operations,
but also when using read(), seek(), sysread(), syswrite() and tell()
(see L<perlport> for more details).  See the C<$/> and C<$\> variables
in L<perlvar> for how to manually set your input and output
line-termination sequences.


[Please do not change anything below this line]
-----------------------------------------------------------------

---
Site configuration information for perl 5.00503:

Configured by mgjv at Mon Nov 22 21:58:09 EST 1999.

Summary of my perl5 (5.0 patchlevel 5 subversion 3) configuration:
  Platform:
    osname=linux, osvers=2.2.12-20, archname=i686-linux
    uname='linux martien 2.2.12-20 #1 mon sep 27 10:40:35 edt 1999 i686 unknown '
    hint=recommended, useposix=true, d_sigaction=define
    usethreads=undef useperlio=undef d_sfio=undef
  Compiler:
    cc='cc', optimize='-O2', gccversion=egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)
    cppflags='-Dbool=char -DHAS_BOOL -I/usr/local/include'
    ccflags ='-Dbool=char -DHAS_BOOL -I/usr/local/include'
    stdchar='char', d_stdstdio=undef, usevfork=false
    intsize=4, longsize=4, ptrsize=4, doublesize=8
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
    alignbytes=4, usemymalloc=n, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib
    libs=-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lposix -lcrypt
    libc=, so=so, useshrplib=false, libperl=libperl.a
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-rdynamic'
    cccdlflags='-fpic', lddlflags='-shared -L/usr/local/lib'

Locally applied patches:
    

---
@INC for perl 5.00503:
    /opt/perl5.00503/lib/5.00503/i686-linux
    /opt/perl5.00503/lib/5.00503
    /opt/perl5.00503/lib/site_perl/5.005/i686-linux
    /opt/perl5.00503/lib/site_perl/5.005
    .

---
Environment for perl 5.00503:
    HOME=/home/mgjv
    LANG=en_US
    LANGUAGE (unset)
    LC_ALL=en_US
    LD_LIBRARY_PATH=:/opt/gimp/lib
    LOGDIR (unset)
    PATH=/home/mgjv/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/opt/perl/bin:/opt/ImageMagick/bin:/opt/gimp/bin
    PERL_BADLANG (unset)
    SHELL=/bin/tcsh

• [ID 20000225.001] Suggested new wording for binmode() perlfunc entry by Martien Verbruggen