path: root/tests/examplefiles/perlfunc.1

.\" 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