pygments.rb 0.6.3 → 1.0.0

data/vendor/pygments-main/tests/examplefiles/perl_regex-delims

@@ -1,120 +0,0 @@
-#! /usr/bin/env perl
-
-use strict;
-use warnings;
-
-# common delimiters
-print "a: ";
-my $a = "foo";
-print $a, " - ";
-$a =~ s/foo/bar/;
-print $a, "\n";
-
-print "b: ";
-my $b = "foo";
-print $b, " - ";
-$b =~ s!foo!bar!;
-print $b, "\n";
-
-print "c: ";
-my $c = "foo";
-print $c, " - ";
-$c =~ s@foo@bar@;
-print $c, "\n";
-
-print "d: ";
-my $d = "foo";
-print $d, " - ";
-$d =~ s\foo\bar\;
-print $d, "\n";
-
-print "\n";
-
-# balanced delimiters
-print "e: ";
-my $e = "foo";
-print $e, " - ";
-$e =~ s{foo}{bar};
-print $e, "\n";
-
-print "f: ";
-my $f = "foo";
-print $f, " - ";
-$f =~ s(foo)(bar);
-print $f, "\n";
-
-print "g: ";
-my $g = "foo";
-print $g, " - ";
-$g =~ s<foo><bar>;
-print $g, "\n";
-
-print "h: ";
-my $h = "foo";
-print $h, " - ";
-$h =~ s[foo][bar];
-print $h, "\n";
-
-print "\n";
-
-# balanced delimiters with whitespace
-print "i: ";
-my $i = "foo";
-print $i, " - ";
-$i =~ s{foo} {bar};
-print $i, "\n";
-
-print "j: ";
-my $j = "foo";
-print $j, " - ";
-$j =~ s<foo>		<bar>;
-print $j, "\n";
-
-print "k: ";
-my $k = "foo";
-print $k, " - ";
-$k =~
-	s(foo)
-
-	(bar);
-print $k, "\n";
-
-print "\n";
-
-# mixed delimiters
-print "l: ";
-my $l = "foo";
-print $l, " - ";
-$l =~ s{foo} <bar>;
-print $l, "\n";
-
-print "m: ";
-my $m = "foo";
-print $m, " - ";
-$m =~ s(foo) !bar!;
-print $m, "\n";
-
-print "n: ";
-my $n = "foo";
-print $n, " - ";
-$n =~ s[foo] $bar$;
-print $n, "\n";
-
-print "\n";
-
-# /x modifier
-print "o: ";
-my $o = "foo";
-print $o, " - ";
-$o =~ s{
-				foo
-			 } {bar}x;
-print $o, "\n";
-
-print "p: ";
-my $p = "foo";
-print $p, " - ";
-$p =~ s%
-  foo
-  %bar%x;
-print $p, "\n";

data/vendor/pygments-main/tests/examplefiles/perlfunc.1

@@ -1,856 +0,0 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings.  \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote.  | will give a
-.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-.    ds -- \(*W-
-.    ds PI pi
-.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
-.    ds L" ""
-.    ds R" ""
-.    ds C` ""
-.    ds C' ""
-'br\}
-.el\{\
-.    ds -- \|\(em\|
-.    ds PI \(*p
-.    ds L" ``
-.    ds R" ''
-'br\}
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
-.\" entries marked with X<> in POD.  Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.if \nF \{\
-.    de IX
-.    tm Index:\\$1\t\\n%\t"\\$2"
-..
-.    nr % 0
-.    rr F
-.\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
-.    \" fudge factors for nroff and troff
-.if n \{\
-.    ds #H 0
-.    ds #V .8m
-.    ds #F .3m
-.    ds #[ \f1
-.    ds #] \fP
-.\}
-.if t \{\
-.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-.    ds #V .6m
-.    ds #F 0
-.    ds #[ \&
-.    ds #] \&
-.\}
-.    \" simple accents for nroff and troff
-.if n \{\
-.    ds ' \&
-.    ds ` \&
-.    ds ^ \&
-.    ds , \&
-.    ds ~ ~
-.    ds /
-.\}
-.if t \{\
-.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-.    \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-.    \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-.    \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-.    ds : e
-.    ds 8 ss
-.    ds o a
-.    ds d- d\h'-1'\(ga
-.    ds D- D\h'-1'\(hy
-.    ds th \o'bp'
-.    ds Th \o'LP'
-.    ds ae ae
-.    ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "PERLFUNC 1"
-.TH PERLFUNC 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide"
-.SH "NAME"
-.IX Xref "function"
-perlfunc \- Perl builtin functions
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-The functions in this section can serve as terms in an expression.
-They fall into two major categories: list operators and named unary
-operators.  These differ in their precedence relationship with a
-following comma.  (See the precedence table in perlop.)  List
-operators take more than one argument, while unary operators can never
-take more than one argument.  Thus, a comma terminates the argument of
-a unary operator, but merely separates the arguments of a list
-operator.  A unary operator generally provides a scalar context to its
-argument, while a list operator may provide either scalar or list
-contexts for its arguments.  If it does both, the scalar arguments will
-be first, and the list argument will follow.  (Note that there can ever
-be only one such list argument.)  For instance, \fIsplice()\fR has three scalar
-arguments followed by a list, whereas \fIgethostbyname()\fR has four scalar
-arguments.
-.PP
-In the syntax descriptions that follow, list operators that expect a
-list (and provide list context for the elements of the list) are shown
-with \s-1LIST\s0 as an argument.  Such a list may consist of any combination
-of scalar arguments or list values; the list values will be included
-in the list as if each individual element were interpolated at that
-point in the list, forming a longer single-dimensional list value.
-Commas should separate elements of the \s-1LIST\s0.
-.PP
-Any function in the list below may be used either with or without
-parentheses around its arguments.  (The syntax descriptions omit the
-parentheses.)  If you use the parentheses, the simple (but occasionally
-surprising) rule is this: It \fIlooks\fR like a function, therefore it \fIis\fR a
-function, and precedence doesn't matter.  Otherwise it's a list
-operator or unary operator, and precedence does matter.  And whitespace
-between the function and left parenthesis doesn't count\*(--so you need to
-be careful sometimes:
-.PP
-.Vb 5
-\&    print 1+2+4;        # Prints 7.
-\&    print(1+2) + 4;     # Prints 3.
-\&    print (1+2)+4;      # Also prints 3!
-\&    print +(1+2)+4;     # Prints 7.
-\&    print ((1+2)+4);    # Prints 7.
-.Ve
-.PP
-If you run Perl with the \fB\-w\fR switch it can warn you about this.  For
-example, the third line above produces:
-.PP
-.Vb 2
-\&    print (...) interpreted as function at - line 1.
-\&    Useless use of integer addition in void context at - line 1.
-.Ve
-.PP
-A few functions take no arguments at all, and therefore work as neither
-unary nor list operators.  These include such functions as \f(CW\*(C`time\*(C'\fR
-and \f(CW\*(C`endpwent\*(C'\fR.  For example, \f(CW\*(C`time+86_400\*(C'\fR always means
-\&\f(CW\*(C`time() + 86_400\*(C'\fR.
-.PP
-For functions that can be used in either a scalar or list context,
-nonabortive failure is generally indicated in a scalar context by
-returning the undefined value, and in a list context by returning the
-null list.
-.PP
-Remember the following important rule: There is \fBno rule\fR that relates
-the behavior of an expression in list context to its behavior in scalar
-context, or vice versa.  It might do two totally different things.
-Each operator and function decides which sort of value it would be most
-appropriate to return in scalar context.  Some operators return the
-length of the list that would have been returned in list context.  Some
-operators return the first value in the list.  Some operators return the
-last value in the list.  Some operators return a count of successful
-operations.  In general, they do what you want, unless you want
-consistency.
-.IX Xref "context"
-.PP
-A named array in scalar context is quite different from what would at
-first glance appear to be a list in scalar context.  You can't get a list
-like \f(CW\*(C`(1,2,3)\*(C'\fR into being in scalar context, because the compiler knows
-the context at compile time.  It would generate the scalar comma operator
-there, not the list construction version of the comma.  That means it
-was never a list to start with.
-.PP
-In general, functions in Perl that serve as wrappers for system calls
-of the same name (like \fIchown\fR\|(2), \fIfork\fR\|(2), \fIclosedir\fR\|(2), etc.) all return
-true when they succeed and \f(CW\*(C`undef\*(C'\fR otherwise, as is usually mentioned
-in the descriptions below.  This is different from the C interfaces,
-which return \f(CW\*(C`\-1\*(C'\fR on failure.  Exceptions to this rule are \f(CW\*(C`wait\*(C'\fR,
-\&\f(CW\*(C`waitpid\*(C'\fR, and \f(CW\*(C`syscall\*(C'\fR.  System calls also set the special \f(CW$!\fR
-variable on failure.  Other functions do not, except accidentally.
-.Sh "Perl Functions by Category"
-.IX Xref "function"
-.IX Subsection "Perl Functions by Category"
-Here are Perl's functions (including things that look like
-functions, like some keywords and named operators)
-arranged by category.  Some functions appear in more
-than one place.
-.IP "Functions for SCALARs or strings" 4
-.IX Xref "scalar string character"
-.IX Item "Functions for SCALARs or strings"
-\&\f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chop\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`index\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR,
-\&\f(CW\*(C`length\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`ord\*(C'\fR, \f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`q/STRING/\*(C'\fR, \f(CW\*(C`qq/STRING/\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR,
-\&\f(CW\*(C`rindex\*(C'\fR, \f(CW\*(C`sprintf\*(C'\fR, \f(CW\*(C`substr\*(C'\fR, \f(CW\*(C`tr///\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`y///\*(C'\fR
-.IP "Regular expressions and pattern matching" 4
-.IX Xref "regular expression regex regexp"
-.IX Item "Regular expressions and pattern matching"
-\&\f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`pos\*(C'\fR, \f(CW\*(C`quotemeta\*(C'\fR, \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`split\*(C'\fR, \f(CW\*(C`study\*(C'\fR, \f(CW\*(C`qr//\*(C'\fR
-.IP "Numeric functions" 4
-.IX Xref "numeric number trigonometric trigonometry"
-.IX Item "Numeric functions"
-\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`atan2\*(C'\fR, \f(CW\*(C`cos\*(C'\fR, \f(CW\*(C`exp\*(C'\fR, \f(CW\*(C`hex\*(C'\fR, \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`log\*(C'\fR, \f(CW\*(C`oct\*(C'\fR, \f(CW\*(C`rand\*(C'\fR,
-\&\f(CW\*(C`sin\*(C'\fR, \f(CW\*(C`sqrt\*(C'\fR, \f(CW\*(C`srand\*(C'\fR
-.ie n .IP "Functions for real @ARRAYs" 4
-.el .IP "Functions for real \f(CW@ARRAYs\fR" 4
-.IX Xref "array"
-.IX Item "Functions for real @ARRAYs"
-\&\f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`splice\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR
-.IP "Functions for list data" 4
-.IX Xref "list"
-.IX Item "Functions for list data"
-\&\f(CW\*(C`grep\*(C'\fR, \f(CW\*(C`join\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`qw/STRING/\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, \f(CW\*(C`unpack\*(C'\fR
-.ie n .IP "Functions for real %HASHes" 4
-.el .IP "Functions for real \f(CW%HASHes\fR" 4
-.IX Xref "hash"
-.IX Item "Functions for real %HASHes"
-\&\f(CW\*(C`delete\*(C'\fR, \f(CW\*(C`each\*(C'\fR, \f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`keys\*(C'\fR, \f(CW\*(C`values\*(C'\fR
-.IP "Input and output functions" 4
-.IX Xref "I O input output dbm"
-.IX Item "Input and output functions"
-\&\f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`closedir\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`eof\*(C'\fR,
-\&\f(CW\*(C`fileno\*(C'\fR, \f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, \f(CW\*(C`read\*(C'\fR,
-\&\f(CW\*(C`readdir\*(C'\fR, \f(CW\*(C`rewinddir\*(C'\fR, \f(CW\*(C`seek\*(C'\fR, \f(CW\*(C`seekdir\*(C'\fR, \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR,
-\&\f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`sysseek\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, \f(CW\*(C`telldir\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR,
-\&\f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`write\*(C'\fR
-.IP "Functions for fixed length data or records" 4
-.IX Item "Functions for fixed length data or records"
-\&\f(CW\*(C`pack\*(C'\fR, \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, \f(CW\*(C`sysread\*(C'\fR, \f(CW\*(C`syswrite\*(C'\fR, \f(CW\*(C`unpack\*(C'\fR, \f(CW\*(C`vec\*(C'\fR
-.IP "Functions for filehandles, files, or directories" 4
-.IX Xref "file filehandle directory pipe link symlink"
-.IX Item "Functions for filehandles, files, or directories"
-\&\f(CW\*(C`\-\f(CIX\f(CW\*(C'\fR, \f(CW\*(C`chdir\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`glob\*(C'\fR,
-\&\f(CW\*(C`ioctl\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`mkdir\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`opendir\*(C'\fR,
-\&\f(CW\*(C`readlink\*(C'\fR, \f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`rmdir\*(C'\fR, \f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR,
-\&\f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR, \f(CW\*(C`utime\*(C'\fR
-.IP "Keywords related to the control flow of your Perl program" 4
-.IX Xref "control flow"
-.IX Item "Keywords related to the control flow of your Perl program"
-\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`continue\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`exit\*(C'\fR,
-\&\f(CW\*(C`goto\*(C'\fR, \f(CW\*(C`last\*(C'\fR, \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, \f(CW\*(C`wantarray\*(C'\fR
-.IP "Keywords related to scoping" 4
-.IX Item "Keywords related to scoping"
-\&\f(CW\*(C`caller\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`use\*(C'\fR
-.IP "Miscellaneous functions" 4
-.IX Item "Miscellaneous functions"
-\&\f(CW\*(C`defined\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`eval\*(C'\fR, \f(CW\*(C`formline\*(C'\fR, \f(CW\*(C`local\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`reset\*(C'\fR,
-\&\f(CW\*(C`scalar\*(C'\fR, \f(CW\*(C`undef\*(C'\fR, \f(CW\*(C`wantarray\*(C'\fR
-.IP "Functions for processes and process groups" 4
-.IX Xref "process pid process id"
-.IX Item "Functions for processes and process groups"
-\&\f(CW\*(C`alarm\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`kill\*(C'\fR,
-\&\f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`qx/STRING/\*(C'\fR, \f(CW\*(C`setpgrp\*(C'\fR, \f(CW\*(C`setpriority\*(C'\fR, \f(CW\*(C`sleep\*(C'\fR, \f(CW\*(C`system\*(C'\fR,
-\&\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR
-.IP "Keywords related to perl modules" 4
-.IX Xref "module"
-.IX Item "Keywords related to perl modules"
-\&\f(CW\*(C`do\*(C'\fR, \f(CW\*(C`import\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`require\*(C'\fR, \f(CW\*(C`use\*(C'\fR
-.IP "Keywords related to classes and object-orientedness" 4
-.IX Xref "object class package"
-.IX Item "Keywords related to classes and object-orientedness"
-\&\f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`package\*(C'\fR, \f(CW\*(C`ref\*(C'\fR, \f(CW\*(C`tie\*(C'\fR, \f(CW\*(C`tied\*(C'\fR,
-\&\f(CW\*(C`untie\*(C'\fR, \f(CW\*(C`use\*(C'\fR
-.IP "Low-level socket functions" 4
-.IX Xref "socket sock"
-.IX Item "Low-level socket functions"
-\&\f(CW\*(C`accept\*(C'\fR, \f(CW\*(C`bind\*(C'\fR, \f(CW\*(C`connect\*(C'\fR, \f(CW\*(C`getpeername\*(C'\fR, \f(CW\*(C`getsockname\*(C'\fR,
-\&\f(CW\*(C`getsockopt\*(C'\fR, \f(CW\*(C`listen\*(C'\fR, \f(CW\*(C`recv\*(C'\fR, \f(CW\*(C`send\*(C'\fR, \f(CW\*(C`setsockopt\*(C'\fR, \f(CW\*(C`shutdown\*(C'\fR,
-\&\f(CW\*(C`socket\*(C'\fR, \f(CW\*(C`socketpair\*(C'\fR
-.IP "System V interprocess communication functions" 4
-.IX Xref "IPC System V semaphore shared memory memory message"
-.IX Item "System V interprocess communication functions"
-\&\f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR, \f(CW\*(C`msgrcv\*(C'\fR, \f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`semctl\*(C'\fR, \f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR,
-\&\f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR, \f(CW\*(C`shmread\*(C'\fR, \f(CW\*(C`shmwrite\*(C'\fR
-.IP "Fetching user and group info" 4
-.IX Xref "user group password uid gid passwd  etc passwd"
-.IX Item "Fetching user and group info"
-\&\f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR, \f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR, \f(CW\*(C`getgrent\*(C'\fR,
-\&\f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`getgrnam\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR,
-\&\f(CW\*(C`getpwuid\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR
-.IP "Fetching network info" 4
-.IX Xref "network protocol host hostname IP address service"
-.IX Item "Fetching network info"
-\&\f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`gethostbyaddr\*(C'\fR, \f(CW\*(C`gethostbyname\*(C'\fR,
-\&\f(CW\*(C`gethostent\*(C'\fR, \f(CW\*(C`getnetbyaddr\*(C'\fR, \f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR,
-\&\f(CW\*(C`getprotobyname\*(C'\fR, \f(CW\*(C`getprotobynumber\*(C'\fR, \f(CW\*(C`getprotoent\*(C'\fR,
-\&\f(CW\*(C`getservbyname\*(C'\fR, \f(CW\*(C`getservbyport\*(C'\fR, \f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR,
-\&\f(CW\*(C`setnetent\*(C'\fR, \f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setservent\*(C'\fR
-.IP "Time-related functions" 4
-.IX Xref "time date"
-.IX Item "Time-related functions"
-\&\f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR, \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`times\*(C'\fR
-.IP "Functions new in perl5" 4
-.IX Xref "perl5"
-.IX Item "Functions new in perl5"
-\&\f(CW\*(C`abs\*(C'\fR, \f(CW\*(C`bless\*(C'\fR, \f(CW\*(C`chomp\*(C'\fR, \f(CW\*(C`chr\*(C'\fR, \f(CW\*(C`exists\*(C'\fR, \f(CW\*(C`formline\*(C'\fR, \f(CW\*(C`glob\*(C'\fR,
-\&\f(CW\*(C`import\*(C'\fR, \f(CW\*(C`lc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR, \f(CW\*(C`map\*(C'\fR, \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`no\*(C'\fR, \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`prototype\*(C'\fR,
-\&\f(CW\*(C`qx\*(C'\fR, \f(CW\*(C`qw\*(C'\fR, \f(CW\*(C`readline\*(C'\fR, \f(CW\*(C`readpipe\*(C'\fR, \f(CW\*(C`ref\*(C'\fR, \f(CW\*(C`sub*\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`tie\*(C'\fR,
-\&\f(CW\*(C`tied\*(C'\fR, \f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`ucfirst\*(C'\fR, \f(CW\*(C`untie\*(C'\fR, \f(CW\*(C`use\*(C'\fR
-.Sp
-* \- \f(CW\*(C`sub\*(C'\fR was a keyword in perl4, but in perl5 it is an
-operator, which can be used in expressions.
-.IP "Functions obsoleted in perl5" 4
-.IX Item "Functions obsoleted in perl5"
-\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR
-.Sh "Portability"
-.IX Xref "portability Unix portable"
-.IX Subsection "Portability"
-Perl was born in Unix and can therefore access all common Unix
-system calls.  In non-Unix environments, the functionality of some
-Unix system calls may not be available, or details of the available
-functionality may differ slightly.  The Perl functions affected
-by this are:
-.PP
-\&\f(CW\*(C`\-X\*(C'\fR, \f(CW\*(C`binmode\*(C'\fR, \f(CW\*(C`chmod\*(C'\fR, \f(CW\*(C`chown\*(C'\fR, \f(CW\*(C`chroot\*(C'\fR, \f(CW\*(C`crypt\*(C'\fR,
-\&\f(CW\*(C`dbmclose\*(C'\fR, \f(CW\*(C`dbmopen\*(C'\fR, \f(CW\*(C`dump\*(C'\fR, \f(CW\*(C`endgrent\*(C'\fR, \f(CW\*(C`endhostent\*(C'\fR,
-\&\f(CW\*(C`endnetent\*(C'\fR, \f(CW\*(C`endprotoent\*(C'\fR, \f(CW\*(C`endpwent\*(C'\fR, \f(CW\*(C`endservent\*(C'\fR, \f(CW\*(C`exec\*(C'\fR,
-\&\f(CW\*(C`fcntl\*(C'\fR, \f(CW\*(C`flock\*(C'\fR, \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`getgrent\*(C'\fR, \f(CW\*(C`getgrgid\*(C'\fR, \f(CW\*(C`gethostbyname\*(C'\fR,
-\&\f(CW\*(C`gethostent\*(C'\fR, \f(CW\*(C`getlogin\*(C'\fR, \f(CW\*(C`getnetbyaddr\*(C'\fR, \f(CW\*(C`getnetbyname\*(C'\fR, \f(CW\*(C`getnetent\*(C'\fR,
-\&\f(CW\*(C`getppid\*(C'\fR, \f(CW\*(C`getpgrp\*(C'\fR, \f(CW\*(C`getpriority\*(C'\fR, \f(CW\*(C`getprotobynumber\*(C'\fR,
-\&\f(CW\*(C`getprotoent\*(C'\fR, \f(CW\*(C`getpwent\*(C'\fR, \f(CW\*(C`getpwnam\*(C'\fR, \f(CW\*(C`getpwuid\*(C'\fR,
-\&\f(CW\*(C`getservbyport\*(C'\fR, \f(CW\*(C`getservent\*(C'\fR, \f(CW\*(C`getsockopt\*(C'\fR, \f(CW\*(C`glob\*(C'\fR, \f(CW\*(C`ioctl\*(C'\fR,
-\&\f(CW\*(C`kill\*(C'\fR, \f(CW\*(C`link\*(C'\fR, \f(CW\*(C`lstat\*(C'\fR, \f(CW\*(C`msgctl\*(C'\fR, \f(CW\*(C`msgget\*(C'\fR, \f(CW\*(C`msgrcv\*(C'\fR,
-\&\f(CW\*(C`msgsnd\*(C'\fR, \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`pipe\*(C'\fR, \f(CW\*(C`readlink\*(C'\fR, \f(CW\*(C`rename\*(C'\fR, \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`semctl\*(C'\fR,
-\&\f(CW\*(C`semget\*(C'\fR, \f(CW\*(C`semop\*(C'\fR, \f(CW\*(C`setgrent\*(C'\fR, \f(CW\*(C`sethostent\*(C'\fR, \f(CW\*(C`setnetent\*(C'\fR,
-\&\f(CW\*(C`setpgrp\*(C'\fR, \f(CW\*(C`setpriority\*(C'\fR, \f(CW\*(C`setprotoent\*(C'\fR, \f(CW\*(C`setpwent\*(C'\fR,
-\&\f(CW\*(C`setservent\*(C'\fR, \f(CW\*(C`setsockopt\*(C'\fR, \f(CW\*(C`shmctl\*(C'\fR, \f(CW\*(C`shmget\*(C'\fR, \f(CW\*(C`shmread\*(C'\fR,
-\&\f(CW\*(C`shmwrite\*(C'\fR, \f(CW\*(C`socket\*(C'\fR, \f(CW\*(C`socketpair\*(C'\fR,
-\&\f(CW\*(C`stat\*(C'\fR, \f(CW\*(C`symlink\*(C'\fR, \f(CW\*(C`syscall\*(C'\fR, \f(CW\*(C`sysopen\*(C'\fR, \f(CW\*(C`system\*(C'\fR,
-\&\f(CW\*(C`times\*(C'\fR, \f(CW\*(C`truncate\*(C'\fR, \f(CW\*(C`umask\*(C'\fR, \f(CW\*(C`unlink\*(C'\fR,
-\&\f(CW\*(C`utime\*(C'\fR, \f(CW\*(C`wait\*(C'\fR, \f(CW\*(C`waitpid\*(C'\fR
-.PP
-For more information about the portability of these functions, see
-perlport and other available platform-specific documentation.
-.Sh "Alphabetical Listing of Perl Functions"
-.IX Subsection "Alphabetical Listing of Perl Functions"
-.IP "\-X \s-1FILEHANDLE\s0" 8
-.IX Xref "-r -w -x -o -R -W -X -O -e -z -s -f -d -l -p -S -b -c -t -u -g -k -T -B -M -A -C"
-.IX Item "-X FILEHANDLE"
-.PD 0
-.IP "\-X \s-1EXPR\s0" 8
-.IX Item "-X EXPR"
-.IP "\-X" 8
-.IX Item "-X"
-.PD
-A file test, where X is one of the letters listed below.  This unary
-operator takes one argument, either a filename or a filehandle, and
-tests the associated file to see if something is true about it.  If the
-argument is omitted, tests \f(CW$_\fR, except for \f(CW\*(C`\-t\*(C'\fR, which tests \s-1STDIN\s0.
-Unless otherwise documented, it returns \f(CW1\fR for true and \f(CW''\fR for false, or
-the undefined value if the file doesn't exist.  Despite the funny
-names, precedence is the same as any other named unary operator, and
-the argument may be parenthesized like any other unary operator.  The
-operator may be any of:
-.Sp
-.Vb 4
-\&    -r  File is readable by effective uid/gid.
-\&    -w  File is writable by effective uid/gid.
-\&    -x  File is executable by effective uid/gid.
-\&    -o  File is owned by effective uid.
-.Ve
-.Sp
-.Vb 4
-\&    -R  File is readable by real uid/gid.
-\&    -W  File is writable by real uid/gid.
-\&    -X  File is executable by real uid/gid.
-\&    -O  File is owned by real uid.
-.Ve
-.Sp
-.Vb 3
-\&    -e  File exists.
-\&    -z  File has zero size (is empty).
-\&    -s  File has nonzero size (returns size in bytes).
-.Ve
-.Sp
-.Vb 8
-\&    -f  File is a plain file.
-\&    -d  File is a directory.
-\&    -l  File is a symbolic link.
-\&    -p  File is a named pipe (FIFO), or Filehandle is a pipe.
-\&    -S  File is a socket.
-\&    -b  File is a block special file.
-\&    -c  File is a character special file.
-\&    -t  Filehandle is opened to a tty.
-.Ve
-.Sp
-.Vb 3
-\&    -u  File has setuid bit set.
-\&    -g  File has setgid bit set.
-\&    -k  File has sticky bit set.
-.Ve
-.Sp
-.Vb 2
-\&    -T  File is an ASCII text file (heuristic guess).
-\&    -B  File is a "binary" file (opposite of -T).
-.Ve
-.Sp
-.Vb 3
-\&    -M  Script start time minus file modification time, in days.
-\&    -A  Same for access time.
-\&    -C  Same for inode change time (Unix, may differ for other platforms)
-.Ve
-.Sp
-Example:
-.Sp
-.Vb 5
-\&    while (<>) {
-\&        chomp;
-\&        next unless -f $_;      # ignore specials
-\&        #...
-\&    }
-.Ve
-.Sp
-The interpretation of the file permission operators \f(CW\*(C`\-r\*(C'\fR, \f(CW\*(C`\-R\*(C'\fR,
-\&\f(CW\*(C`\-w\*(C'\fR, \f(CW\*(C`\-W\*(C'\fR, \f(CW\*(C`\-x\*(C'\fR, and \f(CW\*(C`\-X\*(C'\fR is by default based solely on the mode
-of the file and the uids and gids of the user.  There may be other
-reasons you can't actually read, write, or execute the file.  Such
-reasons may be for example network filesystem access controls, ACLs
-(access control lists), read-only filesystems, and unrecognized
-executable formats.
-.Sp
-Also note that, for the superuser on the local filesystems, the \f(CW\*(C`\-r\*(C'\fR,
-\&\f(CW\*(C`\-R\*(C'\fR, \f(CW\*(C`\-w\*(C'\fR, and \f(CW\*(C`\-W\*(C'\fR tests always return 1, and \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR return 1
-if any execute bit is set in the mode.  Scripts run by the superuser
-may thus need to do a \fIstat()\fR to determine the actual mode of the file,
-or temporarily set their effective uid to something else.
-.Sp
-If you are using ACLs, there is a pragma called \f(CW\*(C`filetest\*(C'\fR that may
-produce more accurate results than the bare \fIstat()\fR mode bits.
-When under the \f(CW\*(C`use filetest 'access'\*(C'\fR the above-mentioned filetests
-will test whether the permission can (not) be granted using the
-\&\fIaccess()\fR family of system calls.  Also note that the \f(CW\*(C`\-x\*(C'\fR and \f(CW\*(C`\-X\*(C'\fR may
-under this pragma return true even if there are no execute permission
-bits set (nor any extra execute permission ACLs).  This strangeness is
-due to the underlying system calls' definitions.  Read the
-documentation for the \f(CW\*(C`filetest\*(C'\fR pragma for more information.
-.Sp
-Note that \f(CW\*(C`\-s/a/b/\*(C'\fR does not do a negated substitution.  Saying
-\&\f(CW\*(C`\-exp($foo)\*(C'\fR still works as expected, however\*(--only single letters
-following a minus are interpreted as file tests.
-.Sp
-The \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR switches work as follows.  The first block or so of the
-file is examined for odd characters such as strange control codes or
-characters with the high bit set.  If too many strange characters (>30%)
-are found, it's a \f(CW\*(C`\-B\*(C'\fR file; otherwise it's a \f(CW\*(C`\-T\*(C'\fR file.  Also, any file
-containing null in the first block is considered a binary file.  If \f(CW\*(C`\-T\*(C'\fR
-or \f(CW\*(C`\-B\*(C'\fR is used on a filehandle, the current \s-1IO\s0 buffer is examined
-rather than the first block.  Both \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR return true on a null
-file, or a file at \s-1EOF\s0 when testing a filehandle.  Because you have to
-read a file to do the \f(CW\*(C`\-T\*(C'\fR test, on most occasions you want to use a \f(CW\*(C`\-f\*(C'\fR
-against the file first, as in \f(CW\*(C`next unless \-f $file && \-T $file\*(C'\fR.
-.Sp
-If any of the file tests (or either the \f(CW\*(C`stat\*(C'\fR or \f(CW\*(C`lstat\*(C'\fR operators) are given
-the special filehandle consisting of a solitary underline, then the stat
-structure of the previous file test (or stat operator) is used, saving
-a system call.  (This doesn't work with \f(CW\*(C`\-t\*(C'\fR, and you need to remember
-that \fIlstat()\fR and \f(CW\*(C`\-l\*(C'\fR will leave values in the stat structure for the
-symbolic link, not the real file.)  (Also, if the stat buffer was filled by
-an \f(CW\*(C`lstat\*(C'\fR call, \f(CW\*(C`\-T\*(C'\fR and \f(CW\*(C`\-B\*(C'\fR will reset it with the results of \f(CW\*(C`stat _\*(C'\fR).
-Example:
-.Sp
-.Vb 1
-\&    print "Can do.\en" if -r $a || -w _ || -x _;
-.Ve
-.Sp
-.Vb 9
-\&    stat($filename);
-\&    print "Readable\en" if -r _;
-\&    print "Writable\en" if -w _;
-\&    print "Executable\en" if -x _;
-\&    print "Setuid\en" if -u _;
-\&    print "Setgid\en" if -g _;
-\&    print "Sticky\en" if -k _;
-\&    print "Text\en" if -T _;
-\&    print "Binary\en" if -B _;
-.Ve
-.IP "abs \s-1VALUE\s0" 8
-.IX Xref "abs absolute"
-.IX Item "abs VALUE"
-.PD 0
-.IP "abs" 8
-.IX Item "abs"
-.PD
-Returns the absolute value of its argument.
-If \s-1VALUE\s0 is omitted, uses \f(CW$_\fR.
-.IP "accept \s-1NEWSOCKET\s0,GENERICSOCKET" 8
-.IX Xref "accept"
-.IX Item "accept NEWSOCKET,GENERICSOCKET"
-Accepts an incoming socket connect, just as the \fIaccept\fR\|(2) system call
-does.  Returns the packed address if it succeeded, false otherwise.
-See the example in \*(L"Sockets: Client/Server Communication\*(R" in perlipc.
-.Sp
-On systems that support a close-on-exec flag on files, the flag will
-be set for the newly opened file descriptor, as determined by the
-value of $^F.  See \*(L"$^F\*(R" in perlvar.
-.IP "alarm \s-1SECONDS\s0" 8
-.IX Xref "alarm SIGALRM timer"
-.IX Item "alarm SECONDS"
-.PD 0
-.IP "alarm" 8
-.IX Item "alarm"
-.PD
-Arranges to have a \s-1SIGALRM\s0 delivered to this process after the
-specified number of wallclock seconds has elapsed.  If \s-1SECONDS\s0 is not
-specified, the value stored in \f(CW$_\fR is used. (On some machines,
-unfortunately, the elapsed time may be up to one second less or more
-than you specified because of how seconds are counted, and process
-scheduling may delay the delivery of the signal even further.)
-.Sp
-Only one timer may be counting at once.  Each call disables the
-previous timer, and an argument of \f(CW0\fR may be supplied to cancel the
-previous timer without starting a new one.  The returned value is the
-amount of time remaining on the previous timer.
-.Sp
-For delays of finer granularity than one second, you may use Perl's
-four-argument version of \fIselect()\fR leaving the first three arguments
-undefined, or you might be able to use the \f(CW\*(C`syscall\*(C'\fR interface to
-access \fIsetitimer\fR\|(2) if your system supports it.  The Time::HiRes
-module (from \s-1CPAN\s0, and starting from Perl 5.8 part of the standard
-distribution) may also prove useful.
-.Sp
-It is usually a mistake to intermix \f(CW\*(C`alarm\*(C'\fR and \f(CW\*(C`sleep\*(C'\fR calls.
-(\f(CW\*(C`sleep\*(C'\fR may be internally implemented in your system with \f(CW\*(C`alarm\*(C'\fR)
-.Sp
-If you want to use \f(CW\*(C`alarm\*(C'\fR to time out a system call you need to use an
-\&\f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR pair.  You can't rely on the alarm causing the system call to
-fail with \f(CW$!\fR set to \f(CW\*(C`EINTR\*(C'\fR because Perl sets up signal handlers to
-restart system calls on some systems.  Using \f(CW\*(C`eval\*(C'\fR/\f(CW\*(C`die\*(C'\fR always works,
-modulo the caveats given in \*(L"Signals\*(R" in perlipc.
-.Sp
-.Vb 13
-\&    eval {
-\&        local $SIG{ALRM} = sub { die "alarm\en" }; # NB: \en required
-\&        alarm $timeout;
-\&        $nread = sysread SOCKET, $buffer, $size;
-\&        alarm 0;
-\&    };
-\&    if ($@) {
-\&        die unless $@ eq "alarm\en";   # propagate unexpected errors
-\&        # timed out
-\&    }
-\&    else {
-\&        # didn't
-\&    }
-.Ve
-.Sp
-For more information see perlipc.
-.IP "atan2 Y,X" 8
-.IX Xref "atan2 arctangent tan tangent"
-.IX Item "atan2 Y,X"
-Returns the arctangent of Y/X in the range \-PI to \s-1PI\s0.
-.Sp
-For the tangent operation, you may use the \f(CW\*(C`Math::Trig::tan\*(C'\fR
-function, or use the familiar relation:
-.Sp
-.Vb 1
-\&    sub tan { sin($_[0]) / cos($_[0])  }
-.Ve
-.Sp
-Note that atan2(0, 0) is not well\-defined.
-.IP "bind \s-1SOCKET\s0,NAME" 8
-.IX Xref "bind"
-.IX Item "bind SOCKET,NAME"
-Binds a network address to a socket, just as the bind system call
-does.  Returns true if it succeeded, false otherwise.  \s-1NAME\s0 should be a
-packed address of the appropriate type for the socket.  See the examples in
-\&\*(L"Sockets: Client/Server Communication\*(R" in perlipc.
-.IP "binmode \s-1FILEHANDLE\s0, \s-1LAYER\s0" 8
-.IX Xref "binmode binary text DOS Windows"
-.IX Item "binmode FILEHANDLE, LAYER"
-.PD 0
-.IP "binmode \s-1FILEHANDLE\s0" 8
-.IX Item "binmode FILEHANDLE"
-.PD
-Arranges for \s-1FILEHANDLE\s0 to be read or written in \*(L"binary\*(R" or \*(L"text\*(R"
-mode on systems where the run-time libraries distinguish between
-binary and text files.  If \s-1FILEHANDLE\s0 is an expression, the value is
-taken as the name of the filehandle.  Returns true on success,
-otherwise it returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$!\fR (errno).
-.Sp
-On some systems (in general, \s-1DOS\s0 and Windows-based systems) \fIbinmode()\fR
-is necessary when you're not working with a text file.  For the sake
-of portability it is a good idea to always use it when appropriate,
-and to never use it when it isn't appropriate.  Also, people can
-set their I/O to be by default \s-1UTF\-8\s0 encoded Unicode, not bytes.
-.Sp
-In other words: regardless of platform, use \fIbinmode()\fR on binary data,
-like for example images.
-.Sp
-If \s-1LAYER\s0 is present it is a single string, but may contain multiple
-directives. The directives alter the behaviour of the file handle.
-When \s-1LAYER\s0 is present using binmode on text file makes sense.
-.Sp
-If \s-1LAYER\s0 is omitted or specified as \f(CW\*(C`:raw\*(C'\fR the filehandle is made
-suitable for passing binary data. This includes turning off possible \s-1CRLF\s0
-translation and marking it as bytes (as opposed to Unicode characters).
-Note that, despite what may be implied in \fI\*(L"Programming Perl\*(R"\fR (the
-Camel) or elsewhere, \f(CW\*(C`:raw\*(C'\fR is \fInot\fR the simply inverse of \f(CW\*(C`:crlf\*(C'\fR
-\&\*(-- other layers which would affect binary nature of the stream are
-\&\fIalso\fR disabled. See PerlIO, perlrun and the discussion about the
-\&\s-1PERLIO\s0 environment variable.
-.Sp
-The \f(CW\*(C`:bytes\*(C'\fR, \f(CW\*(C`:crlf\*(C'\fR, and \f(CW\*(C`:utf8\*(C'\fR, and any other directives of the
-form \f(CW\*(C`:...\*(C'\fR, are called I/O \fIlayers\fR.  The \f(CW\*(C`open\*(C'\fR pragma can be used to
-establish default I/O layers.  See open.
-.Sp
-\&\fIThe \s-1LAYER\s0 parameter of the \fIbinmode()\fI function is described as \*(L"\s-1DISCIPLINE\s0\*(R"
-in \*(L"Programming Perl, 3rd Edition\*(R".  However, since the publishing of this
-book, by many known as \*(L"Camel \s-1III\s0\*(R", the consensus of the naming of this
-functionality has moved from \*(L"discipline\*(R" to \*(L"layer\*(R".  All documentation
-of this version of Perl therefore refers to \*(L"layers\*(R" rather than to
-\&\*(L"disciplines\*(R".  Now back to the regularly scheduled documentation...\fR
-.Sp
-To mark \s-1FILEHANDLE\s0 as \s-1UTF\-8\s0, use \f(CW\*(C`:utf8\*(C'\fR.
-.Sp
-In general, \fIbinmode()\fR should be called after \fIopen()\fR but before any I/O
-is done on the filehandle.  Calling \fIbinmode()\fR will normally flush any
-pending buffered output data (and perhaps pending input data) on the
-handle.  An exception to this is the \f(CW\*(C`:encoding\*(C'\fR layer that
-changes the default character encoding of the handle, see open.
-The \f(CW\*(C`:encoding\*(C'\fR layer sometimes needs to be called in
-mid\-stream, and it doesn't flush the stream.  The \f(CW\*(C`:encoding\*(C'\fR
-also implicitly pushes on top of itself the \f(CW\*(C`:utf8\*(C'\fR layer because
-internally Perl will operate on \s-1UTF\-8\s0 encoded Unicode characters.
-.Sp
-The operating system, device drivers, C libraries, and Perl run-time
-system all work together to let the programmer treat a single
-character (\f(CW\*(C`\en\*(C'\fR) 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 \f(CW\*(C`\en\*(C'\fR is made up of more than
-one character.
-.Sp
-Mac \s-1OS\s0, all variants of Unix, and Stream_LF files on \s-1VMS\s0 use a single
-character to end each line in the external representation of text (even
-though that single character is \s-1CARRIAGE\s0 \s-1RETURN\s0 on Mac \s-1OS\s0 and \s-1LINE\s0 \s-1FEED\s0
-on Unix and most \s-1VMS\s0 files). In other systems like \s-1OS/2\s0, \s-1DOS\s0 and the
-various flavors of MS-Windows your program sees a \f(CW\*(C`\en\*(C'\fR as a simple \f(CW\*(C`\ecJ\*(C'\fR,
-but what's stored in text files are the two characters \f(CW\*(C`\ecM\ecJ\*(C'\fR.  That
-means that, if you don't use \fIbinmode()\fR on these systems, \f(CW\*(C`\ecM\ecJ\*(C'\fR
-sequences on disk will be converted to \f(CW\*(C`\en\*(C'\fR on input, and any \f(CW\*(C`\en\*(C'\fR in
-your program will be converted back to \f(CW\*(C`\ecM\ecJ\*(C'\fR on output.  This is what
-you want for text files, but it can be disastrous for binary files.
-.Sp
-Another consequence of using \fIbinmode()\fR (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 \f(CW\*(C`\ecZ\*(C'\fR, the I/O subsystem will regard it as the end of
-the file, unless you use \fIbinmode()\fR.
-.Sp
-\&\fIbinmode()\fR is not only important for \fIreadline()\fR and \fIprint()\fR operations,
-but also when using \fIread()\fR, \fIseek()\fR, \fIsysread()\fR, \fIsyswrite()\fR and \fItell()\fR
-(see perlport for more details).  See the \f(CW$/\fR and \f(CW\*(C`$\e\*(C'\fR variables
-in perlvar for how to manually set your input and output
-line-termination sequences.
-.IP "bless \s-1REF\s0,CLASSNAME" 8
-.IX Xref "bless"
-.IX Item "bless REF,CLASSNAME"
-.PD 0
-.IP "bless \s-1REF\s0" 8
-.IX Item "bless REF"
-.PD
-This function tells the thingy referenced by \s-1REF\s0 that it is now an object
-in the \s-1CLASSNAME\s0 package.  If \s-1CLASSNAME\s0 is omitted, the current package
-is used.  Because a \f(CW\*(C`bless\*(C'\fR is often the last thing in a constructor,
-it returns the reference for convenience.  Always use the two-argument
-version if a derived class might inherit the function doing the blessing.
-See perltoot and perlobj for more about the blessing (and blessings)
-of objects.
-.Sp
-Consider always blessing objects in CLASSNAMEs that are mixed case.
-Namespaces with all lowercase names are considered reserved for
-Perl pragmata.  Builtin types have all uppercase names. To prevent
-confusion, you may wish to avoid such package names as well.  Make sure
-that \s-1CLASSNAME\s0 is a true value.
-.Sp
-See \*(L"Perl Modules\*(R" in perlmod.
-.IP "caller \s-1EXPR\s0" 8
-.IX Xref "caller call stack stack stack trace"
-.IX Item "caller EXPR"
-.PD 0
-.IP "caller" 8
-.IX Item "caller"
-.PD
-Returns the context of the current subroutine call.  In scalar context,
-returns the caller's package name if there is a caller, that is, if
-we're in a subroutine or \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR, and the undefined value
-otherwise.  In list context, returns
-.Sp
-.Vb 1
-\&    ($package, $filename, $line) = caller;
-.Ve
-.Sp
-With \s-1EXPR\s0, it returns some extra information that the debugger uses to
-print a stack trace.  The value of \s-1EXPR\s0 indicates how many call frames
-to go back before the current one.
-.Sp
-.Vb 2
-\&    ($package, $filename, $line, $subroutine, $hasargs,
-\&    $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i);
-.Ve
-.Sp
-Here \f(CW$subroutine\fR may be \f(CW\*(C`(eval)\*(C'\fR if the frame is not a subroutine
-call, but an \f(CW\*(C`eval\*(C'\fR.  In such a case additional elements \f(CW$evaltext\fR and
-\&\f(CW$is_require\fR are set: \f(CW$is_require\fR is true if the frame is created by a
-\&\f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR statement, \f(CW$evaltext\fR contains the text of the
-\&\f(CW\*(C`eval EXPR\*(C'\fR statement.  In particular, for an \f(CW\*(C`eval BLOCK\*(C'\fR statement,
-\&\f(CW$filename\fR is \f(CW\*(C`(eval)\*(C'\fR, but \f(CW$evaltext\fR is undefined.  (Note also that
-each \f(CW\*(C`use\*(C'\fR statement creates a \f(CW\*(C`require\*(C'\fR frame inside an \f(CW\*(C`eval EXPR\*(C'\fR
-frame.)  \f(CW$subroutine\fR may also be \f(CW\*(C`(unknown)\*(C'\fR if this particular
-subroutine happens to have been deleted from the symbol table.
-\&\f(CW$hasargs\fR is true if a new instance of \f(CW@_\fR was set up for the frame.
-\&\f(CW$hints\fR and \f(CW$bitmask\fR contain pragmatic hints that the caller was
-compiled with.  The \f(CW$hints\fR and \f(CW$bitmask\fR values are subject to change
-between versions of Perl, and are not meant for external use.
-.Sp
-Furthermore, when called from within the \s-1DB\s0 package, caller returns more
-detailed information: it sets the list variable \f(CW@DB::args\fR to be the
-arguments with which the subroutine was invoked.
-.Sp
-Be aware that the optimizer might have optimized call frames away before
-\&\f(CW\*(C`caller\*(C'\fR had a chance to get the information.  That means that \f(CWcaller(N)\fR
-might not return information about the call frame you expect it do, for
-\&\f(CW\*(C`N > 1\*(C'\fR.  In particular, \f(CW@DB::args\fR might have information from the
-previous time \f(CW\*(C`caller\*(C'\fR was called.
-.IP "chdir \s-1EXPR\s0" 8
-.IX Xref "chdir cd"
-.IX Item "chdir EXPR"
-.PD 0
-.IP "chdir \s-1FILEHANDLE\s0" 8
-.IX Item "chdir FILEHANDLE"
-.IP "chdir \s-1DIRHANDLE\s0" 8
-.IX Item "chdir DIRHANDLE"
-.IP "chdir" 8
-.IX Item "chdir"
-.PD
-Changes the working directory to \s-1EXPR\s0, if possible. If \s-1EXPR\s0 is omitted,
-changes to the directory specified by \f(CW$ENV{HOME}\fR, if set; if not,
-changes to the directory specified by \f(CW$ENV{LOGDIR}\fR. (Under \s-1VMS\s0, the
-variable \f(CW$ENV{SYS$LOGIN}\fR is also checked, and used if it is set.) If
-neither is set, \f(CW\*(C`chdir\*(C'\fR does nothing. It returns true upon success,
-false otherwise. See the example under \f(CW\*(C`die\*(C'\fR.
-.Sp
-On systems that support fchdir, you might pass a file handle or
-directory handle as argument.  On systems that don't support fchdir,
-passing handles produces a fatal error at run time.
-.IP "chmod \s-1LIST\s0" 8
-.IX Xref "chmod permission mode"
-.IX Item "chmod LIST"
-Changes the permissions of a list of files.  The first element of the
-list must be the numerical mode, which should probably be an octal
-number, and which definitely should \fInot\fR be a string of octal digits:
-\&\f(CW0644\fR is okay, \f(CW'0644'\fR is not.  Returns the number of files
-successfully changed.  See also \*(L"oct\*(R", if all you have is a string.
-.Sp
-.Vb 6
-\&    $cnt = chmod 0755, 'foo', 'bar';
-\&    chmod 0755, @executables;
-\&    $mode = '0644'; chmod $mode, 'foo';      # !!! sets mode to
-\&                                             # --w----r-T
-\&    $mode = '0644'; chmod oct($mode), 'foo'; # this is better
-\&    $mode = 0644;   chmod $mode, 'foo';      # this is best
-.Ve
-.Sp
-On systems that support fchmod, you might pass file handles among the
-files.  On systems that don't support fchmod, passing file handles
-produces a fatal error at run time.
-.Sp
-.Vb 3
-\&    open(my $fh, "<", "foo");
-\&    my $perm = (stat $fh)[2] & 07777;
-\&    chmod($perm | 0600, $fh);
-.Ve
-.Sp
-You can also import the symbolic \f(CW\*(C`S_I*\*(C'\fR constants from the Fcntl
-module:
-.Sp
-.Vb 1
-\&    use Fcntl ':mode';
-.Ve
-.Sp
-.Vb 2
-\&    chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
-\&    # This is identical to the chmod 0755 of the above example.
-.Ve
-.IP "chomp \s-1VARIABLE\s0" 8
-.IX Xref "chomp INPUT_RECORD_SEPARATOR $ newline eol"
-.IX Item "chomp VARIABLE"
-.PD 0
-.IP "chomp( \s-1LIST\s0 )" 8
-.IX Item "chomp( LIST )"
-.IP "chomp" 8
-.IX Item "chomp"
-.PD
-This safer version of \*(L"chop\*(R" removes any trailing string
-that corresponds to the current value of \f(CW$/\fR (also known as
-\&\f(CW$INPUT_RECORD_SEPARATOR\fR in the \f(CW\*(C`English\*(C'\fR module).  It returns the total
-number of characters removed from all its arguments.  It's often used to
-remove the newline from the end of an input record when you're worried
-that the final record may be missing its newline.  When in paragraph
-mode (\f(CW\*(C`$/ = ""\*(C'\fR), it removes all trailing newlines from the string.
-When in slurp mode (\f(CW\*(C`$/ = undef\*(C'\fR) or fixed-length record mode (\f(CW$/\fR is
-a reference to an integer or the like, see perlvar) \fIchomp()\fR won't
-remove anything.
-If \s-1VARIABLE\s0 is omitted, it chomps \f(CW$_\fR.  Example:
-.Sp
-.Vb 5
-\&    while (<>) {
-\&        chomp;  # avoid \en on last field
-\&        @array = split(/:/);
-\&        # ...
-\&    }
-.Ve
-.Sp
-If \s-1VARIABLE\s0 is a hash, it chomps the hash's values, but not its keys.
-.Sp
-