\input texinfo   @c -*-texinfo-*-
@setfilename perl
@settitle Perl Manual

@setchapternewpage odd
@ifinfo
@comment %**start of header (This is for running Texinfo on a region.)
This file documents perl, Practical Extraction and Report Language, and
was originally based on Larry Wall's unix-style man page for perl.

GNU Texinfo version adapted by Jeff Kellem <composer@@chem.bu.edu>.

Copyright @copyright{} 1989, 1990, 1991 Larry Wall
Texinfo version Copyright @copyright{} 1990, 1991 Jeff Kellem

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``GNU General Public License'' and ``Conditions for
Using Perl'' are included exactly as in the original, and provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU General Public License'' and this
permission notice may be included in translations approved by the Free
Software Foundation instead of in the original English.
@end ifinfo

@titlepage
@title Perl Manual (Texinfo version)
@subtitle for perl version 4.0 patchlevel 03
@subtitle Edition 0.4, dated 15 April 1991, printed on @today{}

@sp 2
@center This is a @strong{DRAFT} copy of the Texinfo version of the perl manual!

@author Original man page by Larry Wall <lwall@@jpl-devvax.jpl.nasa.gov>
@author Texinfo version by Jeff Kellem <composer@@chem.bu.edu>
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1989, 1990, 1991 Larry Wall
@*
Texinfo version Copyright @copyright{} 1990, 1991 Jeff Kellem

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``GNU General Public License'' and ``Conditions for
Using Perl'' are included exactly as in the original, and provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU General Public License'' and this
permission notice may be included in translations approved by the Free
Software Foundation instead of in the original English.
@comment %**end of header (This is for running Texinfo on a region.)
@end titlepage

@node     Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up

@ifinfo
This Info file contains edition 0.4, dated 15 April 1991, "printed" on
@today{} of the Perl Manual for Perl version 4.0 patchlevel 03.

This is a @strong{DRAFT} copy of the Texinfo version of the perl manual!
@end ifinfo

@menu
* Introduction::        A quick introduction to the manual.
* Copying::             The GNU General Public License says how you can
                          copy and share Perl.
* Conditions::          Conditions for Using Perl. (Larry Wall's interpretation
                          of the GPL and how it affects perl scripts.)

* Preface::               A quick description of perl.  (The hype.)
* Perl Startup::          Where perl looks for scripts; perl's options.
* Data Types::            Perl's data types and objects.
* Syntax::                Perl language syntax.
* Compound Statements::   What is a compound statement in Perl?
* Simple Statements::     What is a simple statement in Perl?
* Expressions::           What are valid expressions in Perl?
* Commands::              All of perl's functions.
* Precedence::            Operator precedence in Perl.
* Subroutines::           Defining subroutines in Perl.
* Passing By Reference::  How to pass args by reference in Perl.
* Regular Expressions::   Perl's pattern matching capabilities.
* Formats::               Report formats.
* Interprocess Communication:: Networking in Perl.
* Predefined Names::      Predefined variables.
* Packages::              What is a Perl package?  Find out here.
* Style::                 Suggestions on programming style.
* Debugging::             The Perl debugger.
* Setuid Scripts::        Setuid Perl scripts.
* Environment::           Environment variables Perl utilizes.
* a2p::                   Awk to Perl conversion program.
* s2p::                   Sed to Perl conversion program.
* h2ph::                  Converting C header files into Perl header files.
* Diagnostics::           What do the error messages mean?
* Traps::                 Traps and Pitfalls for C, sh, sed, awk programmers.
* Bugs::                  Known problems in Perl.
                            (Mainly dependent upon your machine.)
* Credits::               The Credits.  Who worked on what.
* Errata::                Errata and Addenda.


* Command Summary::     Summary of commands (syntax only).

Indices
* Concept Index::       (mega ;-)Index of Concepts.
* Function Index::      Index of Commands/Functions.
@end menu

@node     Introduction, Copying, Top, Top
@comment  node-name,  next,  previous,  up
@unnumbered Introduction
@cindex Introduction to the Manual
@cindex Manual Introduction

This Texinfo manual describes PERL, the Practical Extraction and
Report Language.  The manual is, currently, mainly a conversion of Larry
Wall's original unix-style man page into Texinfo format.  In the
future, new sections will be added, such as tutorial sections and more
examples.@refill

The Texinfo version of the perl manual is maintained and distributed by
Jeff Kellem.  His electronic mail address is composer@@chem.bu.edu.
There is a mailing list for discussion of the Texinfo version of the
perl manual and a mailing address for reporting bugs in this version of
the manual.  They are:@refill

@example
@strong{Mailing Address}                     @strong{What The Address Is For}
perl-manual-request@@chem.bu.edu    administrivia (add/drop requests)
perl-manual@@chem.bu.edu            discussion of the Texinfo perl manual
bug-perl-manual@@chem.bu.edu        reporting bugs in the perl manual
@end example

If you would like to join the discussion of the perl manual, send a note to

@example
perl-manual-request@@chem.bu.edu
@end example

@node Copying, Conditions, Introduction, Top
@unnumbered GNU General Public License
@cindex GNU General Public License (GPL)
@cindex GPL (General Public License), GNU
@center Version 1, February 1989

@display
Copyright @copyright{} 1989 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The license agreements of most software companies try to keep users
at the mercy of those companies.  By contrast, our General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  The
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of a such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS
@end iftex
@ifinfo
@center TERMS AND CONDITIONS
@end ifinfo

@enumerate
@item
This License Agreement applies to any program or other work which
contains a notice placed by the copyright holder saying it may be
distributed under the terms of this General Public License.  The
``Program'', below, refers to any such program or work, and a ``work based
on the Program'' means either the Program or any work containing the
Program or a portion of it, either verbatim or with modifications.  Each
licensee is addressed as ``you''.@refill

@item
You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
General Public License and to the absence of any warranty; and give any
other recipients of the Program a copy of this General Public License
along with the Program.  You may charge a fee for the physical act of
transferring a copy.@refill

@item
You may modify your copy or copies of the Program or any portion of
it, and copy and distribute such modifications under the terms of Paragraph
1 above, provided that you also do the following:@refill

@itemize @bullet
@item
cause the modified files to carry prominent notices stating that
you changed the files and the date of any change; and

@item
cause the whole of any work that you distribute or publish, that
in whole or in part contains the Program or any part thereof, either
with or without modifications, to be licensed at no charge to all
third parties under the terms of this General Public License (except
that you may choose to grant warranty protection to some or all
third parties, at your option).@refill

@item
If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive use
in the simplest and most usual way, to print or display an
announcement including an appropriate copyright notice and a notice
that there is no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this General
Public License.@refill

@item
You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.@refill
@end itemize

Mere aggregation of another independent work with the Program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other work under the scope of these terms.@refill

@item
You may copy and distribute the Program (or a portion or derivative of
it, under Paragraph 2) in object code or executable form under the terms
of Paragraphs 1 and 2 above provided that you also do one of the
following:@refill

@itemize @bullet
@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal charge
for the cost of distribution) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,@refill

@item
accompany it with the information you received as to where the
corresponding source code may be obtained.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)@refill
@end itemize

Source code for a work means the preferred form of the work for making
modifications to it.  For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.@refill

@item
You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
the Program is void, and will automatically terminate your rights to use
the Program under this License.  However, parties who have received
copies, or rights to use copies, from you under this General Public
License will not have their licenses terminated so long as such parties
remain in full compliance.@refill

@item
By copying, distributing or modifying the Program (or any work based
on the Program) you indicate your acceptance of this license to do so,
and all its terms and conditions.@refill

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the original
licensor to copy, distribute or modify the Program subject to these
terms and conditions.  You may not impose any further restrictions on the
recipients' exercise of the rights granted herein.@refill

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.@refill

Each version is given a distinguishing version number.  If the Program
specifies a version number of the license which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
the license, you may choose any version ever published by the Free Software
Foundation.@refill

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.@refill

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec Appendix: How to Apply These Terms

  If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@end smallexample

@noindent
Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
@end smallexample

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items---whatever suits your
program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (a program to direct compilers to make passes at
assemblers) written by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end smallexample

@noindent
That's all there is to it!

@node     Conditions, Preface, Copying, Top
@comment  node-name,  next,  previous,  up
@unnumbered Conditions for Using Perl
@cindex Conditions for Using Perl
@cindex Perl Conditions
@cindex Larry Wall's Interpretation of the GNU GPL

@noindent
[ Note: The following is from the author of Perl, Larry Wall. ]

My interpretation of the GNU General Public License is that no Perl
script falls under the terms of the License unless you explicitly put
said script under the terms of the License yourself.  Furthermore, any
object code linked with uperl.o does not automatically fall under the
terms of the License, provided such object code only adds definitions
of subroutines and variables, and does not otherwise impair the
resulting interpreter from executing any standard Perl script.  I
consider linking in C subroutines in this manner to be the moral
equivalent of defining subroutines in the Perl language itself.  You
may sell such an object file as proprietary provided that you provide
or offer to provide the Perl source, as specified by the GNU General
Public License.  (This is merely an alternate way of specifying input
to the program.)  You may also sell a binary produced by the dumping of
a running Perl script that belongs to you, provided that you provide or
offer to provide the Perl source as specified by the License.  (The
fact that a Perl interpreter and your code are in the same binary file
is, in this case, a form of mere aggregation.)  This is my
interpretation of the License.  If you still have concerns or
difficulties understanding my intent, feel free to contact me.

@node     Preface, Perl Startup, Conditions, Top
@comment  node-name,  next,  previous,  up
@chapter Description
@cindex Hype
@cindex Preface
@cindex Quick description of Perl
@cindex Description of Perl
@cindex General Description of Perl

@dfn{Perl} is an interpreted language optimized for scanning arbitrary
text files, extracting information from those text files, and printing
reports based on that information.  It's also a good language for many
system management tasks.  The language is intended to be practical (easy
to use, efficient, complete) rather than beautiful (tiny, elegant,
minimal).  It combines (in the author's opinion, anyway) some of the
best features of @code{C}, @code{sed}, @code{awk}, and @code{sh}, so
people familiar with those languages should have little difficulty with
it.  (Language historians will also note some vestiges of @code{csh},
@code{Pascal}, and even @code{BASIC-PLUS}.)  Expression syntax
corresponds quite closely to C expression syntax.  Unlike most Unix
utilities, @emph{perl} does not arbitrarily limit the size of your
data---if you've got the memory, @emph{perl} can slurp in your whole
file as a single string.  Recursion is of unlimited depth.  And the hash
tables used by associative arrays grow as necessary to prevent degraded
performance.  @emph{Perl} uses sophisticated pattern matching techniques
to scan large amounts of data very quickly.  Although optimized for
scanning text, @emph{perl} can also deal with binary data, and can make
dbm files look like associative arrays (where dbm is available).  Setuid
@emph{perl} scripts are safer than C programs through a dataflow tracing
mechanism which prevents many stupid security holes.  If you have a
problem that would ordinarily use @code{sed} or @code{awk} or @code{sh},
but it exceeds their capabilities or must run a little faster, and you
don't want to write the silly thing in C, then @emph{perl} may be for
you.  There are also translators to turn your @code{sed} and @code{awk}
scripts into @emph{perl} scripts.  OK, enough hype.@refill


@node Perl Startup, Data Types, Preface, Top
@comment  node-name,  next,  previous,  up
@chapter Perl Startup

@noindent
Upon startup, @emph{perl} looks for your script in one of the following
places:

@enumerate
@item
Specified line by line via @samp{-e} switches on the command line.

@item
Contained in the file specified by the first filename on the command
line.  (Note that systems supporting the @samp{#!} notation invoke
interpreters this way.)@refill

@item
Passed in implicitly via standard input.  This only works if there are
no filename arguments---to pass arguments to a @code{stdin} script you
must explicitly specify a @samp{-} for the script name.@refill
@end enumerate

After locating your script, @emph{perl} compiles it to an internal form.
If the script is syntactically correct, it is executed.

@menu
* Options::             Command line options.
@end menu

@node     Options, , , Perl Startup
@comment  node-name,  next,  previous,  up
@section Options
@cindex Options
@cindex Command Line Options
@cindex Arguments
@cindex Command Line Arguments

@c @@@@ following was orig for man pg, may remove in the future @@@@
Note: on first reading this section may not make much sense to you.  It's here
at the front for easy reference.

A single-character option may be combined with the following option, if
any.  This is particularly useful when invoking a script using the
@samp{#!} construct which only allows one argument.  Example:@refill

@example
#!/usr/bin/perl -spi.bak        # same as -s -p -i.bak
@dots{}
@end example

@noindent
Options include:

@table @samp
@item -0 digits
specifies the record separator ($/) as an octal number.  If there are no
digits, the null character is the separator.  Other switches may precede
or follow the digits.  For example, if you have a version of @code{find}
which can print filenames terminated by the null character, you can say
this:@refill

@example
find . -name '*.bak' -print0 | perl -n0e unlink
@end example

The special value @samp{00} will cause Perl to slurp files in paragraph
mode.  The value @samp{0777} will cause Perl to slurp files whole since
there is no legal character with that value.@refill

@item -a
turns on autosplit mode when used with a @samp{-n} or @samp{-p}.  An
implicit split command to the @samp{@@F} array is done as the first thing
inside the implicit while loop produced by the @samp{-n} or
@samp{-p}.@refill

@example
perl -ane 'print pop(@@F), "\n";'
@end example

is equivalent to

@example
while (<>) @{
        @@F = split(' ');
        print pop(@@F), "\n";
@}
@end example

@item -c
causes @emph{perl} to check the syntax of the script and then exit
without executing it.@refill

@item -d
runs the script under the perl debugger.
@xref{Debugging}, for more info.

@item -D number
sets debugging flags.  To watch how it executes your script, use
@samp{-D14}.  (This only works if debugging is compiled into your
@emph{perl}.)  Another nice value is @samp{-D1024}, which lists your
compiled syntax tree.  And @samp{-D512} displays compiled regular
expressions.@refill

@item -e commandline
may be used to enter one line of script.  Multiple @samp{-e} commands
may be given to build up a multi-line script.  If @samp{-e} is given,
@emph{perl} will not look for a script filename in the argument
list.@refill

@item -i extension
specifies that files processed by the @samp{<>} construct are to be edited
in-place.  It does this by renaming the input file, opening the output
file by the same name, and selecting that output file as the default for
print statements.  The extension, if supplied, is added to the name of
the old file to make a backup copy.  If no extension is supplied, no
backup is made.  Saying@refill

@example
perl -p -i.bak -e "s/foo/bar/;" @dots{}
@end example

is the same as using the script:@refill

@example
#!/usr/bin/perl -pi.bak
s/foo/bar/;
@end example

which is equivalent to

@example
#!/usr/bin/perl
while (<>) @{
        if ($ARGV ne $oldargv) @{
                rename($ARGV, $ARGV . '.bak');
                open(ARGVOUT, ">$ARGV");
                select(ARGVOUT);
                $oldargv = $ARGV;
        @}
        s/foo/bar/;
@}
continue @{
    print;      # this prints to original filename
@}
select(STDOUT);
@end example

@cindex @samp{ARGVOUT} filehandle
except that the @samp{-i} form doesn't need to compare @samp{$ARGV} to
@samp{$oldargv} to know when the filename has changed.  It does, however,
use @samp{ARGVOUT} for the selected filehandle.  Note that @samp{STDOUT}
is restored as the default output filehandle after the loop.@refill

You can use @code{eof} to locate the end of each input file, in case you
want to append to each file, or reset line numbering
(@pxref{Input/Output}, for an example).@refill

@item -I directory
may be used in conjunction with @samp{-P} to tell the C preprocessor
where to look for include files.  By default @file{/usr/include} and
@file{/usr/lib/perl} are searched.@refill

@item -l octnum
enables automatic line-ending processing.  It has two effects: first, it
automatically chops the line terminator when used with @samp{-n} or
@samp{-p}, and second, it assigns @samp{$\} to have the value of
@var{octnum} so that any print statements will have that line terminator
added back on.  If @var{octnum} is omitted, sets @samp{$\} to the
current value of @samp{$/}.  For instance, to trim lines to 80
columns:@refill

@example
perl -lpe 'substr($_, 80) = ""'
@end example

Note that the assignment @code{$\ = $/} is done when the switch is
processed, so the input record separator can be different than the
output record separator if the @samp{-l} switch is followed by a
@samp{-0} switch:@refill

@example
gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
@end example

This sets @samp{$\} to newline and then sets @samp{$/} to the null
character.@refill

@item -n
causes @emph{perl} to assume the following loop around your script,
which makes it iterate over filename arguments somewhat like
@code{sed -n} or @code{awk}:@refill

@example
while (<>) @{
        @dots{}         # your script goes here
@}
@end example

Note that the lines are @emph{not} printed by default.  See @samp{-p}
option to have lines printed.  Here is an efficient way to delete all
files older than a week:@refill

[ before version 4.003 ]
@example
find . -mtime +7 -print | perl -ne 'chop;unlink;'
@end example

[ version 4.003 and beyond ]
@example
find . -mtime +7 -print | perl -nle 'unlink;'
@end example

This is faster than using the @samp{-exec} switch of find because you
don't have to start a process on every filename found.@refill

@item -p
causes @emph{perl} to assume the following loop around your script,
which makes it iterate over filename arguments somewhat like
@code{sed}:@refill

@example
while (<>) @{
        @dots{}         # your script goes here
@} continue @{
        print;
@}
@end example

Note that the lines are printed automatically.  To suppress printing use
the @samp{-n} switch.  A @samp{-p} overrides a @samp{-n} switch.@refill

@item -P
causes your script to be run through the C preprocessor before
compilation by @emph{perl}.  (Since both comments and cpp directives
begin with the @samp{#} character, you should avoid starting comments
with any words recognized by the C preprocessor such as @code{if},
@code{else} or @code{define}.)@refill

@item -s
enables some rudimentary switch parsing for switches on the command line
after the script name but before any filename arguments (or before a
@samp{--}).  Any switch found there is removed from @samp{@@ARGV} and
sets the corresponding variable in the @emph{perl} script.  The
following script prints @samp{true} if and only if the script is invoked
with a @samp{-xyz} switch.@refill

@example
#!/usr/bin/perl -s
if ($xyz) @{ print "true\n"; @}
@end example

@item -S
makes @emph{perl} use the @samp{PATH} environment variable to search for the
script (unless the name of the script starts with a slash).  Typically
this is used to emulate @samp{#!} startup on machines that don't support
@samp{#!}, in the following manner:@refill

@example
#!/usr/bin/perl
eval "exec /usr/bin/perl -S $0 $*"
        if $running_under_some_shell;
@end example

The system ignores the first line and feeds the script to
@file{/bin/sh}, which proceeds to try to execute the @emph{perl} script
as a shell script.  The shell executes the second line as a normal shell
command, and thus starts up the @emph{perl} interpreter.  On some
systems @samp{$0} doesn't always contain the full pathname, so the
@samp{-S} tells @emph{perl} to search for the script if necessary.
After @emph{perl} locates the script, it parses the lines and ignores
them because the variable @samp{$running_under_some_shell} is never
true.  A better construct than @samp{$*} would be @samp{$@{1+"$@@"@}},
which handles embedded spaces and such in the filenames, but doesn't
work if the script is being interpreted by @code{csh}.  In order to
start up @code{sh} rather than @code{csh}, some systems may have to
replace the @samp{#!} line with a line containing just a colon, which
will be politely ignored by @emph{perl}.  Other systems can't control
that, and need a totally devious construct that will work under any of
@code{csh}, @code{sh} or @code{perl}, such as the following:@refill

@example
@c @@@@ maybe explain this hack @@@@
eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 $@{1+"$@@"@}'
& eval 'exec /usr/bin/perl -S $0 $argv:q'
        if 0;
@end example

@item -u
causes @emph{perl} to dump core after compiling your script.  You can
then take this core dump and turn it into an executable file by using
the @code{undump} program (not supplied).  This speeds startup at the
expense of some disk space (which you can minimize by stripping the
executable).  (Still, a ``hello world'' executable comes out to about
200K on my machine.)  If you are going to run your executable as a
set-id program then you should probably compile it using taintperl
rather than normal perl.  If you want to execute a portion of your
script before dumping, use the @code{dump} operator instead.  Note:
availability of @code{undump} is platform specific and may not be
available for a specific port of @emph{perl}.@refill

@item -U
allows @emph{perl} to do unsafe operations.  Currently the only
@samp{unsafe} operation is the unlinking of directories while
running as superuser.@refill

@item -v
prints the version and patchlevel of your @emph{perl} executable.@refill

@item -w
prints warnings about identifiers that are mentioned only once, and
scalar variables that are used before being set.  Also warns about
redefined subroutines, and references to undefined filehandles or
filehandles opened readonly that you are attempting to write on.  Also
warns you if you use @samp{==} on values that don't look like numbers,
and if your subroutines recurse more than 100 deep.@refill

@item -x directory
tells @emph{perl} that the script is embedded in a message.  Leading
garbage will be discarded until the first line that starts with
@samp{#!} and contains the string ``perl''.  Any meaningful switches on
that line will be applied (but only one group of switches, as with
normal @samp{#!} processing).  If a directory name is specified,
@emph{perl} will switch to that directory before running the script.
The @samp{-x} switch only controls the the disposal of leading garbage.
The script must be terminated with @samp{__END__} if there is trailing
garbage to be ignored (the script can process any or all of the trailing
garbage via the @samp{DATA} filehandle if desired).@refill
@c @@@@ maybe not have samp@{__END__@} above @@@@
@end table

@node Data Types, Syntax, Perl Startup, Top
@comment  node-name,  next,  previous,  up
@chapter Data Types and Objects
@cindex Data Types
@cindex Data Objects
@cindex Types, Data
@cindex Objects, Data

@emph{Perl} has three data types: scalars, arrays of scalars, and
associative arrays of scalars.  Normal arrays are indexed by number,
and associative arrays by string.@refill

The interpretation of operations and values in perl sometimes depends on
the requirements of the context around the operation or value.  There
are three major contexts: @dfn{string}, @dfn{numeric} and @dfn{array}.
Certain operations return array values in contexts wanting an array, and
scalar values otherwise.  (If this is true of an operation it will be
mentioned in the documentation for that operation.)  Operations which
return scalars don't care whether the context is looking for a string or
a number, but scalar variables and values are interpreted as strings or
numbers as appropriate to the context.  A scalar is interpreted as TRUE
in the boolean sense if it is not the null string or 0.  Booleans
returned by operators are 1 for TRUE and 0 or @'@' (the null string [two
single right quotes]) for FALSE.@refill

There are actually two varieties of null strings: @dfn{defined} and
@dfn{undefined}.  Undefined null strings are returned when there is no
real value for something, such as when there was an error, or at end of
file, or when you refer to an uninitialized variable or element of an
array.  An undefined null string may become defined the first time you
access it, but prior to that you can use the @code{defined()} operator
to determine whether the value is defined or not.@refill

References to scalar variables always begin with @samp{$}, even when
referring to a scalar that is part of an array.  Thus:@refill

@example
$days               # a simple scalar variable
$days[28]           # 29th element of array @@days
$days@{'Feb'@}        # one value from an associative array
$#days              # last index of array @@days
@end example

@noindent
but entire arrays or array slices are denoted by @samp{@@}:

@example
@@days              # ($days[0], $days[1],@dots{} $days[n])
@@days[3,4,5]       # same as @@days[3..5]
@@days@{'a','c'@}     # same as ($days@{'a'@},$days@{'c'@})
@end example

@noindent
and entire associative arrays are denoted by @samp{%}:

@example
%days               # (key1, val1, key2, val2 @dots{})
@end example

@c ADD a xref to s,tr,chop pages @@@@
Any of these eight constructs may serve as an lvalue, that is, may be
assigned to.  (It also turns out that an assignment is itself an lvalue
in certain contexts---see examples under @code{s}, @code{tr} and
@code{chop}.)  Assignment to a scalar evaluates the righthand side in a
scalar context, while assignment to an array or array slice evaluates
the righthand side in an array context.@refill

You may find the length of array @samp{@@days} by evaluating
@samp{$#days}, as in @code{csh}.  (Actually, it's not the length of the
array, it's the subscript of the last element, since there is
(ordinarily) a 0th element.)  Assigning to @samp{$#days} changes the
length of the array.  Shortening an array by this method does not
actually destroy any values.  Lengthening an array that was previously
shortened recovers the values that were in those elements.  You can also
gain some measure of efficiency by preextending an array that is going
to get big.  (You can also extend an array by assigning to an element
that is off the end of the array.  This differs from assigning to
@samp{$#whatever} in that intervening values are set to null rather than
recovered.)  You can truncate an array down to nothing by assigning the
null list @samp{()} to it.  The following are exactly equivalent:@refill

@example
@@whatever = ();
$#whatever = $[ - 1;
@end example

@noindent
If you evaluate an array in a scalar context, it returns the length of
the array.  The following is always true:@refill

@example
@@whatever == $#whatever - $[ + 1;
@end example

Multi-dimensional arrays are not directly supported, but see the
discussion of the @samp{$;} variable later for a means of emulating
multiple subscripts with an associative array.  You could also write a
subroutine to turn multiple subscripts into a single subscript.@refill

Every data type has its own namespace.  You can, without fear of
conflict, use the same name for a scalar variable, an array, an
associative array, a filehandle, a subroutine name, and/or a label.
Since variable and array references always start with @samp{$},
@samp{@@}, or @samp{%}, the @dfn{reserved} words aren't in
fact reserved with respect to variable names.  (They @strong{ARE}
reserved with respect to labels and filehandles, however, which don't
have an initial special character.  Hint: you could say
@code{open(LOG,'logfile')} rather than @code{open(log,'logfile')}.
Using uppercase filehandles also improves readability and protects you
from conflict with future reserved words.)  Case @strong{IS}
significant---@samp{FOO}, @samp{Foo} and @samp{foo} are all different
names.  Names which start with a letter may also contain digits and
underscores.  Names which do not start with a letter are limited to one
character, e.g. @samp{$%} or @samp{$$}.  (Most of the one character
names have a predefined significance to @emph{perl}.  More
later.)@refill

Numeric literals are specified in any of the usual floating point or
integer formats:
@cindex Numeric literals
@cindex Literals, numeric

@example
12345
12345.67
.23E-10
0xffff      # hex
0377        # octal
@end example

@cindex String literals
@cindex Literals, string
String literals are delimited by either single or double quotes.  They
work much like shell quotes: double-quoted string literals are subject
to backslash and variable substitution; single-quoted strings are not
(except for \' and \\).  The usual backslash rules apply for making
characters such as newline, tab, etc., as well as some more exotic
forms:@refill

@example
\t      tab
\n      newline
\r      return
\f      form feed
\b      backspace
\a      alarm (bell)
\e      escape
\033    octal char
\x1b    hex char
\c[     control char
\l      lowercase next char
\u      uppercase next char
\L      lowercase till \E
\U      uppercase till \E
\E      end case modification
@end example

You can also embed newlines directly in your strings, i.e. they can end
on a different line than they begin.  This is nice, but if you forget
your trailing quote, the error will not be reported until @emph{perl}
finds another line containing the quote character, which may be much
further on in the script.  Variable substitution inside strings is
limited to scalar variables, normal array values, and array slices.  (In
other words, identifiers beginning with @samp{$} or @samp{@@}, followed
by an optional bracketed expression as a subscript.)  The following code
segment prints out @samp{The price is $100.}@refill

@example
$Price = '$100';                    # not interpreted
print "The price is $Price.\n";     # interpreted
@end example

Note that you can put curly brackets around the identifier to delimit it
from following alphanumerics.  Also note that a single quoted string
must be separated from a preceding word by a space, since single quote
is a valid character in an identifier.  @xref{Packages}, for more
info.@refill

@c @@@@ look at next 2 paragraphs .. is this how we want things? @@@@
Two special literals are @samp{__LINE__} and @samp{__FILE__}, which
represent the current line number and filename at that point in your
program.  They may only be used as separate tokens; they will not be
interpolated into strings.  In addition, the token @samp{__END__} may be
used to indicate the logical end of the script before the actual end of
file.  Any following text is ignored (but may be read via the
@samp{DATA} filehandle).  The two control characters @kbd{@ctrl{D}} and
@kbd{@ctrl{Z}} are synonyms for @samp{__END__}.@refill

A word that doesn't have any other interpretation in the grammar will be
treated as if it had single quotes around it.  For this purpose, a word
consists only of alphanumeric characters and underline, and must start
with an alphabetic character.  As with filehandles and labels, a bare
word that consists entirely of lowercase letters risks conflict with
future reserved words, and if you use the @samp{-w} switch, @emph{perl}
will warn you about any such words.@refill

Array values are interpolated into double-quoted strings by joining all
the elements of the array with the delimiter specified in the @samp{$"}
variable, space by default.  (Since in versions of perl prior to 3.0 the
@samp{@@} character was not a metacharacter in double-quoted strings,
the interpolation of @samp{@@array}, @samp{$array[EXPR]},
@samp{@@array[LIST]}, @samp{$array@{EXPR@}}, or @samp{@@array@{LIST@}}
only happens if array is referenced elsewhere in the program or is
predefined.)  The following are equivalent:@refill

@example
$temp = join($",@@ARGV);
system "echo $temp";
system "echo @@ARGV";
@end example

Within search patterns (which also undergo double-quotish substitution)
there is a bad ambiguity: Is @samp{/$foo[bar]/} to be interpreted as
@samp{/$@{foo@}[bar]/} (where @samp{[bar]} is a character class for the
regular expression) or as @samp{/$@{foo[bar]@}/} (where @samp{[bar]} is
the subscript to array @samp{@@foo})?  If @samp{@@foo} doesn't otherwise
exist, then it's obviously a character class.  If @samp{@@foo} exists,
perl takes a good guess about @samp{[bar]}, and is almost always right.
If it does guess wrong, or if you're just plain paranoid, you can force
the correct interpretation with curly brackets as above.@refill

@cindex @samp{<<}, here-is syntax
@cindex here-is syntax, @samp{<<}
A line-oriented form of quoting is based on the shell here-is syntax.
Following a @samp{<<} you specify a string to terminate the quoted
material, and all lines following the current line down to the
terminating string are the value of the item.  The terminating string
may be either an identifier (a word), or some quoted text.  If quoted,
the type of quotes you use determines the treatment of the text, just as
in regular quoting.  An unquoted identifier works like double quotes.
There must be no space between the @samp{<<} and the identifier.  (If
you put a space it will be treated as a null identifier, which is valid,
and matches the first blank line---see Merry Christmas example below.)
The terminating string must appear by itself (unquoted and with no
surrounding whitespace) on the terminating line.@refill

@example
        print <<EOF;            # same as above
The price is $Price.
EOF

        print <<"EOF";          # same as above
The price is $Price.
EOF

        print << x 10;          # null identifier is delimiter
Merry Christmas!

        print <<`EOC`;          # execute commands
echo hi there
echo lo there
EOC

        print <<foo, <<bar;     # you can stack them
I said foo.
foo
I said bar.
bar
@end example

Array literals are denoted by separating individual values by commas, and
enclosing the list in parentheses:

@cindex Array literals
@cindex Literals, array
@example
(LIST)
@end example

In a context not requiring an array value, the value of the array literal
is the value of the final element, as in the C comma operator.
For example,

@example
@@foo = ('cc', '-E', $bar);
@end example

@noindent
assigns the entire array value to array @var{foo}, but

@example
$foo = ('cc', '-E', $bar);
@end example

@noindent
assigns the value of variable @var{bar} to variable @var{foo}.  Note
that the value of an actual array in a scalar context is the length of
the array; the following assigns to @samp{$foo} the value 3:@refill

@example
@@foo = ('cc', '-E', $bar);
$foo = @@foo;               # $foo gets 3
@end example

@noindent
You may have an optional comma before the closing parenthesis of an
array literal, so that you can say:@refill

@example
@@foo = (
    1,
    2,
    3,
);
@end example

When a LIST is evaluated, each element of the list is evaluated in
an array context, and the resulting array value is interpolated into LIST
just as if each individual element were a member of LIST.  Thus arrays
lose their identity in a LIST---the list

@example
(@@foo,@@bar,&SomeSub)
@end example

@noindent
contains all the elements of @samp{@@foo} followed by all the elements
of @samp{@@bar}, followed by all the elements returned by the subroutine
named @samp{SomeSub}.@refill

@noindent
A list value may also be subscripted like a normal array.  Examples:

@example
$time = (stat($file))[8];       # stat returns array value
$digit = ('a','b','c','d','e','f')[$digit-10];
return (pop(@@foo),pop(@@foo))[0];
@end example

@noindent
Array lists may be assigned to @emph{if and only if} each element of the
list is an lvalue:

@example
($a, $b, $c) = (1, 2, 3);

($map@{'red'@}, $map@{'blue'@}, $map@{'green'@}) = (0x00f, 0x0f0, 0xf00);
@end example

@noindent
The final element may be an array or an associative array:

@example
($a, $b, @@rest) = split;
local($a, $b, %rest) = @@_;
@end example

@noindent
You can actually put an array anywhere in the list, but the first array
in the list will soak up all the values, and anything after it will get
a null value.  This may be useful in a @code{local()}.@refill

@cindex Associative array literals
@cindex Literals, associative array
@noindent
An associative array literal contains pairs of values to be interpreted
as a key and a value:

@example
# same as map assignment above
%map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
@end example

@noindent
Array assignment in a scalar context returns the number of elements
produced by the expression on the right side of the assignment:@refill

@example
$x = (($foo,$bar) = (3,2,1));   # set $x to 3, not 2
@end example

There are several other pseudo-literals that you should know about.  If
a string is enclosed by backticks (grave accents), it first undergoes
variable substitution just like a double quoted string.  It is then
interpreted as a command, and the output of that command is the value of
the pseudo-literal, like in a shell.  In a scalar context, a single
string consisting of all the output is returned.  In an array context,
an array of values is returned, one for each line of output.  (You can
set @samp{$/} to use a different line terminator.)  The command is
executed each time the pseudo-literal is evaluated.  The status value of
the command is returned in @samp{$?} (@xref{Predefined Names}, for the
interpretation of @samp{$?}).  Unlike in @code{csh}, no translation is
done on the return data---newlines remain newlines.  Unlike in any of
the shells, single quotes do not hide variable names in the command from
interpretation.  To pass a @samp{$} through to the shell you need to
hide it with a backslash.@refill

Evaluating a filehandle in angle brackets yields the next line from that
file (newline included, so it's never false until EOF, at which time the
undefined value is returned).  Ordinarily you must assign that value to
a variable, but there is one situation where an automatic assignment
happens.  If (and only if) the input symbol is the only thing inside the
conditional of a @code{while} loop, the value is automatically assigned
to the variable @samp{$_}.  (This may seem like an odd thing to you, but
you'll use the construct in almost every @emph{perl} script you write.)
Anyway, the following lines are equivalent to each other:@refill

@example
while ($_ = <STDIN>) @{ print; @}
while (<STDIN>) @{ print; @}
for (;<STDIN>;) @{ print; @}
print while $_ = <STDIN>;
print while <STDIN>;
@end example

The filehandles @samp{STDIN}, @samp{STDOUT} and @samp{STDERR} are
predefined.  (The filehandles @samp{stdin}, @samp{stdout} and
@samp{stderr} will also work except in packages, where they would be
interpreted as local identifiers rather than global.)  Additional
filehandles may be created with the @code{open} function.@refill

If a @samp{<FILEHANDLE>} is used in a context that is looking for an
array, an array consisting of all the input lines is returned, one line
per array element.  It's easy to make a LARGE data space this way, so use
with care.@refill

The null filehandle @samp{<>} is special and can be used to emulate the
behavior of @code{sed} and @code{awk}.  Input from @samp{<>} comes either
from standard input, or from each file listed on the command line.  Here's
how it works: the first time @samp{<>} is evaluated, the @samp{ARGV} array
is checked, and if it is null, @samp{$ARGV[0]} is set to @samp{-}, which
when opened gives you standard input.  The @samp{ARGV} array is then
processed as a list of filenames.  The loop@refill

@example
while (<>) @{
        @dots{}                 # code for each line
@}
@end example

@noindent
is equivalent to

@example
unshift(@@ARGV, '-') if $#ARGV < $[;
while ($ARGV = shift) @{
        open(ARGV, $ARGV);
        while (<ARGV>) @{
                @dots{}         # code for each line
        @}
@}
@end example

@noindent
except that it isn't as cumbersome to say.  It really does shift array
@samp{ARGV} and put the current filename into variable @samp{ARGV}.  It
also uses filehandle @samp{ARGV} internally.  You can modify
@samp{@@ARGV} before the first @samp{<>} as long as you leave the first
filename at the beginning of the array.  Line numbers (@samp{$.})
continue as if the input was one big happy file.  (But see example under
@code{eof} for how to reset line numbers on each file.)@refill
@comment @@@@ ADD XREF @@@@

If you want to set @samp{@@ARGV} to your own list of files, go right
ahead.  If you want to pass switches into your script, you can put a loop
on the front like this:@refill

@example
while ($_ = $ARGV[0], /^-/) @{
        shift;
    last if /^--$/;
        /^-D(.*)/ && ($debug = $1);
        /^-v/ && $verbose++;
        @dots{}         # other switches
@}
while (<>) @{
        @dots{}         # code for each line
@}
@end example

The @samp{<>} symbol will return FALSE only once.  If you call it again
after this it will assume you are processing another @samp{@@ARGV} list,
and if you haven't set @samp{@@ARGV}, will input from @samp{STDIN}.@refill

If the string inside the angle brackets is a reference to a scalar
variable (e.g. @samp{<$foo>}), then that variable contains the name of the
filehandle to input from.@refill

@cindex Globbing, filename
@cindex Filename globbing
If the string inside angle brackets is not a filehandle, it is interpreted
as a filename pattern to be globbed, and either an array of filenames or
the next filename in the list is returned, depending on context.  One
level of @samp{$} interpretation is done first, but you can't say
@samp{<$foo>} because that's an indirect filehandle as explained in the
previous paragraph.  You could insert curly brackets to force
interpretation as a filename glob: @samp{<$@{foo@}>}.  Example:@refill

@example
while (<*.c>) @{
        chmod 0644, $_;
@}
@end example

@noindent
is equivalent to

@example
open(foo, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|");
while (<foo>) @{
        chop;
        chmod 0644, $_;
@}
@end example

In fact, it's currently implemented that way.  (Which means it will not
work on filenames with spaces in them unless you have @file{/bin/csh} on
your machine.)  Of course, the shortest way to do the above is:@refill

@example
chmod 0644, <*.c>;
@end example

@node Syntax, Compound Statements, Data Types, Top
@comment  node-name,  next,  previous,  up
@chapter Syntax
@cindex Syntax

A @emph{perl} script consists of a sequence of declarations and
commands.  The only things that need to be declared in @emph{perl} are
report formats and subroutines.  See the sections below for more
information on those declarations.  All uninitialized user-created
objects are assumed to start with a null or 0 value until they are
defined by some explicit operation such as assignment.  The sequence of
commands is executed just once, unlike in @code{sed} and @code{awk}
scripts, where the sequence of commands is executed for each input line.
While this means that you must explicitly loop over the lines of your
input file (or files), it also means you have much more control over
which files and which lines you look at.  (Actually, I'm lying---it is
possible to do an implicit loop with either the @samp{-n} or @samp{-p}
switch.)@refill

A declaration can be put anywhere a command can, but has no effect on
the execution of the primary sequence of commands---declarations all
take effect at compile time.  Typically all the declarations are put at
the beginning or the end of the script.@refill

@emph{Perl} is, for the most part, a free-form language.  (The only
exception to this is format declarations, for fairly obvious reasons.)
Comments are indicated by the @samp{#} character, and extend to the end
of the line.  If you attempt to use @samp{/* */} C comments, it will be
interpreted either as division or pattern matching, depending on the
context.  So don't do that.@refill

@node Compound Statements, Simple Statements, Syntax, Top
@comment  node-name,  next,  previous,  up
@chapter Compound Statements
@cindex Compound Statements
@cindex Statements, Compound

In @emph{perl}, a sequence of commands may be treated as one command by
enclosing it in curly brackets.  We will call this a BLOCK.@refill

@noindent
The following compound commands may be used to control flow:

@cindex @code{if} statement
@cindex @code{else} statement
@cindex @code{elsif} statement
@cindex @code{while} statement
@cindex @code{continue} statement
@cindex @code{for} statement
@cindex @code{foreach} statement
@cindex @code{unless} statement
@findex if
@findex else
@findex elsif
@findex while
@findex continue
@findex for
@findex foreach
@findex unless
@example
if (EXPR) BLOCK
if (EXPR) BLOCK else BLOCK
if (EXPR) BLOCK elsif (EXPR) BLOCK @dots{} else BLOCK
LABEL while (EXPR) BLOCK
LABEL while (EXPR) BLOCK continue BLOCK
LABEL for (EXPR; EXPR; EXPR) BLOCK
LABEL foreach VAR (ARRAY) BLOCK
LABEL BLOCK continue BLOCK
@end example

Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
not statements.  This means that the curly brackets are
@strong{required}---no dangling statements allowed.  If you want to
write conditionals without curly brackets there are several other ways
to do it.  The following all do the same thing:@refill

@example
if (!open(foo)) @{ die "Can't open $foo: $!"; @}
die "Can't open $foo: $!" unless open(foo);
open(foo) || die "Can't open $foo: $!"; # foo or bust!
open(foo) ? 'hi mom' : die "Can't open $foo: $!";
                        # a bit exotic, that last one
@end example

@noindent
The @code{if} statement is straightforward.  Since BLOCKs are always
bounded by curly brackets, there is never any ambiguity about which
@code{if} an @code{else} goes with.  If you use @code{unless} in place
of @code{if}, the sense of the test is reversed.@refill

The @code{while} statement executes the block as long as the expression
is true (does not evaluate to the null string or 0).  The LABEL is
optional, and if present, consists of an identifier followed by a colon.
The LABEL identifies the loop for the loop control statements
@code{next}, @code{last}, and @code{redo} (see below).  If there is a
@code{continue} BLOCK, it is always executed just before the conditional
is about to be evaluated again, similarly to the third part of a
@code{for} loop in C.  Thus it can be used to increment a loop variable,
even when the loop has been continued via the @code{next} statement
(similar to the C @code{continue} statement).@refill

If the word @code{while} is replaced by the word @code{until}, the sense
of the test is reversed, but the conditional is still tested before the
first iteration.@refill

In either the @code{if} or the @code{while} statement, you may replace
@samp{(EXPR)} with a BLOCK, and the conditional is true if the value of
the last command in that block is true.@refill

@noindent
The @code{for} loop works exactly like the corresponding @code{while}
loop:@refill

@example
for ($i = 1; $i < 10; $i++) @{
        @dots{}
@}
@end example

@noindent
is the same as

@example
$i = 1;
while ($i < 10) @{
        @dots{}
@} continue @{
        $i++;
@}
@end example

The @code{foreach} loop iterates over a normal array value and sets the
variable @var{VAR} to be each element of the array in turn.  The
variable is implicitly local to the loop, and regains its former value
upon exiting the loop.  The @code{foreach} keyword is actually identical
to the @code{for} keyword, so you can use @code{foreach} for readability
or @code{for} for brevity.  If @var{VAR} is omitted, @samp{$_} is set to
each value.  If @var{ARRAY} is an actual array (as opposed to an
expression returning an array value), you can modify each element of the
array by modifying @var{VAR} inside the loop.  Examples:@refill

@example
for (@@ary) @{ s/foo/bar/; @}

foreach $elem (@@elements) @{
        $elem *= 2;
@}

for ((10,9,8,7,6,5,4,3,2,1,'BOOM')) @{
        print $_, "\n"; sleep(1);
@}

for (1..15) @{ print "Merry Christmas\n"; @}

foreach $item (split(/:[\\\n:]*/, $ENV@{'TERMCAP'@})) @{
        print "Item: $item\n";
@}
@end example

The BLOCK by itself (labeled or not) is equivalent to a loop that
executes once.  Thus you can use any of the loop control statements in
it to leave or restart the block.  The @code{continue} block is
optional.  This construct is particularly nice for doing case
structures.@refill

@example
foo: @{
        if (/^abc/) @{ $abc = 1; last foo; @};
        if (/^def/) @{ $def = 1; last foo; @};
        if (/^xyz/) @{ $xyz = 1; last foo; @};
        $nothing = 1;
@}
@end example

@cindex Switch statement
@cindex Case statement
There is no official switch statement in perl, because there are already
several ways to write the equivalent.  In addition to the above, you
could write:@refill

@example
foo: @{
        $abc = 1, last foo  if /^abc/;
        $def = 1, last foo  if /^def/;
        $xyz = 1, last foo  if /^xyz/;
        $nothing = 1;
@}
@end example

@noindent
or

@example
foo: @{
        /^abc/ && do @{ $abc = 1; last foo; @}
        /^def/ && do @{ $def = 1; last foo; @}
        /^xyz/ && do @{ $xyz = 1; last foo; @}
        $nothing = 1;
@}
@end example

@noindent
or

@example
foo: @{
        /^abc/ && ($abc = 1, last foo);
        /^def/ && ($def = 1, last foo);
        /^xyz/ && ($xyz = 1, last foo);
        $nothing = 1;
@}
@end example

@noindent
or even

@example
if (/^abc/)
        @{ $abc = 1; @}
elsif (/^def/)
        @{ $def = 1; @}
elsif (/^xyz/)
        @{ $xyz = 1; @}
else
        @{$nothing = 1;@}
@end example

As it happens, these are all optimized internally to a switch structure,
so perl jumps directly to the desired statement, and you needn't worry
about perl executing a lot of unnecessary statements when you have a
string of 50 @code{elsif}s, as long as you are testing the same simple
scalar variable using @samp{==}, @samp{eq}, or pattern matching as
above.  (If you're curious as to whether the optimizer has done this for
a particular case statement, you can use the @samp{-D1024} switch to
list the syntax tree before execution.)@refill

@node Simple Statements, Expressions, Compound Statements, Top
@comment  node-name,  next,  previous,  up
@chapter Simple Statements
@cindex Simple Statements
@cindex Statements, Simple

The only kind of simple statement is an expression evaluated for its
side effects.  Every expression (simple statement) must be terminated
with a semicolon.  Note that this is like C, but unlike Pascal (and
@code{awk}).@refill

Any simple statement may optionally be followed by a single modifier,
just before the terminating semicolon.  The possible modifiers are:

@cindex Statement modifiers
@cindex Modifiers, statement
@cindex @code{if} modifier
@cindex @code{unless} modifier
@cindex @code{while} modifier
@findex if
@findex unless
@findex while
@example
if EXPR
unless EXPR
while EXPR
until EXPR
@end example

The @code{if} and @code{unless} modifiers have the expected semantics.
The @code{while} and @code{until} modifiers also have the expected
semantics (conditional evaluated first), except when applied to a
do-BLOCK or a do-SUBROUTINE command, in which case the block executes
once before the conditional is evaluated.  This is so that you can write
loops like:@refill

@example
do @{
        $_ = <STDIN>;
        @dots{}
@} until $_ eq ".\n";
@end example

@noindent
(See the @code{do} operator below.  Note also that the loop control
commands described later will @strong{NOT} work in this construct, since
modifiers don't take loop labels.  Sorry.)@refill

@node Expressions, Commands, Simple Statements, Top
@comment  node-name,  next,  previous,  up
@chapter Expressions
@cindex Expressions

@c ADD index entries for the various operators @@@@
Since @emph{perl} expressions work almost exactly like C expressions,
only the differences will be mentioned here.@refill

@noindent
Here's what @emph{perl} has that C doesn't:

@table @asis
@item **
The exponentiation operator.

@item **=
The exponentiation assignment operator.

@item ()
The null list, used to initialize an array to null.

@item .
Concatenation of two strings.

@item .=
The concatenation assignment operator.

@item eq
String equality (@samp{==} is numeric equality).  For a mnemonic just
think of @samp{eq} as a string.  (If you are used to the @code{awk}
behavior of using @samp{==} for either string or numeric equality based
on the current form of the comparands, beware!  You must be explicit
here.)@refill

@item ne
String inequality (@samp{!=} is numeric inequality).

@item lt
String less than.

@item gt
String greater than.

@item le
String less than or equal.

@item ge
String greater than or equal.

@item cmp
String comparison, returning -1, 0, or 1.

@item <=>
Numeric comparison, returning -1, 0, or 1.

@item =~
Certain operations search or modify the string @samp{$_} by default.
This operator makes that kind of operation work on some other string.
The right argument is a search pattern, substitution, or translation.
The left argument is what is supposed to be searched, substituted, or
translated instead of the default @samp{$_}.  The return value indicates
the success of the operation.  (If the right argument is an expression
other than a search pattern, substitution, or translation, it is
interpreted as a search pattern at run time.  This is less efficient
than an explicit search, since the pattern must be compiled every time
the expression is evaluated.)  The precedence of this operator is lower
than unary minus and autoincrement/decrement, but higher than everything
else.@refill

@item !~
Just like @samp{=~} except the return value is negated.

@item x
The repetition operator.  Returns a string consisting of the left
operand repeated the number of times specified by the right operand.  In
an array context, if the left operand is a list in parens, it repeats
the list.@refill

@example
print '-' x 80;         # print row of dashes
print '-' x80;          # illegal, x80 is identifier

print "\t" x ($tab/8), ' ' x ($tab%8);  # tab over

@@ones = (1) x 80;      # an array of 80 1's
@@ones = (5) x @@ones;  # set all elements to 5
@end example

@item x=
The repetition assignment operator.  Only works on scalars.

@item ..
The range operator, which is really two different operators depending on
the context.  In an array context, returns an array of values counting
(by ones) from the left value to the right value.  This is useful for
writing @code{for (1..10)} loops and for doing slice operations on
arrays.@refill

In a scalar context, @samp{..} returns a boolean value.  The operator is
bistable, like a flip-flop.  Each @samp{..} operator maintains its own
boolean state.  It is false as long as its left operand is false.  Once
the left operand is true, the range operator stays true until the right
operand is true, @strong{AFTER} which the range operator becomes false
again.  (It doesn't become false till the next time the range operator
is evaluated.  It can become false on the same evaluation it became
true, but it still returns true once.)  The right operand is not
evaluated while the operator is in the ``false'' state, and the left
operand is not evaluated while the operator is in the ``true'' state.
The scalar @samp{..} operator is primarily intended for doing line
number ranges after the fashion of @code{sed} or @code{awk}.  The
precedence is a little lower than @samp{||} and @samp{&&}.  The value
returned is either the null string for false, or a sequence number
(beginning with 1) for true.  The sequence number is reset for each
range encountered.  The final sequence number in a range has the string
@samp{E0} appended to it, which doesn't affect its numeric value, but
gives you something to search for if you want to exclude the endpoint.
You can exclude the beginning point by waiting for the sequence number
to be greater than 1.  If either operand of scalar @samp{..} is static,
that operand is implicitly compared to the @samp{$.} variable, the
current line number.  Examples:@refill

@noindent
As a scalar operator:
@example
if (101 .. 200) @{ print; @}        # print 2nd hundred lines

next line if (1 .. /^$/);   # skip header lines

s/^/> / if (/^$/ .. eof()); # quote body
@end example

@noindent
As an array operator:
@example
for (101 .. 200) @{ print; @} # print $_ 100 times

@@foo = @@foo[$[ .. $#foo]; # an expensive no-op
@@foo = @@foo[$#foo-4 .. $#foo];    # slice last 5 items
@end example

@item -x
@cindex File test operators
@cindex Operators, file test
A file test.  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 @samp{$_}, except for
@samp{-t}, which tests @samp{STDIN}.  It returns 1 for true and @'@' for
false, or the undefined value if the file doesn't exist.  Precedence is
higher than logical and relational operators, but lower than arithmetic
operators.  The operator may be any of:@refill

@example
-r      File is readable by effective uid.
-w      File is writable by effective uid.
-x      File is executable by effective uid.
-o      File is owned by effective uid.
-R      File is readable by real uid.
-W      File is writable by real uid.
-X      File is executable by real uid.
-O      File is owned by real uid.
-e      File exists.
-z      File has zero size.
-s      File has non-zero size (returns size).
-f      File is a plain file.
-d      File is a directory.
-l      File is a symbolic link.
-p      File is a named pipe (FIFO).
-S      File is a socket.
-b      File is a block special file.
-c      File is a character special file.
-u      File has setuid bit set.
-g      File has setgid bit set.
-k      File has sticky bit set.
-t      Filehandle is opened to a tty.
-T      File is a text file.
-B      File is a binary file (opposite of -T).
-M      Age of file in days when script started.
-A      Same for access time.
-C      Same for inode change time.
@end example

The interpretation of the file permission operators @samp{-r},
@samp{-R}, @samp{-w}, @samp{-W}, @samp{-x} and @samp{-X} is 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.  Also
note that, for the superuser, @samp{-r}, @samp{-R}, @samp{-w} and
@samp{-W} always return 1, and @samp{-x} and @samp{-X} return 1 if any
execute bit is set in the mode.  Scripts run by the superuser may thus
need to do a @code{stat()} in order to determine the actual mode of the
file, or temporarily set the uid to something else.@refill

Example:

@example
while (<>) @{
        chop;
        next unless -f $_;      # ignore specials
        @dots{}
@}
@end example

Note that @samp{-s/a/b/} does not do a negated substitution.  Saying
@samp{-exp($foo)} still works as expected, however---only single letters
following a minus are interpreted as file tests.@refill

The @samp{-T} and @samp{-B} switches work as follows.  The first block
or so of the file is examined for odd characters such as strange control
codes or metacharacters.  If too many odd characters (>10%) are found,
it's a @samp{-B} file, otherwise it's a @samp{-T} file.  Also, any file
containing null in the first block is considered a binary file.  If
@samp{-T} or @samp{-B} is used on a filehandle, the current stdio buffer
is examined rather than the first block.  Both @samp{-T} and @samp{-B}
return TRUE on a null file, or a file at EOF when testing a filehandle.@refill

If any of the file tests (or either @code{stat} operator) are given the
special filehandle consisting of a solitary underline @samp{_}, then the
stat structure of the previous file test (or @code{stat} operator) is
used, saving a system call.  (This doesn't work with @samp{-t}, and you
need to remember that @code{lstat} and @samp{-l} will leave values in
the stat structure for the symbolic link, not the real file.)  Example:@refill

@example
print "Can do.\n" if -r $a || -w _ || -x _;

stat($filename);
print "Readable\n" if -r _;
print "Writable\n" if -w _;
print "Executable\n" if -x _;
print "Setuid\n" if -u _;
print "Setgid\n" if -g _;
print "Sticky\n" if -k _;
print "Text\n" if -T _;
print "Binary\n" if -B _;
@end example
@end table

@noindent
Here is what C has that @emph{perl} doesn't:

@table @asis
@item unary &
Address-of operator.

@item unary *
Dereference-address operator.

@item (TYPE)
Type casting operator.
@end table

Like C, @emph{perl} does a certain amount of expression evaluation at
compile time, whenever it determines that all of the arguments to an
operator are static and have no side effects.  In particular, string
concatenation happens at compile time between literals that don't do
variable substitution.  Backslash interpretation also happens at compile
time.  You can say:@refill

@example
'Now is the time for all' . "\n" .
'good men to come to.'
@end example

@noindent
and this all reduces to one string internally.

The autoincrement operator has a little extra built-in magic to it.  If
you increment a variable that is numeric, or that has ever been used in
a numeric context, you get a normal increment.  If, however, the
variable has only been used in string contexts since it was set, and has
a value that is not null and matches the pattern
@samp{/^[a-zA-Z]*[0-9]*$/}, the increment is done as a string,
preserving each character within its range, with carry:@refill

@example
print ++($foo = '99');  # prints @samp{100}
print ++($foo = 'a0');  # prints @samp{a1}
print ++($foo = 'Az');  # prints @samp{Ba}
print ++($foo = 'zz');  # prints @samp{aaa}
@end example

@noindent
The autodecrement is not magical.

The range operator (in an array context) makes use of the magical
autoincrement algorithm if the minimum and maximum are strings.  You can
say@refill

@example
@@alphabet = ('A' .. 'Z');
@end example

@noindent
to get all the letters of the alphabet, or

@example
$hexdigit = (0 .. 9, 'a' .. 'f')[$num & 15];
@end example

@noindent
to get a hexadecimal digit, or

@example
@@z2 = ('01' .. '31');  print @@z2[$mday];
@end example

@noindent
to get dates with leading zeros.  (If the final value specified is not
in the sequence that the magical increment would produce, the sequence
goes until the next value would be longer than the final value
specified.)@refill

The @samp{||} and @samp{&&} operators differ from C's in that, rather
than returning 0 or 1, they return the last value evaluated.  Thus, a
portable way to find out the home directory might be:@refill

@example
$home = $ENV@{'HOME'@} || $ENV@{'LOGDIR'@} ||
    (getpwuid($<))[7] || die "You're homeless!\en";
@end example

Along with the literals and variables mentioned earlier, the operations
in the following section can serve as terms in an expression.  Some of
these operations take a LIST as an argument.  Such a list can consist of
any combination of scalar arguments or array values; the array 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 array value.  Elements of the LIST should be
separated by commas.  If an operation is listed both with and without
parentheses around its arguments, it means you can either use it as a
unary operator or as a function call.  To use it as a function call, the
next token on the same line must be a left parenthesis.  (There may be
intervening white space.)  Such a function then has highest precedence,
as you would expect from a function.  If any token other than a left
parenthesis follows, then it is a unary operator, with a precedence
depending only on whether it is a LIST operator or not.  LIST operators
have lowest precedence.  All other unary operators have a precedence
greater than relational operators but less than arithmetic operators.
@xref{Precedence}, for more info.

@node     Commands, Precedence, Expressions, Top
@comment  node-name,  next,  previous,  up
@chapter Commands
@cindex Commands
@cindex List of Commands
@cindex Command Syntax

@c @@@@ this menu should probably be broken into subgroups @@@@
@c @@@@ taken out of menu 'cos makeinfo did not like it .. @@@@
@c @@@@ still formatted okay .. just gave warning @@@@
@menu
* Math Functions::                Various trigonometric and math functions.
* Structure Conversion::          How to convert binary structures.
* String Functions::              Functions to interact with strings.
* Array and List Functions::      Functions that manipulate arrays/lists.
* File Operations::               Functions that operate on files.
* Directory Reading Functions::   Functions for reading directories.  :-)
* Input/Output::                  Printing and reading data.
* Search and Replace Functions::  Pattern matching functions.
* System Interaction::            A mix of functions dealing with the system.
* Networking Functions::          Interprocess Communication Functions.
* System V IPC::                  System V IPC Functions.
* Time Functions::                Time related functions.
* DBM Functions::                 Functions for accessing @samp{dbm} files.
* Flow Control Functions::        Functions related to flow control.
* Perl Library Functions::        How to include perl libraries.
* Subroutine Functions::          Functions related to user-defined subs.
* Variable Functions::            Functions dealing with variables.
                                    (not already mentioned)
* Miscellaneous Functions::       A catch-all for all other functions.  ;-)
@end menu
@c @@@@ reword above 2 lines @@@@
@c @@@@ above 2 lines now refers to "Variable Functions" menu item @@@@
@c @@@@ see comment above menu @@@@

@node     Math Functions, Structure Conversion, , Commands
@comment  node-name,  next,  previous,  up
@section Math Functions
@cindex Trigonometric Functions
@cindex Math Functions

@table @asis
@item atan2(@var{Y},@var{X})
@cindex Trigonometric Functions
@cindex Math Functions
@findex atan2
Returns the arctangent of @var{Y}/@var{X} in the range
@ifinfo
-PI to PI.@refill
@end ifinfo
@tex
-$\pi$ to $\pi$.
@end tex

@item cos(@var{EXPR})
@itemx cos @var{EXPR}
@itemx cos
@c @@@@ above item not in orig man page pl28 @@@@
@cindex Trigonometric Functions, cosine
@cindex Cosine, trigonometric function
@cindex @code{cos} function
@findex cos
Returns the cosine of @var{EXPR} (expressed in radians).  If @var{EXPR}
is omitted takes cosine of @samp{$_}.@refill

@item exp(@var{EXPR})
@itemx exp @var{EXPR}
@itemx exp
@c @@@@ above not in orig man pg pl28 @@@@
@cindex Trigonometric functions, @code{exp} function
@cindex Trigonometric functions, e to the EXPR
@cindex @code{exp} trigonometric function
@cindex Math functions, @code{exp}
@cindex Math functions, e to the EXPR
@findex exp
Returns @samp{e} to the power of @var{EXPR}.  If @var{EXPR} is omitted,
gives @code{exp($_)}.@refill

@item hex(@var{EXPR})
@itemx hex @var{EXPR}
@itemx hex
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{hex} function
@cindex Number conversion, hex to decimal
@cindex Hexidecimal to decimal conversion
@findex hex
Returns the decimal value of @var{EXPR} interpreted as an hex string.
(To interpret strings that might start with @samp{0} or @samp{0x} see
@code{oct()}.)  If @var{EXPR} is omitted, uses @samp{$_}.@refill

@item int(@var{EXPR})
@itemx int @var{EXPR}
@itemx int
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{int} function
@cindex integer portion of EXPR, Returning
@cindex Returning integer portion of EXPR
@cindex Numeric, integer portion of EXPR
@findex int
Returns the integer portion of @var{EXPR}.  If @var{EXPR} is omitted,
uses @samp{$_}.@refill

@item log(@var{EXPR})
@itemx log @var{EXPR}
@itemx log
@c @@@@ above not in orig man pg pl28 @@@@
@cindex logarithm function (base e)
@cindex @code{log} function (base e)
@cindex Math functions, @code{log} function (base e)
@findex log
Returns logarithm (base @samp{e}) of @var{EXPR}.  If @var{EXPR} is
omitted, returns log of @samp{$_}.@refill

@item oct(@var{EXPR})
@itemx oct @var{EXPR}
@itemx oct
@c @@@@ above line not in orig man page pl28 @@@@
@cindex Number conversion, octal to decimal
@cindex Octal to decimal conversion
@findex oct
Returns the decimal value of @var{EXPR} interpreted as an octal string.
(If @var{EXPR} happens to start off with @samp{0x}, interprets it as a
hex string instead.)  The following will handle decimal, octal and hex
in the standard notation:@refill

@example
@cindex Example, @code{oct} function
@cindex @code{oct} function example
@cindex Example, octal to decimal example
@cindex octal to decimal conversion example
$val = oct($val) if $val =~ /^0/;
@end example

If @var{EXPR} is omitted, uses @samp{$_}.

@item sin(@var{EXPR})
@itemx sin @var{EXPR}
@itemx sin
@c @@@@ above line not in orig man page pl28 @@@@
@cindex sine function (same as @code{sin})
@cindex @code{sin} function
@cindex Math functions, @code{sin} function
@findex sin
Returns the sine of @var{EXPR} (expressed in radians).  If @var{EXPR} is
omitted, returns sine of @samp{$_}.@refill

@item sqrt(@var{EXPR})
@itemx sqrt @var{EXPR}
@itemx sqrt
@c @@@@ above line not in orig man page pl28 @@@@
@cindex @code{sqrt} function
@cindex Math functions, @code{sqrt} function
@cindex Math functions, square root
@cindex Square root function
@findex sqrt
Return the square root of @var{EXPR}.  If @var{EXPR} is omitted, returns
square root of @samp{$_}.@refill

@end table

@node     Structure Conversion, String Functions, Math Functions, Commands
@comment  node-name,  next,  previous,  up
@section Structure Conversion
@cindex Structure Conversion

@table @asis
@item pack(@var{TEMPLATE},@var{LIST})
@cindex @code{pack} function
@ifinfo
@cindex Converting values into binary structure
@end ifinfo
@tex
@cindex Converting values into binary struct
@end tex
@cindex Opposite of @code{unpack} function
@findex pack
Takes an array or list of values and packs it into a binary structure,
returning the string containing the structure.  The @var{TEMPLATE} is a
sequence of characters that give the order and type of values, as
follows:@refill

@ignore
Comments on f & d by gnb@@melba.bby.oz.au    22 Nov 89
@end ignore
@example
A       An ascii string, will be space padded.
a       An ascii string, will be null padded.
c       A signed char value.
C       An unsigned char value.
s       A signed short value.
S       An unsigned short value.
i       A signed integer value.
I       An unsigned integer value.
l       A signed long value.
L       An unsigned long value.
n       A short in @samp{network} order.
N       A long in @samp{network} order.
f       A single-precision float in the native format.
d       A double-precision float in the native format.
p       A pointer to a string.
x       A null byte.
X       Back up a byte.
@@       Null fill to absolute position.
u       A uuencoded string.
b       A bit string (ascending bit order, like vec()).
B       A bit string (descending bit order).
h       A hex string (low nybble first).
H       A hex string (high nybble first).
@end example

Each letter may optionally be followed by a number which gives a repeat
count.  With all types except @samp{a}, @samp{A}, @samp{b}, @samp{B},
@samp{h}, and @samp{H}, the pack function will gobble up that many
values from the @var{LIST}.  A @samp{*} for the repeat count means to
use however many items are left.  The @samp{a} and @samp{A} types gobble
just one value, but pack it as a string of length count, padding with
nulls or spaces as necessary.  (When unpacking, @samp{A} strips trailing
spaces and nulls, but @samp{a} does not.)  Likewise, the @samp{b} and
@samp{B} fields pack a string that many bits long.  The @samp{h} and
@samp{H} fields pack a string that many nybbles long.  Real numbers
(floats and doubles) are in the native machine format only; due to the
multiplicity of floating formats around, and the lack of a standard
``network'' representation, no facility for interchange has been made.
This means that packed floating point data written on one machine may
not be readable on another - even if both use IEEE floating point
arithmetic (as the endian-ness of the memory representation is not part
of the IEEE spec).  Note that perl uses doubles internally for all
numeric calculation, and converting from double to float back to double
will lose precision (i.e. @samp{unpack("f", pack("f", $foo))} will not
in general equal @samp{$foo}).@refill

Examples:@refill

@cindex Examples of @code{pack} function
@cindex @code{pack} function examples
@example
$foo = pack("cccc",65,66,67,68);
# foo eq "ABCD"
$foo = pack("c4",65,66,67,68);
# same thing

$foo = pack("ccxxcc",65,66,67,68);
# foo eq "AB\0\0CD"

$foo = pack("s2",1,2);
# "\1\0\2\0" on little-endian
# "\0\1\0\2" on big-endian

$foo = pack("a4","abcd","x","y","z");
# "abcd"

$foo = pack("aaaa","abcd","x","y","z");
# "axyz"

$foo = pack("a14","abcdefg");
# "abcdefg\0\0\0\0\0\0\0"

$foo = pack("i9pl", gmtime);
# a real struct tm (on my system anyway)

sub bintodec @{
    unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
@}
@end example

The same template may generally also be used in the @code{unpack}
function.@refill

@item unpack(@var{TEMPLATE},@var{EXPR})
@cindex @code{unpack} function
@cindex Opposite of @code{pack} function
@cindex Unpacking binary data
@findex unpack
@code{unpack} does the reverse of @code{pack}: it takes a string
representing a structure and expands it out into an array value,
returning the array value.  (In a scalar context, it merely returns the
first value produced.)  The @var{TEMPLATE} has the same format as in the
@code{pack} function.  Here's a subroutine that does substring:@refill

@cindex Example, @code{unpack} function
@cindex @code{unpack} function example
@cindex Example, emulating @code{substr} with @code{unpack}
@cindex Emulating @code{substr} with @code{unpack} example
@cindex Example, using @code{unpack} to emulate @code{substr}
@cindex Using @code{unpack} to emulate @code{substr} example
@example
sub substr @{
        local($what,$where,$howmuch) = @@_;
        unpack("x$where a$howmuch", $what);
@}
@end example

and then there's

@cindex Example, emulating @code{ord} with @code{unpack}
@cindex Emulating @code{ord} with @code{unpack}
@cindex Example, using @code{unpack} to emulate @code{ord}
@cindex Using @code{unpack} to emulate @code{ord}
@example
sub ord @{ unpack("c",$_[0]); @}
@end example

In addition, you may prefix a field with a @samp{%<number>} to indicate
that you want a <number>-bit checksum of the items instead of the items
themselves.  Default is a 16-bit checksum.  For example, the following
computes the same number as the System V sum program:@refill

@cindex Example of checksum in @code{unpack}
@cindex System V @code{sum} program implementation
@c @@@@ CHG above index entry -- add others ? @@@@
@example
while (<>) @{
    $checksum += unpack("%16C*", $_);
@}
$checksum %= 65536;
@end example

@end table

@node     String Functions, Array and List Functions, Structure Conversion, Commands
@comment  node-name,  next,  previous,  up
@section String Functions
@cindex String Functions

@table @asis
@item chop(@var{LIST})
@itemx chop(@var{VARIABLE})
@itemx chop @var{VARIABLE}
@itemx chop
@cindex Chopping
@cindex @code{chop} function
@cindex Deletion (via @code{chop})
@findex chop
Chops off the last character of a string and returns the character
chopped.  It's used primarily to remove the newline from the end of an
input record, but is much more efficient than @samp{s/\n//} because it
neither scans nor copies the string.  If @var{VARIABLE} is omitted,
chops @samp{$_}.  Example:@refill

@cindex Example, @code{chop} function
@cindex @code{chop} example
@example
while (<>) @{
        chop;   # avoid \n on last field
        @@array = split(/:/);
        @dots{}
@}
@end example

You can actually chop anything that's an lvalue, including an
assignment:@refill

@example
chop($cwd = `pwd`);
chop($answer = <STDIN>);
@end example

If you chop a list, each element is chopped.  Only the value of the last
chop is returned.@refill

@item crypt(@var{PLAINTEXT},@var{SALT})
@cindex @code{crypt} function
@cindex Passwords, @code{crypt} function
@findex crypt
Encrypts a string exactly like the @code{crypt()} function in the C library.
Useful for checking the password file for lousy passwords.  Only the
guys wearing white hats should do this.@refill

@item index(@var{STR},@var{SUBSTR},@var{POSITION})
@itemx index(@var{STR},@var{SUBSTR})
@cindex @code{index} function
@cindex strchr function (really @code{index})
@cindex Searching, first occurrence
@cindex String functions, @code{index} function
@cindex String functions, finding first string
@cindex Finding first occurrence of substring
@findex index
Returns the position of the first occurrence of @var{SUBSTR} in
@var{STR} at or after @var{POSITION}.  If @var{POSITION} is omitted,
starts searching from the beginning of the string.  The return value is
based at 0, or whatever you've set the @samp{$[} variable to.  If the
substring is not found, returns one less than the base, ordinarily
-1.@refill

@item length(@var{EXPR})
@itemx length @var{EXPR}
@itemx length
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{length} function
@cindex Strings, Finding length of a string
@cindex Finding length of a string
@findex length
Returns the length in characters of the value of @var{EXPR}.  If
@var{EXPR} is omitted, returns length of @samp{$_}.@refill

@item rindex(@var{STR},@var{SUBSTR},@var{POSITION})
@itemx rindex(@var{STR},@var{SUBSTR})
@cindex @code{rindex} function
@cindex rstrchr function (really @code{rindex})
@cindex Searching, last occurrence
@cindex Finding last occurrence of a substring
@cindex String functions, @code{rindex} function
@cindex String functions, finding last string
@findex rindex
Works just like @code{index} except that it returns the position of the
@var{LAST} occurrence of @var{SUBSTR} in @var{STR}.  If @var{POSITION}
is specified, returns the last occurrence at or before that
position.@refill

@item substr(@var{EXPR},@var{OFFSET},@var{LEN})
@itemx substr(@var{EXPR},@var{OFFSET})
@cindex @code{substr} function
@cindex Extracting a substring
@findex substr
Extracts a substring out of @var{EXPR} and returns it.  First character
is at offset 0, or whatever you've set @samp{$[} to.  If @var{OFFSET} is
negative, starts that far from the end of the string.  If @var{LEN} is
omitted, returns everything to the end of the string.  You can use the
@code{substr()} function as an lvalue, in which case @var{EXPR} must be
an lvalue.  If you assign something shorter than @var{LEN}, the string
will shrink, and if you assign something longer than @var{LEN}, the
string will grow to accommodate it.  To keep the string the same length
you may need to pad or chop your value using @code{sprintf()}.@refill
@end table

@node     Array and List Functions, File Operations, String Functions, Commands
@comment  node-name,  next,  previous,  up
@section Array and List Functions
@cindex Array and List Functions
@cindex Array Functions
@cindex List Functions

@table @asis
@item delete @var{$ASSOC@{KEY@}}
@cindex @code{delete} function
@cindex Associative Arrays, @code{delete} function
@findex delete
Deletes the specified value from the specified associative array.
Returns the deleted value, or the undefined value if nothing was
deleted.  Deleting from @var{$ENV@{@}} modifies the environment.
Deleting from an array bound to a dbm file deletes the entry from the
dbm file.@refill

The following deletes all the values of an associative array:

@cindex Example, @code{delete} function
@cindex @code{delete} function example
@cindex Deleting values of associative arrays
@ifinfo
@cindex Example, deleting values of associative arrays
@end ifinfo
@example
foreach $key (keys %ARRAY) @{
        delete $ARRAY@{$key@};
@}
@end example

(But it would be faster to use the @code{reset} command.  Saying
@samp{undef %ARRAY} is faster yet.)@refill

@item each(@var{ASSOC_ARRAY})
@itemx each @var{ASSOC_ARRAY}
@cindex Associative arrays, key and value
@cindex @code{each} function, Associative arrays
@cindex Associative arrays, @code{each} function
@findex each
Returns a 2 element array consisting of the key and value for the next
value of an associative array, so that you can iterate over it.  Entries
are returned in an apparently random order.  When the array is entirely
read, a null array is returned (which when assigned produces a FALSE (0)
value).  The next call to @code{each()} after that will start iterating
again.  The iterator can be reset only by reading all the elements from
the array.  You must not modify the array while iterating over it.
There is a single iterator for each associative array, shared by all
@code{each()}, @code{keys()} and @code{values()} function calls in the
program.  The following prints out your environment like the
@code{printenv} program, only in a different order:@refill

@example
@cindex Example of @code{each} function
@cindex @code{each} function example
@cindex Printing ENVironment example
@cindex Example of printing ENVironment
@cindex Example similar to @samp{printenv} program
@cindex @samp{printenv} program example
while (($key,$value) = each %ENV) @{
        print "$key=$value\n";
@}
@end example

See also @code{keys()} and @code{values()}.

@item grep(@var{EXPR},@var{LIST})
@cindex @code{grep} function
@c @@@@ add MORE CINDEX descriptions @@@@
@findex grep
Evaluates @var{EXPR} for each element of @var{LIST} (locally setting
@samp{$_} to each element) and returns the array value consisting of
those elements for which the expression evaluated to true.  In a scalar
context, returns the number of times the expression was true.@refill

@example
@cindex Example, @code{grep} function
@cindex @code{grep} function example
@@foo = grep(!/^#/, @@bar);    # weed out comments
@end example

Note that, since @samp{$_} is a reference into the array value, it can
be used to modify the elements of the array.  While this is useful and
supported, it can cause bizarre results if the @var{LIST} is not a named
array.@refill

@item join(@var{EXPR},@var{LIST})
@itemx join(@var{EXPR},@var{ARRAY})
@cindex @code{join} function
@cindex Joining strings with a field separtor
@cindex Opposite of @code{split} function, @code{join}
@findex join
Joins the separate strings of @var{LIST} or @var{ARRAY} into a single
string with fields separated by the value of @var{EXPR}, and returns the
string.  Example:@refill

@example
@cindex Example of @code{join} function
@cindex @code{join} function example
$_ = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
@end example

See @code{split} function.
@c @@@@ CHG above to xref @@@@

@item keys(@var{ASSOC_ARRAY})
@itemx keys @var{ASSOC_ARRAY}
@cindex Associative arrays, @code{keys} function
@cindex Associative arrays, finding keys
@cindex @code{keys} function, Associative arrays
@findex keys
Returns a normal array consisting of all the keys of the named
associative array.  The keys are returned in an apparently random order,
but it is the same order as either the @code{values()} or @code{each()}
function produces (given that the associative array has not been
modified).  Here is yet another way to print your environment:@refill

@example
@cindex Example of @code{keys} function
@cindex @code{keys} function example
@cindex Printing your environment example
@@keys = keys %ENV;
@@values = values %ENV;
while ($#keys >= 0) @{
        print pop(@@keys), '=', pop(@@values), "\n";
@}
@end example

or how about sorted by key:

@example
foreach $key (sort(keys %ENV)) @{
        print $key, '=', $ENV@{$key@}, "\n";
@}
@end example

@item pop(@var{ARRAY})
@itemx pop @var{ARRAY}
@cindex @code{pop} function
@cindex Arrays, popping the last value
@cindex Arrays, @code{pop} function
@findex pop
Pops and returns the last value of the array, shortening the array by 1.
Has the same effect as:@refill

@example
$tmp = $ARRAY[$#ARRAY--];
@end example

If there are no elements in the array, returns the undefined value.@refill

@item push(@var{ARRAY},@var{LIST})
@cindex @code{push} function
@cindex Arrays, pushing a value onto
@cindex Arrays, @code{push} function
@findex push
Treats @var{ARRAY} (@samp{@@} is optional) as a stack, and pushes the
values of @var{LIST} onto the end of @var{ARRAY}.  The length of
@var{ARRAY} increases by the length of @var{LIST}.  Has the same effect
as:@refill

@example
for $value (LIST) @{
        $ARRAY[++$#ARRAY] = $value;
@}
@end example

but is more efficient.

@item reverse(@var{LIST})
@itemx reverse @var{LIST}
@cindex @code{reverse} function
@cindex Arrays, @code{reverse} function
@cindex Lists, @code{reverse} function
@cindex Reversing an array
@cindex Reversing a list
@findex reverse
In an array context, returns an array value consisting of the elements
of @var{LIST} in the opposite order.  In a scalar context, returns a
string value consisting of the bytes of the first element of @var{LIST}
in the opposite order.@refill

@item shift(@var{ARRAY})
@itemx shift @var{ARRAY}
@itemx shift
@cindex @code{shift} function
@cindex Arrays, shifting first value off
@cindex Arrays, @code{shift} function
@cindex Returning first value of an array
@findex shift
Shifts the first value of the array off and returns it, shortening the
array by 1 and moving everything down.  If there are no elements in the
array, returns the undefined value.  If @var{ARRAY} is omitted, shifts
the @samp{@@ARGV} array in the main program, and the @samp{@@_} array in
subroutines.  (This is determined lexically.)  See also
@code{unshift()}, @code{push()} and @code{pop()}.  @code{shift()} and
@code{unshift()} do the same thing to the left end of an array that
@code{push()} and @code{pop()} do to the right end.@refill

@item sort(@var{SUBROUTINE} @var{LIST})
@itemx sort(@var{LIST})
@itemx sort @var{SUBROUTINE} @var{LIST}
@itemx sort @var{LIST}
@cindex @code{sort} function
@cindex Sorting a list
@cindex Sorting
@findex sort
Sorts the @var{LIST} and returns the sorted array value.  Nonexistent
values of arrays are stripped out.  If @var{SUBROUTINE} is omitted,
sorts in standard string comparison order.  If @var{SUBROUTINE} is
specified, gives the name of a subroutine that returns an integer less
than, equal to, or greater than 0, depending on how the elements of the
array are to be ordered.  In the interests of efficiency the normal
calling code for subroutines is bypassed, with the following effects:
the subroutine may not be a recursive subroutine, and the two elements
to be compared are passed into the subroutine not via @samp{@@_} but as
@samp{$a} and @samp{$b} (see example below).  They are passed by
reference so don't modify @samp{$a} and @samp{$b}.  @var{SUBROUTINE} may
be a scalar variable name, in which case the value provides the name of
the subroutine to use.  Examples:@refill

@ifinfo
@cindex Example, sorting using your own comparison routine
@cindex Sorting using your own comparison routine example
@end ifinfo
@cindex Example, @code{sort} function
@cindex @code{sort} function example
@cindex Sorting by age example
@cindex Example, sorting by age
@cindex Sorting using a user routine
@example
sub byage @{
    $age@{$a@} - $age@{$b@};    # presuming integers
@}
@@sortedclass = sort byage @@class;

@cindex Sorting examples
@cindex Examples, sorting
sub reverse @{ $a lt $b ? 1 : $a gt $b ? -1 : 0; @}
@@harry = ('dog','cat','x','Cain','Abel');
@@george = ('gone','chased','yz','Punished','Axed');
print sort @@harry;
        # prints AbelCaincatdogx
print sort reverse @@harry;
        # prints xdogcatCainAbel
print sort @@george, 'to', @@harry;
        # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
@end example

@item splice(@var{ARRAY},@var{OFFSET},@var{LENGTH},@var{LIST})
@itemx splice(@var{ARRAY},@var{OFFSET},@var{LENGTH})
@itemx splice(@var{ARRAY},@var{OFFSET})
@cindex @code{splice} function
@cindex Splicing part of a list
@cindex Extracting elements from a list
@cindex Removing elements from a list
@findex splice
Removes the elements designated by @var{OFFSET} and @var{LENGTH} from an
array, and replaces them with the elements of @var{LIST}, if any.
Returns the elements removed from the array.  The array grows or shrinks
as necessary.  If @var{LENGTH} is omitted, removes everything from
@var{OFFSET} onward.  The following equivalencies hold (assuming
@code{$[ == 0}):@refill

@example
@cindex Examples of @code{splice} function
@cindex @code{splice} function example
push(@@a,$x,$y)         splice(@@a,$#x+1,0,$x,$y)
pop(@@a)                splice(@@a,-1)
shift(@@a)              splice(@@a,0,1)
unshift(@@a,$x,$y)      splice(@@a,0,0,$x,$y)
$a[$x] = $y            splice(@@a,$x,1,$y);
@end example

Example, assuming array lengths are passed before arrays:

@example
@cindex Example, @code{splice} function
@cindex @code{splice} function example
@cindex Example, comparing two array values
@cindex Comparing two array values example
sub aeq @{      # compare two array values
        local(@@a) = splice(@@_,0,shift);
        local(@@b) = splice(@@_,0,shift);
        return 0 unless @@a == @@b;     # same len?
        while (@@a) @{
            return 0 if pop(@@a) ne pop(@@b);
        @}
        return 1;
@}
if (&aeq($len,@@foo[1..$len],0+@@bar,@@bar)) @{ @dots{} @}
@end example

@item split(/@var{PATTERN}/,@var{EXPR},@var{LIMIT})
@itemx split(/@var{PATTERN}/,@var{EXPR})
@itemx split(/@var{PATTERN}/)
@itemx split
@cindex @code{split} function
@cindex Splitting a string into an array
@findex split
Splits a string into an array of strings, and returns it.  (If not in an
array context, returns the number of fields found and splits into the
@samp{@@_} array.  (In an array context, you can force the split into
@samp{@@_} by using @samp{??} as the pattern delimiters, but it still
returns the array value.))  If @var{EXPR} is omitted, splits the
@samp{$_} string.  If @var{PATTERN} is also omitted, splits on
whitespace (@samp{/[\t\n]+/}).  Anything matching @var{PATTERN} is taken
to be a delimiter separating the fields.  (Note that the delimiter may
be longer than one character.)  If @var{LIMIT} is specified, splits into
no more than that many fields (though it may split into fewer).  If
@var{LIMIT} is unspecified, trailing null fields are stripped (which
potential users of @code{pop()} would do well to remember).  A pattern
matching the null string (not to be confused with a null pattern
@samp{//}, which is just one member of the set of patterns matching a
null string) will split the value of @var{EXPR} into separate characters
at each point it matches that way.  For example:@refill

@example
@cindex Example, @code{split} function
@cindex @code{split} function example
@cindex Example, @code{join} function
@cindex @code{join} function example
print join(':', split(/ */, 'hi there'));
@end example

produces the output @samp{h:i:t:h:e:r:e}.

The @var{LIMIT} parameter can be used to partially split a line

@example
@cindex Example, @code{split} function
@cindex @code{split} function example
@cindex Example, splitting passwd file entry
@cindex Splitting passwd file entry example
($login, $passwd, $remainder) = split(/:/, $_, 3);
@end example

(When assigning to a list, if @var{LIMIT} is omitted, perl supplies a
@var{LIMIT} one larger than the number of variables in the list, to
avoid unnecessary work.  For the list above @var{LIMIT} would have been
4 by default.  In time critical applications it behooves you not to
split into more fields than you really need.)@refill

If the @var{PATTERN} contains parentheses, additional array elements are
created from each matching substring in the delimiter.@refill

@example
split(/([,-])/,"1-10,20");
@end example

produces the array value

@example
(1,'-',10,',',20)
@end example

The pattern /@var{PATTERN}/ may be replaced with an expression to
specify patterns that vary at runtime.  (To do runtime compilation only
once, use @samp{/$variable/o}.)  As a special case, specifying a space
(' ') will split on white space just as split with no arguments does,
but leading white space does @emph{NOT} produce a null first field.
Thus, split(' ') can be used to emulate @code{awk}'s default behavior,
whereas @samp{split(/ /)} will give you as many null initial fields as
there are leading spaces.@refill

Example:

@example
@cindex Example, splitting passwd file entry
@cindex Splitting passwd file entry example
open(passwd, '/etc/passwd');
while (<passwd>) @{
        ($login, $passwd, $uid, $gid, $gcos, $home, $shell)
                = split(/:/);
        @dots{}
@}
@end example

(Note that @samp{$shell} above will still have a newline on it.  See
@code{chop()}.)  See also @code{join}.@refill

@item unshift(@var{ARRAY},@var{LIST})
@cindex @code{unshift} function
@cindex Prepending to the front of an array
@cindex Arrays, prepending
@cindex Arrays, @code{unshift} function
@findex unshift
Does the opposite of a @code{shift}.  Or the opposite of a @code{push},
depending on how you look at it.  Prepends list to the front of the
array, and returns the number of elements in the new array.@refill

@example
@cindex Example, unshift function
@cindex unshift function example
unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;
@end example

@item values(@var{ASSOC_ARRAY})
@itemx values @var{ASSOC_ARRAY}
@cindex @code{values} function
@cindex Associative Arrays, @code{values} function
@cindex Associative Arrays, values of
@cindex Values of associative arrays
@findex values
Returns a normal array consisting of all the values of the named
associative array.  The values are returned in an apparently random
order, but it is the same order as either the @code{keys()} or
@code{each()} function would produce on the same array.  See also
@code{keys()} and @code{each()}.@refill
@end table

@node     File Operations, Directory Reading Functions, Array and List Functions, Commands
@comment  node-name,  next,  previous,  up
@section File Operations
@cindex File Operations

@table @asis
@item chmod(@var{LIST})
@itemx chmod @var{LIST}
Changes the permissions of a list of files.  The first element of the
list must be the numerical mode.  Returns the number of files
successfully changed.@refill
@cindex File Access
@cindex File Modes
@cindex File Permissions
@cindex Changing File Permissions
@cindex Changing File Modes
@cindex Access, Changing File
@cindex Permissions, Changing File
@cindex Modes, Changing File
@findex chmod

@example
@cindex Example, @code{chmod} function
@cindex @code{chmod} example
$cnt = chmod 0755, 'foo', 'bar';
chmod 0755, @@executables;
@end example

@item chown(@var{LIST})
@itemx chown @var{LIST}
@cindex Ownership of Files
@cindex File Ownership
@cindex Changing File Ownership
@cindex File Ownership, Changing
@cindex @code{chown} function
@cindex @code{chgrp} function (part of @code{chown})
@findex chgrp (part of chown)
@findex chown
Changes the owner (and group) of a list of files.  The first two
elements of the list must be the @strong{NUMERICAL} uid and gid, in that
order.  Returns the number of files successfully changed.@refill

@example
$cnt = chown $uid, $gid, 'foo', 'bar';
chown $uid, $gid, @@filenames;
@end example

Here's an example of looking up non-numeric uids:

@example
@cindex Looking up non-numeric uids example
@cindex Example, non-numeric uids
@cindex Example, @code{chown} function
@cindex @code{chown} example
print "User: ";
$user = <STDIN>;
chop($user);
print "Files: "
$pattern = <STDIN>;
chop($pattern);
open(pass, '/etc/passwd') || die "Can't open passwd: $!\n";
while (<pass>) @{
        ($login,$pass,$uid,$gid) = split(/:/);
        $uid@{$login@} = $uid;
        $gid@{$login@} = $gid;
@}
@@ary = <$@{pattern@}>; # get filenames
if ($uid@{$user@} eq @'@') @{
        die "$user not in passwd file";
@}
else @{
        chown $uid@{$user@}, $gid@{$user@}, @@ary;
@}
@end example

@item fcntl(@var{FILEHANDLE},@var{FUNCTION},@var{SCALAR})
@cindex @code{fcntl} function
@findex fcntl
Implements the @samp{fcntl(2)} function.  You'll probably have to
say:@refill

@example
require "fcntl.ph";   # probably /usr/local/lib/perl/fcntl.ph
@end example

@c @@@@ orig problem in perl man pg pl27 -- chg makelib to h2ph @@@@
@c @@@@ fcntl.h --> fcntl.ph             -- ditto @@@@
first to get the correct function definitions.  If @file{fcntl.ph}
doesn't exist or doesn't have the correct definitions you'll have to
roll your own, based on your C header files such as
@file{<sys/fcntl.h>}.  (There is a perl script called @samp{h2ph} that
comes with the perl kit which may help you in this.)  Argument
processing and value return works just like @code{ioctl} below.  Note
that @code{fcntl} will produce a fatal error if used on a machine that
doesn't implement @samp{fcntl(2)}.@refill

@item fileno(@var{FILEHANDLE})
@itemx fileno @var{FILEHANDLE}
@cindex @code{fileno} function
@cindex File descriptor
@cindex Filehandle's file descriptor
@cindex File number
@findex fileno
Returns the file descriptor for a filehandle.  Useful for constructing
bitmaps for @code{select()}.  If @var{FILEHANDLE} is an expression, the
value is taken as the name of the filehandle.@refill

@item flock(@var{FILEHANDLE},@var{OPERATION})
@cindex @code{flock} function
@cindex File locking
@findex flock
Calls @samp{flock(2)} on @var{FILEHANDLE}.  See manual page for
@samp{flock(2)} for definition of OPERATION.  Returns true for success,
false on failure.  Will produce a fatal error if used on a machine that
doesn't implement @samp{flock(2)}.  Here's a mailbox appender for BSD
systems.@refill

@example
@cindex Example of @code{flock} function
@cindex Example of a BSD mailbox appender
@cindex BSD mailbox appender example
@cindex Mailbox (BSD) appender example
$LOCK_SH = 1;
$LOCK_EX = 2;
$LOCK_NB = 4;
$LOCK_UN = 8;

sub lock @{
    flock(MBOX,$LOCK_EX);
    # and, in case someone appended
    # while we were waiting...
    seek(MBOX, 0, 2);
@}

sub unlock @{
    flock(MBOX,$LOCK_UN);
@}

open(MBOX, ">>/usr/spool/mail/$ENV@{'USER'@}")
        || die "Can't open mailbox: $!";

do lock();
print MBOX $msg,"\n\n";
do unlock();
@end example

@item link(@var{OLDFILE},@var{NEWFILE})
@cindex @code{link} function
@cindex Creating a link to a file
@findex link
Creates a new filename linked to the old filename.  Returns 1 for
success, 0 otherwise.@refill

@item lstat(@var{FILEHANDLE})
@itemx lstat @var{FILEHANDLE}
@itemx lstat(@var{EXPR})
@itemx lstat @var{SCALARVARIABLE}
@cindex @code{lstat} function
@cindex Symbolic Links, stat-ing
@cindex Links, stat-ing symbolic
@cindex Stat-ing symbolic links
@findex lstat
Does the same thing as the @code{stat()} function, but stats a symbolic
link instead of the file the symbolic link points to.  If symbolic links
are unimplemented on your system, a normal stat is done.@refill

@item readlink(@var{EXPR})
@itemx readlink @var{EXPR}
@itemx readlink
@c @@@@ above line not in orig man page pl28 @@@@
@cindex @code{readlink} function
@cindex Symbolic links, reading
@cindex Links, reading symbolic
@findex readlink
Returns the value of a symbolic link, if symbolic links are implemented.
If not, gives a fatal error.  If there is some system error, returns the
undefined value and sets @samp{$!} (errno).  If @var{EXPR} is omitted,
uses @samp{$_}.@refill

@item rename(@var{OLDNAME},@var{NEWNAME})
@cindex @code{rename} function
@cindex @code{rename} system call
@cindex Renaming a file
@findex rename
Changes the name of a file.  Returns 1 for success, 0 otherwise.  Will
not work across filesystem boundaries.@refill

@item stat(@var{FILEHANDLE})
@itemx stat @var{FILEHANDLE}
@itemx stat(@var{EXPR})
@itemx stat @var{SCALARVARIABLE}
@cindex @code{stat} function
@cindex Statistics for a file, finding
@cindex File statistics
@findex stat
Returns a 13-element array giving the statistics for a file, either the
file opened via @var{FILEHANDLE}, or named by @var{EXPR}.  Typically
used as follows:@refill

@example
@cindex Example, @code{stat} function
@cindex @code{stat} function example
($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
   $atime,$mtime,$ctime,$blksize,$blocks)
       = stat($filename);
@end example

@cindex Underscore with @code{stat} function
@cindex Special case of underscore with @code{stat}
If @code{stat} is passed the special filehandle consisting of an
underline (@samp{_}), no stat is done, but the current contents of the
stat structure from the last stat or filetest are returned.
Example:@refill

@example
@cindex Example, @code{stat} function and underscore
@cindex @code{stat} function and underscore example
if (-x $file && (($d) = stat(_)) && $d < 0) @{
        print "$file is executable NFS file\n";
@}
@end example

@item symlink(@var{OLDFILE},@var{NEWFILE})
@cindex @code{symlink} function
@cindex Creating symbolic links
@cindex Symbolic links, Creating
@cindex Links, Creating symbolic
@findex symlink
Creates a new filename symbolically linked to the old filename.  Returns
1 for success, 0 otherwise.  On systems that don't support symbolic
links, produces a fatal error at run time.  To check for that, use
eval:@refill

@example
@cindex Example of @code{symlink} function
@cindex @code{symlink} function example
@cindex Checking if @code{symlink} function exists
@cindex Checking if function exists example
@cindex Example, checking if @code{symlink} exists
@cindex Example, checking if function exists
$symlink_exists = (eval 'symlink("","");', $@@ eq @'@');
@end example

@item truncate(@var{FILEHANDLE},@var{LENGTH})
@item truncate(@var{EXPR},@var{LENGTH})
Truncates the file opened on @var{FILEHANDLE}, or named by @var{EXPR},
to the specified length.  Produces a fatal error if @code{truncate}
isn't implemented on your system.@refill

@item unlink(@var{LIST})
@itemx unlink @var{LIST}
@itemx unlink
@c @@@@ above line not in orig man page pl28 @@@@
@c @@@@ orig man pg did not mention about unlink w/o args pl28 @@@@
@cindex @code{unlink} function
@cindex Deleting a file(s)
@cindex Unlinking a file(s)
@findex unlink
Deletes a list of files.  If @var{EXPR} is not specified, deletes file
specified by @samp{$_}.  Returns the number of files successfully
deleted.@refill

@example
@cindex Examples of @code{unlink} function
@cindex @code{unlink} function examples
$cnt = unlink 'a', 'b', 'c';
unlink @@goners;
unlink <*.bak>;
@end example

Note: unlink will not delete directories unless you are superuser and
the @samp{-U} flag is supplied to @emph{perl}.  Even if these conditions
are met, be warned that unlinking a directory can inflict damage on your
filesystem.  Use @code{rmdir} instead.@refill

@item utime(@var{LIST})
@itemx utime @var{LIST}
@cindex @code{utime} function
@cindex Changing access times of a file(s)
@cindex Changing modification times of a file(s)
@cindex Files, changing access times
@cindex Files, changing modification times
@findex utime
Changes the access and modification times on each file of a list of
files.  The first two elements of the list must be the NUMERICAL access
and modification times, in that order.  Returns the number of files
successfully changed.  The inode modification time of each file is set
to the current time.  Example of a ``touch'' command:@refill

@example
@cindex Example of a touch command
@cindex touch command example
#!/usr/bin/perl
$now = time;
utime $now, $now, @@ARGV;
@end example
@end table

@node     Directory Reading Functions, Input/Output, File Operations, Commands
@comment  node-name,  next,  previous,  up
@section Directory Reading Functions
@cindex Directory Reading Functions
@cindex Directory Functions
@cindex Directory Operations

@table @asis
@item chdir(@var{EXPR})
@itemx chdir @var{EXPR}
@itemx chdir
@c @@@@ above item not in orig man pg pl28 @@@@
@cindex @code{chdir} function
@cindex Directory functions, @code{chdir}
@cindex Changing Directories
@cindex cwd (Change Working Directory)
@cindex Change Working Directory (cwd)
@findex chdir
Changes the working directory to @var{EXPR}, if possible.  If @var{EXPR}
is omitted, changes to home directory.  Returns 1 upon success, 0
otherwise.  See example under @code{die}.@refill

@item closedir(@var{DIRHANDLE})
@itemx closedir @var{DIRHANDLE}
@cindex @code{closedir} function
@cindex Closing a directory
@cindex Directory, closing a
@findex closedir
Closes a directory opened by @code{opendir()}.

@item mkdir(@var{FILENAME},@var{MODE})
@cindex @code{mkdir} function
@cindex Directory functions, @code{mkdir}
@cindex Making directories
@findex mkdir
Creates the directory specified by @var{FILENAME}, with permissions
specified by @var{MODE} (as modified by @code{umask}).  If it succeeds
it returns 1, otherwise it returns 0 and sets @samp{$!} (errno).@refill

@item opendir(@var{DIRHANDLE},@var{EXPR})
@cindex @code{opendir} function
@cindex Directory functions, @code{opendir}
@cindex Opening a directory for processing
@findex opendir
Opens a directory named @var{EXPR} for processing by @code{readdir()},
@code{telldir()}, @code{seekdir()}, @code{rewinddir()} and
@code{closedir()}.  Returns true if successful.  @var{DIRHANDLE}s have
their own namespace separate from @var{FILEHANDLE}s.@refill

@item readdir(@var{DIRHANDLE})
@itemx readdir @var{DIRHANDLE}
@cindex @code{readdir} function
@cindex Directory functions, @code{readdir}
@cindex Directory functions, next directory
@findex readdir
Returns the next directory entry for a directory opened by
@code{opendir()}.  If used in an array context, returns all the rest of
the entries in the directory.  If there are no more entries, returns an
undefined value in a scalar context or a null list in an array
context.@refill

@item rewinddir(@var{DIRHANDLE})
@itemx rewinddir @var{DIRHANDLE}
@cindex @code{rewinddir} function
@cindex Directory functions, @code{rewinddir}
@cindex Resetting list of dirs for @code{readdir}
@findex rewinddir
Sets the current position to the beginning of the directory for the
@code{readdir()} routine on @var{DIRHANDLE}.@refill

@item rmdir(@var{FILENAME})
@itemx rmdir @var{FILENAME}
@itemx rmdir
@c @@@@ above line not in orig man page pl28 @@@@
@cindex @code{rmdir} function
@cindex Directory functions, @code{rmdir}
@cindex Directory functions, removing a dir
@cindex Removing a directory
@findex rmdir
Deletes the directory specified by @var{FILENAME} if it is empty.  If it
succeeds it returns 1, otherwise it returns 0 and sets @samp{$!}
(errno).  If @var{FILENAME} is omitted, uses @samp{$_}.@refill

@item seekdir(@var{DIRHANDLE},@var{POS})
@cindex @code{seekdir} function
@cindex Directory functions, @code{seekdir}
@ifinfo
@cindex Directory functions, positioning pointer
@end ifinfo
@tex
@cindex Directory functions, positioning
@end tex
@findex seekdir
Sets the current position for the @code{readdir()} routine on
@var{DIRHANDLE}.  @var{POS} must be a value returned by
@code{telldir()}.  Has the same caveats about possible directory
compaction as the corresponding system library routine.@refill

@item telldir(@var{DIRHANDLE})
@itemx telldir @var{DIRHANDLE}
@cindex @code{telldir} function
@cindex Current position of directory
@comment above ???@@@@???
@cindex Directory functions, @code{telldir}
@findex telldir
Returns the current position of the @code{readdir()} routines on
@var{DIRHANDLE}.  Value may be given to @code{seekdir()} to access a
particular location in a directory.  Has the same caveats about possible
directory compaction as the corresponding system library routine.@refill
@end table

@node     Input/Output, Search and Replace Functions, Directory Reading Functions, Commands
@comment  node-name,  next,  previous,  up
@section Input/Output
@cindex Input/Output
@cindex I/O
@cindex Input/Output Operations
@cindex Input/Output Functions

@table @asis
@item binmode(@var{FILEHANDLE})
@itemx binmode @var{FILEHANDLE}
@cindex @code{binmode} function
@cindex Binary Mode
@cindex Text Mode
@findex binmode
Arranges for the file to be read in @strong{binary} mode in operating
systems that distinguish between binary and text files.  Files that are
not read in binary mode have CR LF sequences translated to LF on input
and LF translated to CR LF on output.  @code{binmode} has no effect
under Unix.  If @var{FILEHANDLE} is an expression, the value is taken as
the name of the filehandle.@refill

@item close(@var{FILEHANDLE})
@itemx close @var{FILEHANDLE}
@cindex @code{close} function
@cindex Closing a filehandle
@cindex Closing a file
@cindex Closing a pipe
@cindex File, closing a
@cindex Filehandle, closing a
@cindex Pipe, closing
@findex close
Closes the file or pipe associated with the file handle.  You don't have
to close @var{FILEHANDLE} if you are immediately going to do another
open on it, since open will close it for you.  (See @code{open}.)
However, an explicit close on an input file resets the line counter
(@samp{$.}), while the implicit close done by @code{open} does not.
Also, closing a pipe will wait for the process executing on the pipe to
complete, in case you want to look at the output of the pipe afterwards.
Closing a pipe explicitly also puts the status value of the command into
@samp{$?}.  Example:@refill

@example
@cindex Example, @code{close} function
@cindex @code{close} function example
@cindex Example, closing a filehandle
@cindex Closing a filehandle example
open(OUTPUT, '|sort >foo');     # pipe to sort
@dots{}         # print stuff to output
close OUTPUT;           # wait for sort to finish
open(INPUT, 'foo');     # get sort's results
@end example

@var{FILEHANDLE} may be an expression whose value gives the real
filehandle name.@refill

@item eof(@var{FILEHANDLE})
@itemx eof()
@itemx eof
@cindex @code{eof} function
@cindex End Of File (EOF)
@cindex EOF (End Of File)
@cindex Filehandle, end of file
@cindex Filehandle, EOF
@findex eof
Returns 1 if the next read on @var{FILEHANDLE} will return end of file,
or if @var{FILEHANDLE} is not open.  @var{FILEHANDLE} may be an
expression whose value gives the real filehandle name.  (Note that this
function actually reads a character and the @code{ungetc}'s it, so it is
not very useful in an interactive context.)  An @code{eof} without an
argument returns the eof status for the last file read.  Empty
parentheses @samp{()} may be used to indicate the pseudo file formed of
the files listed on the command line, i.e. @samp{eof()} is reasonable to
use inside a @samp{while (<>)} loop to detect the end of only the last
file.  Use @samp{eof(ARGV)} or @code{eof} without the parentheses to
test EACH file in a @samp{while (<>)} loop.  Examples:@refill

@example
@cindex Example of @code{eof} function
@cindex @code{eof} function example
# insert dashes just before last line of last file
while (<>) @{
        if (eof()) @{
                print "--------------\n";
        @}
        print;
@}

# reset line numbering on each input file
while (<>) @{
        print "$.\t$_";
        if (eof) @{     # Not eof().
                close(ARGV);
        @}
@}
@end example

@item getc(@var{FILEHANDLE})
@itemx getc @var{FILEHANDLE}
@itemx getc
@cindex @code{getc} function
@cindex Reading a character
@cindex Inputting a character
@cindex Keyboard input, character
@cindex Character input
@findex getc
Returns the next character from the input file attached to
@var{FILEHANDLE}, or a null string at EOF.  If @var{FILEHANDLE} is
omitted, reads from STDIN.@refill

@item open(@var{FILEHANDLE},@var{EXPR})
@itemx open(@var{FILEHANDLE})
@itemx open @var{FILEHANDLE}
@cindex @code{open} function
@cindex Opening a file
@findex open
Opens the file whose filename is given by @var{EXPR}, and associates it
with @var{FILEHANDLE}.  If @var{FILEHANDLE} is an expression, its value is
used as the name of the real filehandle wanted.  If @var{EXPR} is omitted,
the scalar variable of the same name as the @var{FILEHANDLE} contains the
filename.  If the filename begins with @samp{<} or nothing, the file is
opened for input.  If the filename begins with @samp{>}, the file is opened
for output.  If the filename begins with @samp{>>}, the file is opened for
appending.  (You can put a @samp{+} in front of the @samp{>} or @samp{<} to
indicate that you want both read and write access to the file.)  If the
filename begins with @samp{|}, the filename is interpreted as a command to
which output is to be piped, and if the filename ends with a @samp{|}, the
filename is interpreted as command which pipes input to us.  (You may not
have a command that pipes both in and out.)  Opening @samp{-} opens
@samp{STDIN} and opening @samp{>-} opens @samp{STDOUT}.  @code{open}
returns non-zero upon success, the undefined value otherwise.  If the open
involved a pipe, the return value happens to be the pid of the subprocess.
Examples:@refill

@example
@cindex Examples of @code{open} function
@cindex @code{open} function examples
$article = 100;
open article || die "Can't find article $article: $!\n";
while (<article>) @{@dots{}

open(LOG, '>>/usr/spool/news/twitlog');
                                # (log is reserved)

open(article, "caesar <$article |");
                                # decrypt article

open(extract, "|sort >/tmp/Tmp$$");
                                # $$ is our process#

# process argument list of files along with any includes

foreach $file (@@ARGV) @{
        do process($file, 'fh00');      # no pun intended
@}

sub process @{
        local($filename, $input) = @@_;
        $input++;               # this is a string increment
        unless (open($input, $filename)) @{
                print STDERR "Can't open $filename: $!\n";
                return;
        @}
        while (<$input>) @{     # note the use of indirection
                if (/^#include "(.*)"/) @{
                        do process($1, $input);
                        next;
                @}
                @dots{}         # whatever
        @}
@}
@end example

You may also, in the Bourne shell tradition, specify an @var{EXPR}
beginning with @samp{>&}, in which case the rest of the string is
interpreted as the name of a filehandle (or file descriptor, if numeric)
which is to be duped and opened.  You may use @samp{&} after @samp{>},
@samp{>>}, @samp{<}, @samp{+>}, @samp{+>>} and @samp{+<}.  The mode you
specify should match the mode of the original filehandle.  Here is a
script that saves, redirects, and restores @samp{STDOUT} and
@samp{STDERR}:@refill

@ifinfo
@cindex Example, saving, redirecting, and restoring STDOUT/STDERR
@cindex Saving, redirecting, and restoring STDOUT/STDERR example
@end ifinfo
@cindex Example, dup-ing STDOUT/STDERR
@cindex dup-ing STDOUT/STDERR example
@example
#!/usr/bin/perl
open(SAVEOUT, ">&STDOUT");
open(SAVEERR, ">&STDERR");

open(STDOUT, ">foo.out") || die "Can't redirect stdout";
open(STDERR, ">&STDOUT") || die "Can't dup stdout";

select(STDERR); $| = 1;         # make unbuffered
select(STDOUT); $| = 1;         # make unbuffered

print STDOUT "stdout 1\n";      # this works for
print STDERR "stderr 1\n";      # subprocesses too

close(STDOUT);
close(STDERR);

open(STDOUT, ">&SAVEOUT");
open(STDERR, ">&SAVEERR");

print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
@end example

If you open a pipe on the command @samp{-}, i.e. either @samp{|-} or
@samp{-|}, then there is an implicit fork done, and the return value of
open is the pid of the child within the parent process, and 0 within the
child process.  (Use @samp{defined($pid)} to determine if the
@code{open} was successful.)  The filehandle behaves normally for the
parent, but i/o to that filehandle is piped from/to the
@samp{STDOUT}/@samp{STDIN} of the child process.  In the child process
the filehandle isn't opened---i/o happens from/to the new @samp{STDOUT}
or @samp{STDIN}.  Typically this is used like the normal piped
@code{open} when you want to exercise more control over just how the
pipe command gets executed, such as when you are running setuid, and
don't want to have to scan shell commands for metacharacters.  The
following pairs are equivalent:@refill

@example
@cindex Examples of @code{open} function
@cindex @code{open} function examples
open(FOO, "|tr '[a-z]' '[A-Z]'");
open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';

open(FOO, "cat -n '$file'|");
open(FOO, "-|") || exec 'cat', '-n', $file;
@end example

Explicitly closing any piped filehandle causes the parent process to
wait for the child to finish, and returns the status value in @samp{$?}.
Note: on any operation which may do a fork, unflushed buffers remain
unflushed in both processes, which means you may need to set @samp{$|}
to avoid duplicate output.@refill

The filename that is passed to open will have leading and trailing
whitespace deleted.  In order to open a file with arbitrary weird
characters in it, it's necessary to protect any leading and trailing
whitespace thusly:@refill

@ifinfo
@cindex Example, preserving white space in @code{open} function
@end ifinfo
@cindex Preserving white space in @code{open}
@example
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
@end example

@item pipe(@var{READHANDLE},@var{WRITEHANDLE})
@cindex @code{pipe} function
@cindex Opening a pair of connected pipes
@cindex @code{pipe} system call
@findex pipe
Opens a pair of connected pipes like the corresponding system call.
Note that if you set up a loop of piped processes, deadlock can occur
unless you are very careful.  In addition, note that perl's pipes use
stdio buffering, so you may need to set @samp{$|} to flush your
@var{WRITEHANDLE} after each command, depending on the application.
@*
[Requires version 3.0 patchlevel 9.]@refill

@item print(@var{FILEHANDLE} @var{LIST})
@itemx print(@var{LIST})
@itemx print @var{FILEHANDLE} @var{LIST}
@itemx print @var{LIST}
@itemx print
@cindex @code{print} function
@cindex Printing a string(s)
@findex print
Prints a string or a comma-separated list of strings.  Returns non-zero
if successful.  @var{FILEHANDLE} may be a scalar variable name, in which
case the variable contains the name of the filehandle, thus introducing
one level of indirection.  (NOTE: If @var{FILEHANDLE} is a variable and
the next token is a term, it may be misinterpreted as an operator unless
you interpose a @samp{+} or put parens around the arguments.)  If
@var{FILEHANDLE} is omitted, prints by default to standard output (or to
the last selected output channel---see @code{select()}).@refill
@comment @@@@ PUT XREF ABOVE "see select()" @@@@
If @var{LIST} is also omitted, prints @samp{$_} to @samp{STDOUT}.  To set
the default output channel to something other than @samp{STDOUT} use the
select operation.  Note that, because @code{print} takes a @var{LIST},
anything in the @var{LIST} is evaluated in an array context, and any
subroutine that you call will have one or more of its expressions evaluated
in an array context.  Also be careful not to follow the @code{print}
keyword with a left parenthesis unless you want the corresponding right
parenthesis to terminate the arguments to the @code{print}---interpose a
@samp{+} or put parens around all the arguments.@refill

@item printf(@var{FILEHANDLE} @var{LIST})
@itemx printf(@var{LIST})
@itemx printf @var{FILEHANDLE} @var{LIST}
@itemx printf @var{LIST}
@itemx printf
@c @@@@ above line not in orig man page pl28 @@@@
@cindex @code{printf} function
@cindex Printing a string with a format
@findex printf
Equivalent to a @samp{print @var{FILEHANDLE} sprintf(@var{LIST})}.
@comment @@@@ rewrite above possibly @@@@

@item read(@var{FILEHANDLE},@var{SCALAR},@var{LENGTH},@var{OFFSET})
@itemx read(@var{FILEHANDLE},@var{SCALAR},@var{LENGTH})
@cindex @code{read} function
@cindex Reading data from a file
@findex read
Attempts to read @var{LENGTH} bytes of data into variable @var{SCALAR}
from the specified @var{FILEHANDLE}.  Returns the number of bytes
actually read, or @code{undef} if there was an error.  @var{SCALAR}
will be grown or shrunk to the length actually read.  An @var{OFFSET}
may be specified to place the read data at some other place than the
beginning of the string.  This call is actually implemented in terms of
stdio's @code{fread} call.  To get a true @code{read} system call,
see @code{sysread}.@refill
@c @@@@ add xref for sysread above @@@@

@item select(@var{RBITS},@var{WBITS},@var{EBITS},@var{TIMEOUT})
@cindex @code{select} system call
@findex select(RBITS,WBITS,EBITS,TIMEOUT)
This calls the select system call with the bitmasks specified, which can
be constructed using @code{fileno()} and @code{vec()}, along these
lines:@refill

@ifinfo
@cindex Example, constructing bitmasks for @code{select} system call
@end ifinfo
@tex
@cindex Example, constructing bitmasks
@end tex
@example
@cindex Bitmasks and @code{select} system call
@cindex Example, bitmasks and @code{select}
@cindex Constructing bitmasks for @code{select}
$rin = $win = $ein = @'@';
vec($rin,fileno(STDIN),1) = 1;
vec($win,fileno(STDOUT),1) = 1;
$ein = $rin | $win;
@end example

If you want to select on many filehandles you might wish to write a
subroutine:@refill

@example
sub fhbits @{
    local(@@fhlist) = split(' ',$_[0]);
    local($bits);
    for (@@fhlist) @{
        vec($bits,fileno($_),1) = 1;
    @}
    $bits;
@}
$rin = &fhbits('STDIN TTY SOCK');
@end example

The usual idiom is:

@example
@cindex Example of @code{select} system call
@cindex @code{select} system call example
($nfound,$timeleft) =
   select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
@end example

or to block until something becomes ready:

@example
$nfound = select($rout=$rin, $wout=$win,
                        $eout=$ein, undef);
@end example

Any of the bitmasks can also be @code{undef}.  The timeout, if
specified, is in seconds, which may be fractional.  NOTE: not all
implementations are capable of returning the @samp{$timeleft}.  If not,
they always return @samp{$timeleft} equal to the supplied
@samp{$timeout}.@refill

@item seek(FILEHANDLE,POSITION,WHENCE)
@cindex @code{seek} function
@cindex Positioning the file pointer
@cindex fseek function of stdio (really @code{seek})
@findex seek
Randomly positions the file pointer for @var{FILEHANDLE}, just like the
@code{fseek()} call of stdio.  @var{FILEHANDLE} may be an expression
whose value gives the name of the filehandle.  Returns 1 upon success, 0
otherwise.@refill

@item select(@var{FILEHANDLE})
@itemx select
@cindex @code{select(FILEHANDLE)} function
@cindex Setting default FILEHANDLE for output
@findex select(FILEHANDLE)
Returns the currently selected filehandle.  Sets the current default
filehandle for output, if @var{FILEHANDLE} is supplied.  This has two
effects: first, a @code{write} or a @code{print} without a filehandle
will default to this @var{FILEHANDLE}.  Second, references to variables
related to output will refer to this output channel.  For example, if
you have to set the top of form format for more than one output channel,
you might do the following:@refill

@ifinfo
@cindex Example, @code{select(FILEHANDLE)} and top of form format
@end ifinfo
@example
@cindex Example, @code{select(FILEHANDLE)} function
@cindex @code{select(FILEHANDLE)} function example
@cindex Example, top of form format
@cindex Top of form format example
select(REPORT1);
$^ = 'report1_top';
select(REPORT2);
$^ = 'report2_top';
@end example

@var{FILEHANDLE} may be an expression whose value gives the name of the
actual filehandle.  Thus:@refill

@example
@cindex Example, @code{select(FILEHANDLE)} function
@cindex @code{select(FILEHANDLE)} function example
$oldfh = select(STDERR); $| = 1; select($oldfh);
@end example

@item tell(@var{FILEHANDLE})
@itemx tell @var{FILEHANDLE}
@itemx tell
@cindex @code{tell} function
@cindex Current file position, finding
@cindex Finding current file position
@findex tell
Returns the current file position for @var{FILEHANDLE}.
@var{FILEHANDLE} may be an expression whose value gives the name of the
actual filehandle.  If @var{FILEHANDLE} is omitted, assumes the file
last read.@refill

@item write(@var{FILEHANDLE})
@itemx write(@var{EXPR})
@itemx write
@cindex @code{write} function
@cindex Writing a formatted record
@cindex Printing a formatted record
@cindex Printing Reports
@cindex Reports, Printing
@findex write
@comment @@@@ ADD other INDEX entries @@@@
Writes a formatted record (possibly multi-line) to the specified file,
using the format associated with that file.  By default the format for a
file is the one having the same name is the filehandle, but the format
for the current output channel (see @code{select}) may be set explicitly
by assigning the name of the format to the @samp{$~} variable.@refill

Top of form processing is handled automatically: if there is
insufficient room on the current page for the formatted record, the page
is advanced by writing a form feed, a special top-of-page format is used
to format the new page header, and then the record is written.  By
default the top-of-page format is @code{top}, but it may be set to the
format of your choice by assigning the name to the @samp{$^} variable.
The number of lines remaining on the current page is in variable
@samp{$-}, which can be set to 0 to force a new page.@refill

If @var{FILEHANDLE} is unspecified, output goes to the current default
output channel, which starts out as @samp{STDOUT} but may be changed by
the @code{select} operator.  If the @var{FILEHANDLE} is an @var{EXPR},
then the expression is evaluated and the resulting string is used to
look up the name of the @var{FILEHANDLE} at run time.  @xref{Formats},
for more info.@refill

Note that @code{write} is NOT the opposite of @code{read}.
@end table

@node     Search and Replace Functions, System Interaction, Input/Output, Commands
@comment  node-name,  next,  previous,  up
@section Search and Replace Functions
@cindex Search and Replace Functions
@cindex Replace and Search Functions

@table @asis
@item m/@var{PATTERN}/io
@itemx /@var{PATTERN}/io
@cindex Match function
@cindex Matching, Pattern
@cindex Pattern Matching
@cindex Pattern matching function
@findex m/PATTERN/
@findex /PATTERN/
Searches a string for a pattern match, and returns true (1) or false
(@'@').  If no string is specified via the @samp{=~} or @samp{!~}
operator, the @samp{$_} string is searched.  (The string specified with
@samp{=~} need not be an lvalue---it may be the result of an expression
evaluation, but remember the @samp{=~} binds rather tightly.)
@xref{Regular Expressions}, for more info.@refill

If @samp{/} is the delimiter then the initial @samp{m} is optional.
With the @samp{m} you can use any pair of non-alphanumeric characters as
delimiters.  This is particularly useful for matching Unix path names
that contain @samp{/}.  If the final delimiter is followed by the
optional letter @samp{i}, the matching is done in a case-insensitive
manner.  @var{PATTERN} may contain references to scalar variables, which
will be interpolated (and the pattern recompiled) every time the pattern
search is evaluated.  (Note that @samp{$)} and @samp{$|} may not be
interpolated because they look like end-of-string tests.)  If you want
such a pattern to be compiled only once, add an @samp{o} after the
trailing delimiter.  This avoids expensive run-time recompilations, and
is useful when the value you are interpolating won't change over the
life of the script.  If the @var{PATTERN} evaluates to a null string,
the most recent successful regular expression is used instead.@refill

If used in a context that requires an array value, a pattern match returns
an array consisting of the subexpressions matched by the parentheses in
the pattern, i.e. @samp{($1, $2, $3@dots{})}.  It does @strong{NOT}
actually set @samp{$1}, @samp{$2}, etc. in this case, nor does it set
@samp{$+}, @samp{$`}, @samp{$&} or @samp{$'}.  If the match fails, a null
array is returned.  If the match succeeds, but there were no parentheses,
an array value of (1) is returned.@refill

Examples:
@example
@cindex Examples of match function
@cindex match function examples
@cindex Pattern matching examples
open(tty, '/dev/tty');
<tty> =~ /^y/i && do foo(); # do foo if desired

if (/Version: *([0-9.]*)/) @{ $version = $1; @}

next if m#^/usr/spool/uucp#;

@cindex Poor Man's Grep Example
@cindex Example, Poor Man's Grep
# poor man's grep
$arg = shift;
while (<>) @{
        print if /$arg/o;   # compile only once
@}

if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
@end example

This last example splits @samp{$foo} into the first two words and the
remainder of the line, and assigns those three fields to @samp{$F1},
@samp{$F2} and @samp{$Etc}.  The conditional is true if any variables
were assigned, i.e. if the pattern matched.@refill

@item ?@var{PATTERN}?
@findex ?PATTERN?
This is just like the @code{/pattern/} search, except that it matches only
once between calls to the @code{reset} operator.  This is a useful
optimization when you only want to see the first occurrence of something in
each file of a set of files, for instance.  Only @samp{??} patterns local
to the current package are reset.@refill

@item s/@var{PATTERN}/@var{REPLACEMENT}/gieo
@cindex @code{s/PATTERN/REPLACEMENT/} function
@cindex Substitute function
@cindex Replacing a pattern in a string
@findex s/PATTERN/REPLACEMENT/
@findex substitute function
Searches a string for a pattern, and if found, replaces that pattern
with the replacement text and returns the number of substitutions made.
Otherwise it returns false (0).  The @samp{g} is optional, and if
present, indicates that all occurrences of the pattern are to be
replaced.  The @samp{i} is also optional, and if present, indicates that
matching is to be done in a case-insensitive manner.  The @samp{e} is
likewise optional, and if present, indicates that the replacement string
is to be evaluated as an expression rather than just as a double-quoted
string.  Any non-alphanumeric delimiter may replace the slashes; if
single quotes are used, no interpretation is done on the replacement
string (the @samp{e} modifier overrides this, however); if backquotes
are used, the replacement string is a command to execute whose output
will be used as the actual replacement text.  If no string is specified
via the @samp{=~} or @samp{!~} operator, the @samp{$_} string is
searched and modified.  (The string specified with @samp{=~} must be a
scalar variable, an array element, or an assignment to one of those,
i.e. an lvalue.)  If the pattern contains a @samp{$} that looks like a
variable rather than an end-of-string test, the variable will be
interpolated into the pattern at run-time.  If you only want the pattern
compiled once the first time the variable is interpolated, add an
@samp{o} at the end.  If the @var{PATTERN} evaluates to a null string,
the most recent successful regular expression is used instead.
@xref{Regular Expressions}, for more info.  Examples:@refill

@example
@cindex Examples, substitute function
@cindex Substitute function examples
@cindex Examples, @code{s/PATTERN/REPLACEMENT/}
@cindex @code{s/PATTERN/REPLACEMENT/} examples
s/\bgreen\b/mauve/g;        # don't change wintergreen

$path =~ s|/usr/bin|/usr/local/bin|;

s/Login: $foo/Login: $bar/; # run-time pattern

($foo = $bar) =~ s/bar/foo/;

$_ = 'abc123xyz';
s/\d+/$&*2/e;               # yields @samp{abc246xyz}
s/\d+/sprintf("%5d",$&)/e;  # yields @samp{abc  246xyz}
s/\w/$& x 2/eg;             # yields @samp{aabbcc  224466xxyyzz}

s/([^ ]*) *([^ ]*)/$2 $1/;  # reverse 1st two fields
@end example

(Note the use of @samp{$} instead of @samp{\} in the last example.
@xref{Regular Expressions}.)@refill

@item study(@var{SCALAR})
@itemx study @var{SCALAR}
@itemx study
@cindex @code{study} function
@cindex Speeding up searches, using @code{study}
@findex study
Takes extra time to study @var{SCALAR} (@samp{$_} if unspecified) in
anticipation of doing many pattern matches on the string before it is
next modified.  This may or may not save time, depending on the nature
and number of patterns you are searching on, and on the distribution of
character frequencies in the string to be searched---you probably want
to compare runtimes with and without it to see which runs faster.  Those
loops which scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most.  You may have only
one study active at a time---if you study a different scalar the first
is ``unstudied''.  (The way study works is this: a linked list of every
character in the string to be searched is made, so we know, for example,
where all the @samp{k} characters are.  From each search string, the
rarest character is selected, based on some static frequency tables
constructed from some C programs and English text.  Only those places
that contain this ``rarest'' character are examined.)@refill

For example, here is a loop which inserts index producing entries before
any line containing a certain pattern:@refill

@example
@cindex Example of @code{study} function
@cindex @code{study} function example
while (<>) @{
        study;
        print ".IX foo\n" if /\bfoo\b/;
        print ".IX bar\n" if /\bbar\b/;
        print ".IX blurfl\n" if /\bblurfl\b/;
        @dots{}
        print;
@}
@end example

In searching for @samp{/\bfoo\b/}, only those locations in @samp{$_}
that contain @samp{f} will be looked at, because @samp{f} is rarer than
@samp{o}.  In general, this is a big win except in pathological cases.
The only question is whether it saves you more time than it took to
build the linked list in the first place.@refill

Note that if you have to look for strings that you don't know till
runtime, you can build an entire loop as a string and eval that to avoid
recompiling all your patterns all the time.  Together with undefining
@samp{$/} to input entire files as one record, this can be very fast,
often faster than specialized programs like @samp{fgrep}.  The following
scans a list of files (@samp{@@files}) for a list of words
(@samp{@@words}), and prints out the names of those files that contain a
match:@refill

@example
@cindex Example, using @code{study} and @code{eval}
@cindex Using @code{study} and @code{eval} example
@cindex Example, simple fgrep
@cindex Simple fgrep example
$search = 'while (<>) @{ study;';
foreach $word (@@words) @{
    $search .= "++\$seen@{\$ARGV@} if /\b$word\b/;\n";
@}
$search .= "@}";
@@ARGV = @@files;
undef $/
eval $search;           # this screams
$/ = "\n";              # put back to normal input delim
foreach $file (sort keys(%seen)) @{
    print $file, "\n";
@}
@end example

@item tr/@var{SEARCHLIST}/@var{REPLACEMENTLIST}/cds
@itemx y/@var{SEARCHLIST}/@var{REPLACEMENTLIST}/cds
@cindex translate function
@findex translate function
@cindex @code{tr/SEARCHLIST/REPLACEMENTLIST/}
@cindex @code{y/SEARCHLIST/REPLACEMENTLIST/}
@findex tr/SEARCHLIST/REPLACEMENTLIST/
@findex y/SEARCHLIST/REPLACEMENTLIST/
Translates all occurrences of the characters found in the search list
with the corresponding character in the replacement list.  It returns
the number of characters replaced or deleted.  If no string is specified
via the @samp{=~} or @samp{!~} operator, the @samp{$_} string is
translated.  (The string specified with @samp{=~} must be a scalar
variable, an array element, or an assignment to one of those, i.e. an
lvalue.)  For @code{sed} devotees, @code{y} is provided as a synonym for
@code{tr}.

If the @samp{c} modifier is specified, the @var{SEARCHLIST} character
set is complemented.  If the @samp{d} modifier is specified, any
characters specified by @var{SEARCHLIST} that are not found in
@var{REPLACEMENTLIST} are deleted.  (Note that this is slightly more
flexible than the behavior of some @code{tr} programs, which delete
anything they find in the @var{SEARCHLIST}, period.)  If the @samp{s}
modifier is specified, sequences of characters that were translated to
the same character are squashed down to 1 instance of the
character.@refill
@c maybe add more description on s modifier and examples for tr///cds

If the @samp{d} modifier was used, the @var{REPLACEMENTLIST} is always
interpreted exactly as specified.  Otherwise, if the
@var{REPLACEMENTLIST} is shorter than the @var{SEARCHLIST}, the final
character is replicated till it is long enough.  If the
@var{REPLACEMENTLIST} is null, the @var{SEARCHLIST} is replicated.  The
latter is useful for counting characters in a class, or for squashing
character sequences in a class.@refill

Examples:@refill

@example
@cindex Example, translate function
@cindex translate function example
@cindex Example, @code{tr/SEARCHLIST/REPLACEMENTLIST/}
@cindex Example, @code{y/SEARCHLIST/REPLACEMENTLIST/}
@cindex @code{tr/SEARCHLIST/REPLACEMENTLIST/} example
@cindex @code{y/SEARCHLIST/REPLACEMENTLIST/} example
$ARGV[1] =~ y/A-Z/a-z/;          # canonicalize to lower case

$cnt = tr/*/*/;                  # count the stars in $_

$cnt = tr/0-9//;                 # count the digits in $_

tr/a-zA-Z//s;                    # bookkeeper -> bokeper

($HOST = $host) =~ tr/a-z/A-Z/;

y/\001-@@[-_@{-\177/ /;            # change non-alphas to space
                                 #   (before the c & s modifiers)
y/a-zA-Z/ /cs;                   # change non-alphas to single space
                                 #   (version 3.0 patchlevel 40+)

tr/\200-\377/\0-\177/;           # delete 8th bit
@end example
@end table

@node     System Interaction, Networking Functions, Search and Replace Functions, Commands
@comment  node-name,  next,  previous,  up
@section System Interaction
@cindex System Interaction

@table @asis
@item alarm(@var{SECONDS})
@itemx alarm @var{SECONDS}
@findex alarm
@cindex @code{alarm} function
@cindex Timers, @code{alarm} function
Arranges to have a @samp{SIGALRM} delivered to this process after the
specified number of seconds (minus 1, actually) have elapsed.  Thus,
@code{alarm(15)} will cause a @samp{SIGALRM} at some point more than 14
seconds in the future.  Only one timer may be counting at once.  Each
call disables the previous timer, and an argument of 0 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.@refill

@item chroot(@var{FILENAME})
@itemx chroot @var{FILENAME}
@itemx chroot
@c @@@@ above item not in orig man page pl28 @@@@
@cindex Change root system call
@cindex @code{chroot} function
@findex chroot
Does the same as the system call of that name.  If you don't know what
it does, don't worry about it.  If @var{FILENAME} is omitted, does
@code{chroot} to @samp{$_}.@refill

@item die(@var{LIST})
@itemx die @var{LIST}
@itemx die
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{die} function
@cindex Exitting perl script
@findex die
Outside of an @code{eval}, prints the value of @var{LIST} to
@samp{STDERR} and exits with the current value of @samp{$!} (errno).  As
of version 3.0 patchlevel 27, @code{die} without @var{LIST} specified is
equivalent to@refill
@example
die 'Died';
@end example
If @samp{$!} is 0, exits with the value of @samp{($? >> 8)} (`command`
status).  If @samp{($? >> 8)} is 0, exits with 255.  Inside an
@code{eval}, the error message is stuffed into @samp{$@@} and the
@code{eval} is terminated with the undefined value.@refill

@noindent
Equivalent examples:

@example
@cindex Example of @code{die} function
@cindex @code{die} function example
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';

chdir '/usr/spool/news' || die "Can't cd to spool: $!\n"
@end example

If the value of @var{EXPR} does not end in a newline, the current script
line number and input line number (if any) are also printed, and a
newline is supplied.  Hint: sometimes appending ``, stopped'' to your
message will cause it to make better sense when the string ``at foo line
123'' is appended.  Suppose you are running script ``canasta''.@refill

@example
die "/etc/games is no good";
die "/etc/games is no good, stopped";
@end example

@noindent
produce, respectively

@example
/etc/games is no good at canasta line 123.
/etc/games is no good, stopped at canasta line 123.
@end example

See also @code{exit}.

@item exec(@var{LIST})
@itemx exec @var{LIST}
@cindex @code{exec} function
@cindex Executing programs via @code{exec}
@findex exec
If there is more than one argument in @var{LIST}, or if @var{LIST} is an
array with more than one value, calls @code{execvp()} with the arguments
in @var{LIST}.  If there is only one scalar argument, the argument is
checked for shell metacharacters.  If there are any, the entire argument
is passed to @samp{/bin/sh -c} for parsing.  If there are none, the
argument is split into words and passed directly to @code{execvp()},
which is more efficient.  Note: @code{exec} (and @code{system}) do not
flush your output buffer, so you may need to set @samp{$|} to avoid lost
output.  Examples:@refill

@ifinfo
@cindex Example of executing a program in a perl script
@end ifinfo
@cindex Example of @code{exec}ing a program in a script
@example
@cindex Example of @code{exec} function
@cindex @code{exec} function example
exec '/bin/echo', 'Your arguments are: ', @@ARGV;
exec "sort $outfile | uniq";
@end example

If you don't really want to execute the first argument, but want to lie
to the program you are executing about its own name, you can specify the
program you actually want to run by assigning that to a variable and
putting the name of the variable in front of the @var{LIST} without a
comma.  (This always forces interpretation of the @var{LIST} as a
multi-valued list, even if there is only a single scalar in the list.)
Example:@refill

@example
$shell = '/bin/csh';
exec $shell '-sh';              # pretend it's a login shell
@end example

@item exit(@var{EXPR})
@itemx exit @var{EXPR}
@cindex @code{exit} function
@cindex Exitting a perl script
@findex exit
Evaluates @var{EXPR} and exits immediately with that value.  Example:@refill

@example
@cindex Example of @code{exit} function
@cindex @code{exit} function example
$ans = <STDIN>;
exit 0 if $ans =~ /^[Xx]/;
@end example

See also @code{die}.  If @var{EXPR} is omitted, exits with 0 status.@refill

@item fork
@cindex @code{fork} function
@cindex Child processes, creating
@cindex Creating multiple processes
@findex fork
Does a @code{fork()} call.  Returns the child pid to the parent process
and 0 to the child process.  Note: unflushed buffers remain unflushed in
both processes, which means you may need to set @samp{$|} to avoid
duplicate output.@refill

@item getpwnam(@var{NAME})
@itemx getgrnam(@var{NAME})
@itemx gethostbyname(@var{NAME})
@itemx getnetbyname(@var{NAME})
@itemx getprotobyname(@var{NAME})
@itemx getpwuid(@var{UID})
@itemx getgrgid(@var{GID})
@itemx getservbyname(@var{NAME},@var{PROTO})
@itemx gethostbyaddr(@var{ADDR},@var{ADDRTYPE})
@itemx getnetbyaddr(@var{ADDR},@var{ADDRTYPE})
@itemx getprotobynumber(@var{NUMBER})
@itemx getservbyport(@var{PORT},@var{PROTO})
@itemx getpwent
@itemx getgrent
@itemx gethostent
@itemx getnetent
@itemx getprotoent
@itemx getservent
@itemx setpwent
@itemx setgrent
@itemx sethostent(@var{STAYOPEN})
@itemx setnetent(@var{STAYOPEN})
@itemx setprotoent(@var{STAYOPEN})
@itemx setservent(@var{STAYOPEN})
@itemx endpwent
@itemx endgrent
@itemx endhostent
@itemx endnetent
@itemx endprotoent
@itemx endservent
@findex getpwnam
@findex getgrnam
@findex gethostbyname
@findex getnetbyname
@findex getprotobyname
@findex getpwuid
@findex getgrgid
@findex getservbyname
@findex gethostbyaddr
@findex getnetbyaddr
@findex getprotobynumber
@findex getservbyport
@findex getpwent
@findex getgrent
@findex gethostent
@findex getnetent
@findex getprotoent
@findex getservent
@findex setpwent
@findex setgrent
@findex sethostent
@findex setnetent
@findex setprotoent
@findex setservent
@findex endpwent
@findex endgrent
@findex endhostent
@findex endnetent
@findex endprotoent
@findex endservent
@comment @@@@ DON'T FORGET to do CINDEX stuff @@@@
These routines perform the same functions as their counterparts in the
system library.  The return values from the various get routines are as
follows:@refill

@example
($name,$passwd,$uid,$gid,
   $quota,$comment,$gcos,$dir,$shell) = getpw@dots{}
($name,$passwd,$gid,$members) = getgr@dots{}
($name,$aliases,$addrtype,$length,@@addrs) = gethost@dots{}
($name,$aliases,$addrtype,$net) = getnet@dots{}
($name,$aliases,$proto) = getproto@dots{}
($name,$aliases,$port,$proto) = getserv@dots{}
@end example

The @samp{$members} value returned by @code{getgr@dots{}} is a space
separated list of the login names of the members of the group.@refill

The @samp{@@addrs} value returned by the @code{gethost@dots{}} functions
is a list of the raw addresses returned by the corresponding system
library call.  In the Internet domain, each address is four bytes long and
you can unpack it by saying something like:@refill

@ifinfo
@cindex Example, Converting packed Internet host address
@cindex Converting packed Internet host address example
@end ifinfo
@example
@cindex Example, @code{unpack} function
@cindex @code{unpack} function example
@cindex Example, Converting packed IP address
@cindex Converting packed IP address example
($a,$b,$c,$d) = unpack('C4',$addr[0]);
@end example

@item getlogin
@cindex @code{getlogin} function
@cindex Reading @file{/etc/utmp}, login name
@cindex Current login name, from utmp
@cindex login name, finding current
@findex getlogin
Returns the current login from @file{/etc/utmp}, if any.  If null, use
@code{getpwuid}.@refill

@example
@cindex Example of @code{getlogin} function
@cindex @code{getlogin} example
@cindex Example, finding current login name
@cindex Finding current login name example
$login = getlogin || (getpwuid($<))[0] || "Somebody";
@end example

@item getpgrp(@var{PID})
@itemx getpgrp @var{PID}
@itemx getpgrp
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{getpgrp} function
@cindex Process group, finding
@cindex Finding process group
@findex getpgrp
Returns the current process group for the specified @var{PID}, 0 for the
current process.  Will produce a fatal error if used on a machine that
doesn't implement @code{getpgrp(2)}.  If PID is omitted, returns process
group of current process.  PID can be an expression.@refill
@comment @@@@ CHK ABOVE WORDING and args to getpgrp! @@@@

@item getppid
@cindex @code{getppid} function
@cindex Parent Process ID, finding
@cindex Parent PID, finding
@cindex Finding parent PID
@cindex Finding parent process id
@findex getppid
Returns the process id of the parent process.

@item getpriority(@var{WHICH},@var{WHO})
@cindex @code{getpriority} function
@cindex Current priority, Finding
@cindex Priority, Finding current
@cindex Finding current priority
@findex getpriority
Returns the current priority for a process, a process group, or a user.
(See the @code{getpriority(2)} man page.)  Will produce a fatal error if
used on a machine that doesn't implement @code{getpriority(2)}.@refill

@item ioctl(@var{FILEHANDLE},@var{FUNCTION},@var{SCALAR})
@cindex @code{ioctl} system call
@findex ioctl
Implements the @code{ioctl(2)} function.
You'll probably have to say

@example
require "ioctl.ph";   # probably @file{/usr/local/lib/perl/ioctl.ph}
@end example

@c @@@@ chged makelib to h2ph -- was prob w/orig man pg pl28 @@@@
@c @@@@ ioctl.h --> ioctl.ph  -- ditto @@@@
first to get the correct function definitions.  If @file{ioctl.ph}
doesn't exist or doesn't have the correct definitions you'll have to
roll your own, based on your C header files such as
@file{<sys/ioctl.h>}.  (There is a perl script called @code{h2ph}
that comes with the perl kit which may help you in this.)  @var{SCALAR}
will be read and/or written depending on the @var{FUNCTION}---a pointer
to the string value of @var{SCALAR} will be passed as the third argument
of the actual @code{ioctl} call.  (If @var{SCALAR} has no string value
but does have a numeric value, that value will be passed rather than a
pointer to the string value.  To guarantee this to be true, add a 0 to
the scalar before using it.)  The @code{pack()} and @code{unpack()}
functions are useful for manipulating the values of structures used by
@code{ioctl()}.@refill

The following example sets the erase character to DEL.

@example
@cindex Example, @code{ioctl} function
@cindex @code{ioctl} function example
@cindex Example, setting erase char to DEL
@cindex stty ex., setting erase char to DEL
require 'ioctl.ph';
$sgttyb_t = "ccccs";            # 4 chars and a short
if (ioctl(STDIN,$TIOCGETP,$sgttyb)) @{
        @@ary = unpack($sgttyb_t,$sgttyb);
        $ary[2] = 127;
        $sgttyb = pack($sgttyb_t,@@ary);
        ioctl(STDIN,$TIOCSETP,$sgttyb)
                || die "Can't ioctl: $!";
@}
@end example

The return value of @code{ioctl} (and @code{fcntl}) is as follows:@refill

@example
if OS returns:                  perl returns:
  -1                              undefined value
  0                               string "0 but true"
  anything else                   that number
@end example

Thus perl returns true on success and false on failure, yet you can still
easily determine the actual value returned by the operating system:@refill

@example
@cindex Example, system return value
@cindex System return value example
($retval = ioctl(@dots{})) || ($retval = -1);
printf "System returned %d\n", $retval;
@end example

@item kill(@var{LIST})
@itemx kill @var{LIST}
@cindex @code{kill} function
@cindex Sending a signal to a process
@findex kill
Sends a signal to a list of processes.  The first element of the list
must be the signal to send.  Returns the number of processes
successfully signaled.@refill

@example
@cindex Example of @code{kill} function
@cindex @code{kill} function example
@cindex Example, sending a signal
@cindex Sending a signal to a process example
$cnt = kill 1, $child1, $child2;
kill 9, @@goners;
@end example

If the signal is negative, kills process groups instead of processes.
(On System V, a negative @emph{process} number will also kill process
groups, but that's not portable.)  You may use a signal name in
quotes.@refill

@item setpgrp(@var{PID},@var{PGRP})
@cindex @code{setpgrp} function
@cindex Setting the current process group
@cindex Process group, setting current
@findex setpgrp
Sets the current process group for the specified @var{PID}, 0 for the
current process.  Will produce a fatal error if used on a machine that
doesn't implement @code{setpgrp(2)}.@refill

@item setpriority(@var{WHICH},@var{WHO},@var{PRIORITY})
@cindex @code{setpriority} function
@cindex Setting a process' priority
@cindex Processes, setting priority
@findex setpriority
Sets the current priority for a process, a process group, or a user.
(See the @code{setpriority(2)} man page.)  Will produce a fatal error if
used on a machine that doesn't implement @code{setpriority(2)}.@refill

@item sleep(@var{EXPR})
@itemx sleep @var{EXPR}
@itemx sleep
@cindex @code{sleep} function
@cindex Pausing for EXPR seconds
@cindex Sleeping for EXPR seconds
@findex sleep
Causes the script to sleep for @var{EXPR} seconds, or forever if no
@var{EXPR}.  May be interrupted by sending the process a
@samp{SIGALARM}.  Returns the number of seconds actually slept.@refill

@item syscall(@var{LIST})
@itemx syscall @var{LIST}
@cindex @code{syscall} function
@cindex Calling system calls
@findex syscall
Calls the system call specified as the first element of the list,
passing the remaining elements as arguments to the system call.  If
unimplemented, produces a fatal error.  The arguments are interpreted as
follows: if a given argument is numeric, the argument is passed as an
int.  If not, the pointer to the string value is passed.  You are
responsible to make sure a string is pre-extended long enough to receive
any result that might be written into a string.  If your integer
arguments are not literals and have never been interpreted in a numeric
context, you may need to add 0 to them to force them to look like
numbers.@refill

@example
@cindex Example of @code{syscall} function
@cindex @code{syscall} function example
require 'syscall.ph';         # may need to run h2ph
@c @@@@ maybe should note that b4 pl27 h2ph was called makelib @@@@
syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
@end example

@item sysread(@var{FILEHANDLE},@var{SCALAR},@var{LENGTH},@var{OFFSET})
@itemx sysread(@var{FILEHANDLE},@var{SCALAR},@var{LENGTH})
@findex sysread
@cindex sysread function
Attempts to read @var{LENGTH} bytes of data into variable @var{SCALAR}
from the specified @var{FILEHANDLE}, using the system call
@code{read(2)}.  It bypasses stdio, so mixing this with other kinds of
reads may cause confusion.  Returns the number of bytes actually read,
or @code{undef} if there was an error.  @var{SCALAR} will be grown or
shrunk to the length actually read.  An @var{OFFSET} may be specified to
place the read data at some other place than the beginning of the
string.@refill

@item syswrite(@var{FILEHANDLE},@var{SCALAR},@var{LENGTH},@var{OFFSET})
@itemx syswrite(@var{FILEHANDLE},@var{SCALAR},@var{LENGTH})
@findex syswrite
@cindex syswrite function
Attempts to write @var{LENGTH} bytes of data from variable @var{SCALAR}
to the specified @var{FILEHANDLE}, using the system call
@code{write(2)}.  It bypasses stdio, so mixing this with prints may
cause confusion.  Returns the number of bytes actually written, or
@code{undef} if there was an error.  An @var{OFFSET} may be specified
to place the read data at some other place than the beginning of the
string.@refill

@item system(@var{LIST})
@itemx system @var{LIST}
@cindex @code{system} function
@cindex Issuing a shell command
@findex system
Does exactly the same thing as @samp{exec @var{LIST}} except that a fork
is done first, and the parent process waits for the child process to
complete.  Note that argument processing varies depending on the number
of arguments.  The return value is the exit status of the program as
returned by the @code{wait()} call.  To get the actual exit value divide
by 256.  See also @code{exec}.@refill

@item times
@cindex @code{times} function
@cindex Finding user/system times
@cindex User and system times for a process
@cindex System and user times for a process
@findex times
Returns a four-element array giving the user and system times, in
seconds, for this process and the children of this process.@refill

@example
@cindex Example, @code{times} function
@cindex @code{times} function example
@cindex Example, process' user/system times
@cindex process' user/system times example
($user,$system,$cuser,$csystem) = times;
@end example

@item umask(@var{EXPR})
@itemx umask @var{EXPR}
@itemx umask
@cindex @code{umask} function
@cindex File permissions, default
@cindex Default file permissions
@findex umask
Sets the umask for the process and returns the old one.  If @var{EXPR}
is omitted, merely returns current umask.@refill

@item wait
@cindex @code{wait} function
@cindex Waiting for a child process to exit
@cindex Child processes, waiting for
@cindex Processes, waiting for child
@findex wait
Waits for a child process to terminate and returns the pid of the
deceased process, or -1 if there are no child processes.  The status is
returned in @samp{$?}.

@item waitpid(@var{PID},@var{FLAGS})
@findex waitpid
@cindex waitpid function
Waits for a particular child process to terminate and returns the pid of
the deceased process or -1 if there are no such child process.  The
status is returns in @samp{$?}.  If you say@refill

@example
require "sys/wait.ph";
@dots{}
waitpid(-1,&WNOHANG);
@end example

then you can do a non-blocking wait for any process.  Non-blocking wait
is only available on machines supporting either the @code{waitpid(2)} or
@code{wait4(2)} system calls.  However, waiting for a particular pid
with @var{FLAGS} of 0 is implemented everywhere.  (@emph{Perl} emulates
the system call by remembering the status values of processes that have
exited but have not been harvested by the @emph{Perl} script yet.)@refill

@ignore
@c deleted after perl 3.0 patchlevel 28 man page
If you expected a child and didn't find it, you probably had a call to
system, a close on a pipe, or backticks between the fork and the wait.
These constructs also do a wait and may have harvested your child
process.
@end ignore

@item warn(@var{LIST})
@itemx warn @var{LIST}
@cindex @code{warn} function
@ifinfo
@cindex Printing a message on STDERR, similar to die function
@end ifinfo
@tex
@cindex Printing a message on STDERR
@end tex
@cindex Similar to @code{die} function
@findex warn
@c @@@@ should we comment on warn w/o args ?? is that expected behaviour? @@@@
@c @@@@ (warn) is almost same as (warn "Warning: something's wrong") @@@@
@c @@@@ 'cept line number seems to be 1 > real line # @@@@
@c @@@@ like die w/o args pl28 @@@@
Produces a message on @samp{STDERR} just like @code{die}, but doesn't
exit.@refill
@end table

@node     Networking Functions, System V IPC, System Interaction, Commands
@comment  node-name,  next,  previous,  up
@section Networking Functions - Interprocess Communication
@cindex Interprocess Communication
@cindex IPC (Interprocess Communication)
@cindex Networking

@table @asis
@item accept(@var{NEWSOCKET},@var{GENERICSOCKET})
@cindex @code{accept} function
@cindex IPC functions
@ifinfo
@cindex Interprocess Communication functions
@end ifinfo
@cindex Sockets, Functions for
@findex accept
Does the same thing that the @code{accept} system call does.  Returns true
if it succeeded, false otherwise.  @xref{Interprocess Communication}, for
an example.@refill

@item bind(@var{SOCKET},@var{NAME})
@cindex IPC, @code{bind} function
@cindex Binding to a socket
@ifinfo
@cindex Interprocess Communication, @code{bind} function
@end ifinfo
@cindex Networking, binding to a socket
@cindex @code{bind} function
@findex bind
Does the same thing that the @code{bind} system call does.  Returns true
if it succeeded, false otherwise.  @var{NAME} should be a packed address
of the proper type for the socket.  @xref{Interprocess Communication}, for
an example.@refill

@item connect(@var{SOCKET},@var{NAME})
@cindex @code{connect} function
@cindex Connecting to a socket
@cindex IPC, @code{connect} function
@ifinfo
@cindex Interprocess Communication, @code{connect} function
@end ifinfo
@cindex Socket, connecting to
@findex connect
Does the same thing that the @code{connect} system call does.  Returns true
if it succeeded, false otherwise.  @var{NAME} should be a packed address of
the proper type for the socket.  @xref{Interprocess Communication}, for an
example.@refill

@item getpeername(@var{SOCKET})
@cindex IPC, @code{getpeername} function
@ifinfo
@cindex Interprocess Communication, @code{getpeername} function
@cindex Getting address of other end of socket connection
@end ifinfo
@cindex @code{getpeername} function
@findex getpeername
Returns the packed @emph{sockaddr} address of other end of the @var{SOCKET}
connection.@refill

@cindex Example, IPC - @code{getpeername} function
@cindex @code{getpeername} function example
@cindex IPC example, @code{getpeername} function
@ifinfo
@cindex Interprocess Communication example - @code{getpeername} function
@cindex Example, Interprocess Communication - @code{getpeername} function
@end ifinfo
@example
# An internet sockaddr
$sockaddr = 'S n a4 x8';
$hersockaddr = getpeername(S);
($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
@end example

@item getsockname(@var{SOCKET})
@cindex @code{getsockname} function
@cindex Sockets, Finding socket address
@cindex Finding socket address
@cindex IPC, Finding socket address
@ifinfo
@cindex Interprocess Communication, Finding socket address
@end ifinfo
@cindex Socket address, Finding
@findex getsockname
Returns the packed @emph{sockaddr} address of this end of the @var{SOCKET}
connection.@refill

@example
@cindex Example, Finding socket address
@cindex Finding socket address example
# An internet sockaddr
$sockaddr = 'S n a4 x8';
$mysockaddr = getsockname(S);
($family, $port, $myaddr) = unpack($sockaddr,$mysockaddr);
@end example

@item getsockopt(@var{SOCKET},@var{LEVEL},@var{OPTNAME})
@cindex @code{getsockopt} function
@cindex Sockets, Finding socket option
@cindex Finding socket option
@cindex IPC, Finding socket option
@ifinfo
@cindex Interprocess Communication, Finding socket option
@end ifinfo
@findex getsockopt
Returns the socket option requested, or undefined if there is an
error.@refill

@item listen(@var{SOCKET},@var{QUEUESIZE})
@cindex @code{listen} function
@cindex Sockets, @code{listen} system call
@cindex IPC, @code{listen} system call
@ifinfo
@cindex Interprocess Communication, @code{listen} system call
@end ifinfo
@findex listen
Does the same thing that the @code{listen} system call does.  Returns true
if it succeeded, false otherwise.  @xref{Interprocess Communication}, for an
example.@refill

@item recv(@var{SOCKET},@var{SCALAR},@var{LEN},@var{FLAGS})
@cindex @code{recv} function
@cindex Sockets, receiving a message
@cindex Receiving a message on a socket
@ifinfo
@cindex Interprocess Communication, receiving a message
@cindex Interprocess Communication, @code{recv} system call
@end ifinfo
@cindex IPC, receiving a message
@cindex IPC, @code{recv} system call
@cindex Sockets, @code{recv} system call
@findex recv
Receives a message on a socket.  Attempts to receive @var{LENGTH} bytes
of data into variable @var{SCALAR} from the specified @var{SOCKET}
filehandle.  Returns the address of the sender, or the undefined value
if there's an error.  @var{SCALAR} will be grown or shrunk to the length
actually read.  Takes the same flags as the system call of the same
name.@refill

@item send(@var{SOCKET},@var{MSG},@var{FLAGS},@var{TO})
@itemx send(@var{SOCKET},@var{MSG},@var{FLAGS})
@cindex @code{send} function
@cindex Sockets, sending a message
@ifinfo
@cindex Interprocess Communication, sending a message on a socket
@end ifinfo
@cindex IPC, sending a message on a socket
@cindex Sending a message on a socket
@findex send
Sends a message on a socket.  Takes the same flags as the system call of
the same name.  On unconnected sockets you must specify a destination to
send @var{TO}.  Returns the number of characters sent, or the undefined
value if there is an error.@refill

@item setsockopt(@var{SOCKET},@var{LEVEL},@var{OPTNAME},@var{OPTVAL})
@cindex @code{setsockopt} function
@cindex Sockets, setting socket options
@cindex IPC, setting socket options
@ifinfo
@cindex Interprocess Communication, setting socket options
@end ifinfo
@findex setsockopt
Sets the socket option requested.  Returns undefined if there is an
error.  @var{OPTVAL} may be specified as @code{undef} if you don't want
to pass an argument.@refill

@item shutdown(@var{SOCKET},@var{HOW})
@cindex @code{shutdown} function
@cindex Sockets, shutting down a socket
@cindex IPC, shutting down a socket
@ifinfo
@cindex Interprocess Communication, shutting down a socket connection
@end ifinfo
@cindex Shutting down a socket connection
@findex shutdown
Shuts down a socket connection in the manner indicated by @var{HOW},
which has the same interpretation as in the system call of the same
name.@refill

@item socket(@var{SOCKET},@var{DOMAIN},@var{TYPE},@var{PROTOCOL})
@cindex @code{socket} function
@cindex Sockets, opening a socket
@cindex Sockets, creating a socket
@cindex IPC, opening a socket
@cindex IPC, creating a socket
@ifinfo
@cindex Interprocess Communication, opening a socket
@cindex Interprocess Communication, creating a socket
@end ifinfo
@cindex Opening a socket
@cindex Creating a socket
@findex socket
@c @@@@ chged makelib to h2ph -- prob w/orig man pg pl28 @@@@
Opens a socket of the specified kind and attaches it to filehandle
@var{SOCKET}.  @var{DOMAIN}, @var{TYPE} and @var{PROTOCOL} are specified
the same as for the system call of the same name.  You may need to run
@code{h2ph} on @file{sys/socket.h} to get the proper values handy in
a perl library file.  Return true if successful.  @xref{Interprocess
Communication}, for an example.@refill

@item socketpair(@var{SOCKET1},@var{SOCKET2},@var{DOMAIN},@var{TYPE},@var{PROTOCOL})
@cindex @code{socketpair} function
@cindex Sockets, creating a pair of sockets
@cindex IPC, creating a pair of sockets
@ifinfo
@cindex Interprocess Communication, creating a pair of sockets
@end ifinfo
@cindex Creating a pair of sockets
@cindex Opening a pair of sockets
@findex socketpair
Creates an unnamed pair of sockets in the specified domain, of the
specified type.  @var{DOMAIN}, @var{TYPE} and @var{PROTOCOL} are
specified the same as for the system call of the same name.  If
unimplemented, yields a fatal error.  Return true if successful.@refill
@end table

@node     System V IPC, Time Functions, Networking Functions, Commands
@comment  node-name,  next,  previous,  up
@c PROBABLY should move to subsection along with @@@@
@c NF - IPC under one heading @@@@
@section Networking Functions - System V IPC
@cindex Interprocess Communication, System V
@cindex IPC (Interprocess Communication), System V
@cindex System V IPC
@cindex Networking, System V IPC
@cindex IPC, System V

@table @asis
@item msgctl(@var{ID},@var{CMD},@var{ARG})
@findex msgctl
@cindex Message Queue functions, msgctl
@cindex msgctl function
Calls the System V IPC function @code{msgctl}.  If @var{CMD} is
&IPC_STAT, then @var{ARG} must be a variable which will hold the
returned msqid_ds structure.  Returns like @code{ioctl}: the
undefined value for error, ``0 but true'' for zero, or the actual return
value otherwise.@refill

@item msgget(@var{KEY},@var{FLAGS})
@findex msgget
@cindex Message Queue functions, msgget
@cindex msgget function
Calls the System V IPC function @code{msgget}.  Returns the message
queue id, or the undefined value if there is an error.@refill

@item msgsnd(@var{ID},@var{MSG},@var{FLAGS})
@findex msgsnd
@cindex Message Queue functions, msgsnd
@cindex msgsnd function
Calls the System V IPC function @code{msgsnd} to send the message
@var{MSG} to the message queue @var{ID}.  @var{MSG} must begin with the
long integer message type, which may be created with
@samp{pack("L", $type)}.  Returns true if successful, or false if
there is an error.@refill

@item msgrcv(@var{ID},@var{VAR},@var{SIZE},@var{TYPE},@var{FLAGS})
@findex msgrcv
@cindex Message Queue functions, msgrcv
@cindex msgrcv function
Calls the System V IPC function @code{msgrcv} to receive a message
from message queue @var{ID} into variable @var{VAR} with a maximum
message size of @var{SIZE}.  Note that if a message is received, the
message type will be the first thing in @var{VAR}, and the maximum
length of @var{VAR} is @var{SIZE} plus the size of the message type.
Returns true if successful, or false if there is an error.@refill

@item semctl(@var{ID},@var{SEMNUM},@var{CMD},@var{ARG})
@findex semctl
@cindex Semaphore functions, semctl
@cindex semctl function
Calls the System V IPC function @code{semctl}.  If @var{CMD} is
&IPC_STAT or &GETALL, then @var{ARG} must be a variable which will hold
the returned semid_ds structure or semaphore value array.  Returns like
@code{ioctl}: the undefined value for error, ``0 but true'' for zero,
or the actual return value otherwise.@refill

@item semget(@var{KEY},@var{NSEMS},@var{SIZE},@var{FLAGS})
@findex semget
@cindex Semaphore functions, semget
@cindex semget function
Calls the System V IPC function @code{semget}.  Returns the semaphore
id, or the undefined value if there is an error.@refill

@item semop(@var{KEY},@var{OPSTRING})
@findex semop
@cindex Semaphore functions, semop
@cindex semop function
@cindex System V IPC, semaphore functions
Calls the System V IPC function @code{semop} to perform semaphore operations
such as signaling and waiting.  @var{OPSTRING} must be a packed array of
semop structures.  Each semop structure can be generated with
@samp{pack("sss", $semnum, $semop, $semflag)}.  The number of semaphore
operations is implied by the length of @var{OPSTRING}.  Returns true if
successful, or false if there is an error.  As an example, the
following code waits on semaphore $semnum of semaphore id $semid:@refill

@example
$semop = pack("sss", $semnum, -1, 0);
die "Semaphore trouble: $!\n" unless semop($semid, $semop);
@end example

To signal the semaphore, replace @samp{-1} with @samp{1}.@refill

@item shmctl(@var{ID},@var{CMD},@var{ARG})
@findex shmctl
@cindex shmctl function
@cindex Shared Memory function, shmctl
Calls the System V IPC function @code{shmctl}.  If @var{CMD} is
&IPC_STAT, then @var{ARG} must be a variable which will hold the
returned shmid_ds structure.  Returns like @code{ioctl}: the
undefined value for error, ``0 but true'' for zero, or the actual return
value otherwise.@refill

@item shmget(@var{KEY},@var{SIZE},@var{FLAGS})
@findex shmget
@cindex shmget function
@cindex Shared Memory functions, shmget
Calls the System V IPC function @code{shmget}.  Returns the shared
memory segment id, or the undefined value if there is an error.@refill

@item shmread(@var{ID},@var{VAR},@var{POS},@var{SIZE})
@itemx shmwrite(@var{ID},@var{STRING},@var{POS},@var{SIZE})
@findex shmread
@findex shmwrite
@cindex Shared Memory functions, shmread
@cindex Shared Memory functions, shmwrite
@cindex shmread function
@cindex shmwrite function
Reads or writes the System V shared memory segment @var{ID} starting at
position @var{POS} for size @var{SIZE} by attaching to it, copying in/out, and
detaching from it.  When reading, @var{VAR} must be a variable which
will hold the data read.  When writing, if @var{STRING} is too long,
only @var{SIZE} bytes are used; if @var{STRING} is too short, nulls are
written to fill out @var{SIZE} bytes.  Returns true if successful, or
false if there is an error.@refill
@end table

@node     Time Functions, DBM Functions, System V IPC, Commands
@comment  node-name,  next,  previous,  up
@section Time Related Functions
@cindex Time Functions

@table @asis
@item gmtime(@var{EXPR})
@itemx gmtime @var{EXPR}
@itemx gmtime
@c @@@@ above not in orig man pg pl28 @@@@
@cindex Time functions, Greenwich time
@cindex Greenwich time conversion
@cindex @code{gmtime} function
@findex gmtime
Converts a time as returned by the @code{time} function to a 9-element
array with the time analyzed for the Greenwich timezone.  Typically used
as follows:@refill

@example
@cindex Example, @code{gmtime} function
@cindex @code{gmtime} function example
@cindex Example, converting to Greenwich time
@cindex Converting to Greenwich time
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
                                            = gmtime(time);
@end example

All array elements are numeric, and come straight out of a @samp{struct tm}.
In particular this means that @code{$mon} has the range @samp{0..11} and
@code{$wday} has the range @samp{0..6}.  If @var{EXPR} is omitted, does
@samp{gmtime(time)}.@refill

@item localtime(@var{EXPR})
@itemx localtime @var{EXPR}
@itemx localtime
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{localtime} function
@ifinfo
@cindex Time conversion, seconds to local timezone
@end ifinfo
@cindex Time conversion, local timezone
@cindex Local timezone, time conversion
@findex localtime
Converts a time as returned by the time function to a 9-element array
with the time analyzed for the local timezone.  Typically used as
follows:@refill

@example
@cindex Example of @code{localtime} function
@cindex @code{localtime} function example
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
                                        = localtime(time);
@end example

All array elements are numeric, and come straight out of a @samp{struct tm}.
In particular this means that $mon has the range @samp{0..11} and $wday has
the range @samp{0..6}.  If @var{EXPR} is omitted, does
@code{localtime(time)}.@refill

@item time
@cindex @code{time} function
@findex time
Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970.
Suitable for feeding to @code{gmtime()} and @code{localtime()}.@refill
@end table

@node     DBM Functions, Flow Control Functions, Time Functions, Commands
@comment  node-name,  next,  previous,  up
@section DBM Functions
@cindex dbm functions
@cindex Database Functions

@c @@@@ talk a little about dbm files @@@@
@c @@@@ maybe include example dealing with sendmail aliases file @@@@
@c
@table @asis
@c @@@@ make dbm (or database functions) node @@@@
@item dbmclose(@var{ASSOC_ARRAY})
@itemx dbmclose @var{ASSOC_ARRAY}
@cindex dbm library, @code{dbmclose} function
@cindex @code{dbmclose} function
@cindex Database library (dbm), @code{dbmclose}
@findex dbmclose
Breaks the binding between a dbm file and an associative array.  The
values remaining in the associative array are meaningless unless you
happen to want to know what was in the cache for the dbm file.  This
function is only useful if you have ndbm.@refill

@item dbmopen(@var{ASSOC},@var{DBNAME},@var{MODE})
@cindex dbm library, @code{dbmopen} function
@cindex @code{dbmopen} function
@cindex Database library (dbm), @code{dbmopen}
@findex dbmopen
This binds a dbm or ndbm file to an associative array.  @var{ASSOC} is
the name of the associative array.  (Unlike normal open, the first
argument is @strong{NOT} a filehandle, even though it looks like one).
@var{DBNAME} is the name of the database (without the @file{.dir} or
@file{.pag} extension).  If the database does not exist, it is created
with protection specified by @var{MODE} (as modified by the umask).  If
your system only supports the older dbm functions, you may only have one
@code{dbmopen} in your program.  If your system has neither dbm nor ndbm,
calling @code{dbmopen} produces a fatal error.@refill

Values assigned to the associative array prior to the @code{dbmopen} are
lost.  A certain number of values from the dbm file are cached in memory.
By default this number is 64, but you can increase it by preallocating
that number of garbage entries in the associative array before the
@code{dbmopen}.  You can flush the cache if necessary with the reset
command.@refill

If you don't have write access to the dbm file, you can only read
associative array variables, not set them.  If you want to test whether
you can write, either use file tests or try setting a dummy array entry
inside an eval, which will trap the error.@refill

Note that functions such as @code{keys()} and @code{values()} may return
huge array values when used on large dbm files.  You may prefer to use
the @code{each()} function to iterate over large dbm files.  Example:@refill

@example
@cindex Example, using @code{each} with dbm file
@cindex Example, dbm
@cindex dbm example
@cindex Example of @code{each} function
@cindex @code{each} function example
# print out history file offsets
dbmopen(HIST,'/usr/lib/news/history',0666);
while (($key,$val) = each %HIST) @{
        print $key, ' = ', unpack('L',$val), "\n";
@}
dbmclose(HIST);
@end example
@end table

@node     Flow Control Functions, Perl Library Functions, DBM Functions, Commands
@comment  node-name,  next,  previous,  up
@section Flow Control Functions
@cindex Flow Control Functions

@table @asis
@item do @var{BLOCK}
@cindex @code{do BLOCK}
@findex do BLOCK
Returns the value of the last command in the sequence of commands
indicated by @var{BLOCK}.  When modified by a loop modifier, executes
the @var{BLOCK} once before testing the loop condition.  (On other
statements the loop modifiers test the conditional first.)@refill

@item goto @var{LABEL}
@cindex @code{goto} function
@cindex Branching
@cindex @code{goto LABEL}
@findex goto
Finds the statement labeled with @var{LABEL} and resumes execution
there.  Currently you may only go to statements in the main body of the
program that are not nested inside a @samp{do @{@}} construct.  This
statement is not implemented very efficiently, and is here only to make
the @emph{sed}-to-@emph{perl} translator easier.  I may change its
semantics at any time, consistent with support for translated @code{sed}
scripts.  Use it at your own risk.  Better yet, don't use it at all.@refill

@item last @var{LABEL}
@itemx last
@cindex @code{last} function
@cindex Loops, @code{last} function
@cindex break statement in C
@cindex Exiting a loop
@findex last
The @code{last} command is like the @code{break} statement in C (as used
in loops); it immediately exits the loop in question.  If the @var{LABEL}
is omitted, the command refers to the innermost enclosing loop.  The
@code{continue} block, if any, is not executed:@refill

@example
@cindex Example of @code{last} function
@cindex @code{last} function example
line: while (<STDIN>) @{
        last line if /^$/;      # exit when done with header
        @dots{}
@}
@end example

@item next @var{LABEL}
@itemx next
@cindex @code{next} function
@cindex Loops, @code{next} function
@cindex Loops, continuing
@cindex continue statement in C
@findex next
The @code{next} command is like the @code{continue} statement in C; it
starts the next iteration of the loop:@refill

@example
@cindex Example, @code{next} function
@cindex @code{next} function example
@cindex Example, Loops and @code{next} function
line: while (<STDIN>) @{
        next line if /^#/;      # discard comments
        @dots{}
@}
@end example

Note that if there were a @code{continue} block on the above, it would
get executed even on discarded lines.  If the @var{LABEL} is omitted,
the command refers to the innermost enclosing loop.@refill

@item redo @var{LABEL}
@itemx redo
@cindex @code{redo} function
@cindex Loops, restarting
@cindex Restarting loops
@findex redo
The @code{redo} command restarts the loop block without evaluating the
conditional again.  The @code{continue} block, if any, is not executed.
If the @var{LABEL} is omitted, the command refers to the innermost
enclosing loop.  This command is normally used by programs that want to
lie to themselves about what was just input:@refill

@example
@cindex Example, @code{redo} function
@cindex @code{redo} function example
@cindex Example, Pascal comment stripper
@cindex Pascal comment stripper example
# a simpleminded Pascal comment stripper
# (warning: assumes no @{ or @} in strings)
line: while (<STDIN>) @{
        while (s|(@{.*@}.*)@{.*@}|$1 |) @{@}
        s|@{.*@}| |;
        if (s|@{.*| |) @{
                $front = $_;
                while (<STDIN>) @{
                        if (/@}/) @{    # end of comment?
                                s|^|$front@{|;
                                redo line;
                        @}
                @}
        @}
        print;
@}
@end example
@end table

@node     Perl Library Functions, Subroutine Functions, Flow Control Functions, Commands
@comment  node-name,  next,  previous,  up
@section Perl Library Functions
@cindex Perl Library Functions

@table @asis
@item require(@var{EXPR})
@item require @var{EXPR}
@item require
@cindex @code{require} function
@cindex Including library files
@cindex Library files, Including
@findex require
Includes the library file specified by @var{EXPR}, or by @samp{$_} if
@var{EXPR} is not supplied.  Has semantics similar to the following
subroutine:@refill

@cindex @code{require} operator implementation
@example
sub require @{
    local($filename) = @@_;
    return 1 if $INC@{$filename@};
    local($realfilename,$result);
    ITER: @{
        foreach $prefix (@@INC) @{
            $realfilename = "$prefix/$filename";
            if (-f $realfilename) @{
                $result = do $realfilename;
                last ITER;
            @}
        @}
        die "Can't find $filename in \@@INC";
    @}
    die $@@ if $@@;
    die "$filename did not return true value" unless $result;
    $INC@{$filename@} = $realfilename;
    $result;
@}
@end example

Note that the file will not be included twice under the same specified
name.@refill

@item do @var{EXPR}
@cindex @code{do EXPR}
@findex do EXPR
Uses the value of @var{EXPR} as a filename and executes the contents of
the file as a @emph{perl} script.  Its primary use is to include
subroutines from a @emph{perl} subroutine library.@refill

@example
@cindex Example, @code{do EXPR}
@cindex @code{do EXPR} example
do 'stat.pl';
@end example

@noindent
is just like

@example
eval `cat stat.pl`;
@end example

except that it's more efficient, more concise, keeps track of the
current filename for error messages, and searches all the @samp{-I}
libraries if the file isn't in the current directory (@pxref{Predefined
Names,``INC'' array}, for more info).  It's the same, however, in
that it does reparse the file every time you call it, so if you are
going to use the file inside a loop you might prefer to use @samp{-P}
and @samp{#include}, at the expense of a little more startup time.  (The
main problem with @samp{#include} is that cpp doesn't grok @samp{#}
comments---a workaround is to use @samp{;#} for standalone comments.)
Note that the following are @strong{NOT} equivalent:@refill

@example
do $foo;        # eval a file
do $foo();      # call a subroutine
@end example

Note that inclusion of library routines is better done with the
@code{require} operator.@refill
@end table

@node     Subroutine Functions, Variable Functions, Perl Library Functions, Commands
@comment  node-name,  next,  previous,  up
@section Subroutine Functions
@cindex Subroutine Functions

@table @asis
@item caller(@var{EXPR})
@item caller
@findex caller
@cindex caller function
@cindex Subroutine context
@cindex Context of subroutine
@cindex Current context of subroutine
@cindex Current subroutine context
Returns the context of the current subroutine call:

@example
($package,$filename,$line) = caller;
@end example

With @var{EXPR}, returns some extra information that the debugger uses
to print a stack trace.  The value of @var{EXPR} indicates how many call
frames to go back before the current one.@refill

@item do @var{SUBROUTINE} (@var{LIST})
@cindex @code{do SUBROUTINE}
@findex do SUBROUTINE
Executes a @var{SUBROUTINE} declared by a @code{sub} declaration, and
returns the value of the last expression evaluated in @var{SUBROUTINE}.
If there is no subroutine by that name, produces a fatal error.  (You
may use the @code{defined} operator to determine if a subroutine
exists.)  If you pass arrays as part of @var{LIST} you may wish to pass
the length of the array in front of each array.  (@xref{Subroutines}.)
@var{SUBROUTINE} may be a scalar variable, in which case the variable
contains the name of the subroutine to execute.  The parentheses are
required to avoid confusion with the @samp{do @var{EXPR}} form.@refill

As an alternate form, you may call a subroutine by prefixing the name
with an ampersand: @samp{&foo(@@args)}.  If you aren't passing any
arguments, you don't have to use parentheses.  If you omit the
parentheses, no @samp{@@_} array is passed to the subroutine.  The @samp{&}
form is also used to specify subroutines to the @code{defined} and
@code{undef} operators.@refill

@item local(@var{LIST})
@cindex @code{local} function
@cindex Declaring local variables
@cindex variables, Declaring local
@cindex local variables, Declaring
@findex local
Declares the listed variables to be local to the enclosing block,
subroutine, @code{eval} or @code{do}.  All the listed elements must be
legal lvalues.  This operator works by saving the current values of
those variables in @var{LIST} on a hidden stack and restoring them upon
exiting the block, subroutine or @code{eval}.  This means that called
subroutines can also reference the local variable, but not the global
one.  The @var{LIST} may be assigned to if desired, which allows you to
initialize your local variables.  (If no initializer is given for a
particular variable, it is created with an undefined value.)  Commonly
this is used to name the parameters to a subroutine.  Examples:@refill

@example
@cindex Example, @code{local} function
@cindex @code{local} function example
@cindex Example, declaring local variables
@cindex Declaring local variable examples
sub RANGEVAL @{
        local($min, $max, $thunk) = @@_;
        local($result) = @'@';
        local($i);

        # Presumably $thunk makes reference to $i

        for ($i = $min; $i < $max; $i++) @{
                $result .= eval $thunk;
        @}

        $result;
@}

if ($sw eq '-v') @{
    # init local array with global array
    local(@@ARGV) = @@ARGV;
    unshift(@@ARGV,'echo');
    system @@ARGV;
@}
# @@ARGV restored

# temporarily add to digits associative array
if ($base12) @{
        # (NOTE: not claiming this is efficient!)
        local(%digits) = (%digits,'t',10,'e',11);
        do parse_num();
@}
@end example

Note that @code{local()} is a run-time command, and so gets executed
every time through a loop, using up more stack storage each time until
it's all released at once when the loop is exited.@refill

@item return @var{LIST}
@cindex @code{return} function
@cindex Returning a value from a subroutine
@cindex Return value
@findex return
Returns from a subroutine with the value specified.  (Note that a
subroutine can automatically return the value of the last expression
evaluated.  That's the preferred method---use of an explicit
@code{return} is a bit slower.)@refill

@c @@@@ do we want wantarray in this node ?? @@@@
@item wantarray
@cindex @code{wantarray} function
@cindex Array context
@findex wantarray
Returns true if the context of the currently executing subroutine is
looking for an array value.  Returns false if the context is looking for
a scalar.@refill

@example
@cindex Example, @code{wantarray} function
@cindex @code{wantarray} function example
return wantarray ? () : undef;
@end example
@end table

@node     Variable Functions, Miscellaneous Functions, Subroutine Functions, Commands
@comment  node-name,  next,  previous,  up
@section Variable Functions
@cindex Variable Functions

@table @asis
@item defined(@var{EXPR})
@itemx defined @var{EXPR}
@cindex @code{defined} function
@findex defined
Returns a boolean value saying whether the lvalue @var{EXPR} has a real
value or not.  Many operations return the undefined value under
exceptional conditions, such as end of file, uninitialized variable,
system error and such.  This function allows you to distinguish between
an undefined null string and a defined null string with operations that
might return a real null string, in particular referencing elements of
an array.  You may also check to see if arrays or subroutines exist.
Use on predefined variables is not guaranteed to produce intuitive
results.  Examples:@refill

@example
@cindex Examples of @code{defined} function
@cindex @code{defined} function examples
print if defined $switch@{'D'@};
print "$val\n" while defined($val = pop(@@ary));
die "Can't readlink $sym: $!"
        unless defined($value = readlink $sym);
eval '@@foo = ()' if defined(@@foo);
die "No XYZ package defined" unless defined %_XYZ;
sub foo @{ defined &bar ? &bar(@@_) : die "No bar"; @}
@end example

See also @code{undef}.

@item reset(@var{EXPR})
@itemx reset @var{EXPR}
@itemx reset
@cindex @code{reset} function
@cindex Clearing variables
@cindex Resetting @code{??} searches
@cindex Resetting variables
@findex reset
Generally used in a @code{continue} block at the end of a loop to clear
variables and reset @samp{??} searches so that they work again.  The
expression is interpreted as a list of single characters (hyphens allowed
for ranges).  All variables and arrays beginning with one of those letters
are reset to their pristine state.  If the expression is omitted,
one-match searches (@samp{?pattern?}) are reset to match again.  Only resets
variables or searches in the current package.  Always returns 1.
Examples:@refill

@example
@cindex Example of @code{reset} function
@cindex @code{reset} function example
reset 'X';          # reset all X variables
reset 'a-z';        # reset lower case variables
reset;              # just reset @samp{??} searches
@end example

Note: resetting @samp{A-Z} is not recommended since you'll wipe out your
@samp{ARGV} and @samp{ENV} arrays.@refill

The use of reset on dbm associative arrays does not change the dbm file.
(It does, however, flush any entries cached by perl, which may be useful
if you are sharing the dbm file.  Then again, maybe not.)@refill

@item scalar(@var{EXPR})
@findex scalar
@cindex scalar function
@cindex Forcing scalar context
@cindex Scalar context, forcing
@cindex Context, forcing scalar
Forces @var{EXPR} to be interpreted in a scalar context and returns the
value of @var{EXPR}.@refill

@item undef(@var{EXPR})
@itemx undef @var{EXPR}
@itemx undef
@cindex @code{undef} function
@cindex Undefining a value
@findex undef
Undefines the value of @var{EXPR}, which must be an lvalue.  Use only on
a scalar value, an entire array, or a subroutine name (using @samp{&}).
(@code{undef} will probably not do what you expect on most predefined
variables or dbm array values.)  Always returns the undefined value.
You can omit the @var{EXPR}, in which case nothing is undefined, but you
still get an undefined value that you could, for instance, return from a
subroutine.  Examples:@refill

@example
@cindex Examples of @code{undef} function
@cindex @code{undef} function examples
undef $foo;
undef $bar@{'blurfl'@};
undef @@ary;
undef %assoc;
undef &mysub;
return (wantarray ? () : undef) if $they_blew_it;
@end example
@end table

@node     Miscellaneous Functions, , Variable Functions, Commands
@comment  node-name,  next,  previous,  up
@section Miscellaneous Functions
@cindex Miscellaneous Functions

@table @asis
@item dump @var{LABEL}
@itemx dump
@c @@@@ above not in orig man pg pl28 @@@@
@cindex Core dump
@cindex How to create a core file for @code{undump}
@cindex @samp{undump}, creating a core file
@cindex @code{dump}, creating a core file
@cindex Creating a core file
@findex dump
This causes an immediate core dump.  Primarily this is so that you can use
the @samp{undump} program to turn your core dump into an executable binary
after having initialized all your variables at the beginning of the
program.  When the new binary is executed it will begin by executing a
@samp{goto @var{LABEL}} (with all the restrictions that @code{goto}
suffers).  Think of it as a @code{goto} with an intervening core dump and
reincarnation.  If @var{LABEL} is omitted, restarts the program from the
top.  @strong{WARNING}: any files opened at the time of the dump will
@strong{NOT} be open any more when the program is reincarnated, with
possible resulting confusion on the part of perl.  See also
@samp{-u}.@refill

Example:

@example
@cindex Example of @code{dump} function
@cindex @code{dump} function example
#!/usr/bin/perl
    require 'getopt.pl';
    require 'stat.pl';
    %days = (
        'Sun',1,
        'Mon',2,
        'Tue',3,
        'Wed',4,
        'Thu',5,
        'Fri',6,
        'Sat',7);

    dump QUICKSTART if $ARGV[0] eq '-d';

QUICKSTART:
    do Getopt('f');
    @dots{}
@end example

@item eval(@var{EXPR})
@itemx eval @var{EXPR}
@itemx eval
@c @@@@ above not in orig man pg pl28 @@@@
@cindex @code{eval} function
@cindex Parsing and executing variable code
@cindex Testing if a feature exists
@findex eval
@var{EXPR} is parsed and executed as if it were a little @emph{perl}
program.  It is executed in the context of the current @emph{perl}
program, so that any variable settings, subroutine or format definitions
remain afterwards.  The value returned is the value of the last
expression evaluated, just as with subroutines.  If there is a syntax
error or runtime error, or a @code{die} statement is executed, an
undefined value is returned by @code{eval}, and @samp{$@@} is set to the
error message.  If there was no error, @samp{$@@} is guaranteed to be a
null string.  If @var{EXPR} is omitted, evaluates @samp{$_}.  The final
semicolon, if any, may be omitted from the expression.@refill

Note that, since @code{eval} traps otherwise-fatal errors, it is useful
for determining whether a particular feature (such as @code{dbmopen} or
@code{symlink}) is implemented.  If is also @emph{Perl}'s exception
trapping mechanism, where the @code{die} operator is used to raise
exceptions.@refill

@item ord(@var{EXPR})
@itemx ord @var{EXPR}
@itemx ord
@c @@@@ above line not in orig man page pl28 @@@@
@cindex @code{ord} function
@cindex Conversion of char to its ascii value
@cindex Ascii character value
@findex ord
Returns the numeric ascii value of the first character of @var{EXPR}.
If @var{EXPR} is omitted, uses @samp{$_}.@refill

@item q/@var{STRING}/
@itemx qq/@var{STRING}/
@itemx qx/@var{STRING}/
@cindex Quote operator
@findex q (single quote operator)
@findex qq (double quote operator)
@findex qx (backquote operator)
These are not really functions, but simply syntactic sugar to let you
avoid putting too many backslashes into quoted strings.  The @code{q}
operator is a generalized single quote, and the @code{qq} operator a
generalized double quote.  The @code{qx} operator is a generalized
backquote.  Any non-alphanumeric delimiter can be used in place of
@samp{/}, including newline.  If the delimiter is an opening bracket or
parenthesis, the final delimiter will be the corresponding closing
bracket or parenthesis.  (Embedded occurrences of the closing bracket
need to be backslashed as usual.)  Examples:@refill

@example
@cindex Example, @code{q} operator
@cindex Example, @code{qq} operator
@cindex @code{q} operator example
@cindex @code{qq} operator example
$foo = q!I said, "You said, 'She said it.'"!;
$bar = q('This is it.');
$today = qx@{ date @};
$_ .= qq
*** The previous line contains the naughty word "$&".\n
        if /(ibm|apple|awk)/;      # :-)
@end example

@item rand(@var{EXPR})
@itemx rand @var{EXPR}
@itemx rand
@cindex @code{rand} function
@cindex Random number generation
@findex rand
Returns a random fractional number between 0 and the value of
@var{EXPR}.  (@var{EXPR} should be positive.)  If @var{EXPR} is omitted,
returns a value between 0 and 1.  See also @code{srand()}.@refill

@item srand(@var{EXPR})
@itemx srand @var{EXPR}
@itemx srand
@c @@@@ above line not in orig man page pl28 @@@@
@cindex @code{srand} function
@ifinfo
@cindex Setting the seed for the random number generator
@end ifinfo
@cindex Setting random number gen. seed
@cindex Random number generator seed
@cindex Seed, random number generator
@findex srand
Sets the random number seed for the @code{rand} operator.  If @var{EXPR}
is omitted, does @code{srand(time)}.@refill

@item sprintf(@var{FORMAT},@var{LIST})
@cindex @code{sprintf} function
@cindex Formatting a string
@findex sprintf
Returns a string formatted by the usual @code{printf} conventions.  The
@samp{*} character is not supported.@refill

@item vec(@var{EXPR},@var{OFFSET},@var{BITS})
@cindex @code{vec} function
@cindex bitfields and vectors
@cindex vectors and bitfields
@findex vec
Treats a string as a vector of unsigned integers, and returns the value
of the bitfield specified.  May also be assigned to.  @var{BITS} must be
a power of two from 1 to 32.@refill

Vectors created with @code{vec()} can also be manipulated with the
logical operators @samp{|}, @samp{&} and @samp{^}, which will assume a
bit vector operation is desired when both operands are strings.  This
interpretation is not enabled unless there is at least one @code{vec()}
in your program, to protect older programs.@refill

To transform a bit vector into a string or array of 0's and 1's, use
these:@refill

@example
$bits = unpack("b*", $vector);
@@bits = split(//, unpack("b*", $vector));
@end example

If you know the exact length in bits, it can be used in place of the *.
@end table

@node     Precedence, Subroutines, Commands, Top
@comment  node-name,  next,  previous,  up
@chapter Precedence
@cindex Precedence

@emph{Perl} operators have the following associativity and
precedence:@refill

@comment @@@@ use display or example or table ?? @@@@
@example
@cindex Operator precedence
@cindex Precedence of operators
@cindex Operator associativity
@cindex Associativity of operators
nonassoc   print printf exec system sort reverse
                chmod chown kill unlink utime die return
left       ,
right      = += \-= *= etc.
right      ?:
nonassoc   ..
left       ||
left       &&
left       | ^
left       &
nonassoc   == != <=> eq ne cmp
nonassoc   < > <= >= lt gt le ge
nonassoc   chdir exit eval reset sleep rand umask
nonassoc   -r -w -x etc.
left       << >>
left       + - .
left       * / % x
left       =~ !~
right      ! ~ and unary minus
right      **
nonassoc   ++ --
left       @samp{(}
@end example

As mentioned earlier, if any list operator (@code{print}, etc.) or any unary
operator (@code{chdir}, etc.)  is followed by a left parenthesis as the next
token on the same line, the operator and arguments within parentheses
are taken to be of highest precedence, just like a normal function call.
Examples:@refill

@example
@cindex Examples of precedence
@cindex Precedence examples
chdir $foo || die;              # (chdir $foo) || die
chdir($foo) || die;             # (chdir $foo) || die
chdir ($foo) || die;            # (chdir $foo) || die
chdir +($foo) || die;           # (chdir $foo) || die
@end example

but, because @samp{*} is higher precedence than @samp{||}:

@example
@cindex Examples of precedence
@cindex Precedence examples
chdir $foo * 20;                # chdir ($foo * 20)
chdir($foo) * 20;               # (chdir $foo) * 20
chdir ($foo) * 20;              # (chdir $foo) * 20
chdir +($foo) * 20;             # chdir ($foo * 20)

rand 10 * 20;                   # rand (10 * 20)
rand(10) * 20;                  # (rand 10) * 20
rand (10) * 20;                 # (rand 10) * 20
rand +(10) * 20;                # rand (10 * 20)
@end example

In the absence of parentheses, the precedence of list operators such as
@code{print}, @code{sort} or @code{chmod} is either very high or very
low depending on whether you look at the left side of operator or the
right side of it.  For example, in@refill

@example
@cindex Examples of precedence
@cindex Precedence examples
@@ary = (1, 3, sort 4, 2);
print @@ary;            # prints 1324
@end example

the commas on the right of the sort are evaluated before the sort, but
the commas on the left are evaluated after.  In other words, list
operators tend to gobble up all the arguments that follow them, and then
act like a simple term with regard to the preceding expression.  Note
that you have to be careful with parens:@refill

@example
@cindex Examples of precedence
@cindex Precedence examples
# These evaluate exit before doing the print:
print($foo, exit);      # Obviously not what you want.
print $foo, exit;       # Nor is this.

# These do the print before evaluating exit:
(print $foo), exit;     # This is what you want.
print($foo), exit;      # Or this.
print ($foo), exit;     # Or even this.
@end example

Also note that

@example
@cindex Examples of precedence
@cindex Precedence examples
print ($foo & 255) + 1, "\n";
@end example

probably doesn't do what you expect at first glance.

@node     Subroutines, Passing By Reference, Precedence, Top
@comment  node-name,  next,  previous,  up
@chapter Subroutines
@cindex Subroutines

A subroutine may be declared as follows:

@example
sub NAME BLOCK
@end example

Any arguments passed to the routine come in as array @samp{@@_}, that is
@samp{($_[0], $_[1], @dots{})}.  The array @samp{@@_} is a local array,
but its values are references to the actual scalar parameters.  The
return value of the subroutine is the value of the last expression
evaluated, and can be either an array value or a scalar value.
Alternately, a return statement may be used to specify the returned
value and exit the subroutine.  To create local variables see the
@code{local} operator.@refill

A subroutine is called using the @code{do} operator or the @code{&}
operator.@refill

Example:

@example
@cindex Examples of subroutines
@cindex Subroutine examples
@cindex Example of a max subroutine
@cindex max subroutine example
sub MAX @{
        local($max) = pop(@@_);
        foreach $foo (@@_) @{
                $max = $foo if $max < $foo;
        @}
        $max;
@}

@dots{}
$bestday = &MAX($mon,$tue,$wed,$thu,$fri);
@end example

Example:

@cindex Examples of subroutines
@cindex Subroutine examples
@cindex Example, get_line subroutine
@cindex get_line subroutine example
@ifinfo
@cindex Example, reading lines with continuation lines
@cindex Reading lines with continuation lines example
@end ifinfo
@tex
@cindex Reading lines with continuation lines
@end tex
@example
# get a line, combining continuation lines
#  that start with whitespace
sub get_line @{
        $thisline = $lookahead;
        line: while ($lookahead = <STDIN>) @{
                if ($lookahead =~ /^[ \t]/) @{
                        $thisline .= $lookahead;
                @}
                else @{
                        last line;
                @}
        @}
        $thisline;
@}

$lookahead = <STDIN>;   # get first line
while ($_ = do get_line()) @{
        @dots{}
@}
@end example

Use array assignment to a local list to name your formal arguments:@refill

@ifinfo
@cindex Example, subroutines and formal arguments
@cindex Subroutines and formal arguments example
@cindex Formal arguments and subroutines example
@end ifinfo
@tex
@cindex Example, subs and formal args
@cindex Subs and formal ags example
@cindex Formal args and subs example
@end tex
@example
sub maybeset @{
        local($key, $value) = @@_;
        $foo@{$key@} = $value unless $foo@{$key@};
@}
@end example

This also has the effect of turning call-by-reference into
call-by-value, since the assignment copies the values.@refill

Subroutines may be called recursively.  If a subroutine is called using
the @samp{&} form, the argument list is optional.  If omitted, no
@samp{@@_} array is set up for the subroutine; the @samp{@@_} array at
the time of the call is visible to subroutine instead.@refill

@example
do foo(1,2,3);          # pass three arguments
&foo(1,2,3);            # the same

do foo();               # pass a null list
&foo();                 # the same
&foo;                   # pass no arguments--more efficient
@end example

@node     Passing By Reference, Regular Expressions, Subroutines, Top
@comment  node-name,  next,  previous,  up
@chapter Passing By Reference
@cindex Passing By Reference

Sometimes you don't want to pass the value of an array to a subroutine
but rather the name of it, so that the subroutine can modify the global
copy of it rather than working with a local copy.  In perl you can refer
to all the objects of a particular name by prefixing the name with a
star: @samp{*foo}.  When evaluated, it produces a scalar value that
represents all the objects of that name, including any filehandle,
format or subroutine.  When assigned to within a @code{local()}
operation, it causes the name mentioned to refer to whatever @samp{*}
value was assigned to it.  Example:@refill

@example
@cindex Example, passing by reference
@cindex Passing by reference example
sub doubleary @{
    local(*someary) = @@_;
    foreach $elem (@@someary) @{
        $elem *= 2;
    @}
@}
do doubleary(*foo);
do doubleary(*bar);
@end example

Assignment to @samp{*name} is currently recommended only inside a
@code{local()}.  You can actually assign to @samp{*name} anywhere, but
the previous referent of @samp{*name} may be stranded forever.  This may
or may not bother you.@refill

Note that scalars are already passed by reference, so you can modify
scalar arguments without using this mechanism by referring explicitly to
the @samp{$_[nnn]} in question.  You can modify all the elements of an
array by passing all the elements as scalars, but you have to use the
@samp{*} mechanism to @code{push}, @code{pop} or change the size of an
array.  The @samp{*} mechanism will probably be more efficient in any
case.@refill

Since a @samp{*name} value contains unprintable binary data, if it is
used as an argument in a @code{print}, or as a @samp{%s} argument in a
@code{printf} or @code{sprintf}, it then has the value @samp{*name},
just so it prints out pretty.@refill

Even if you don't want to modify an array, this mechanism is useful for
passing multiple arrays in a single LIST, since normally the LIST
mechanism will merge all the array values so that you can't extract out
the individual arrays.@refill

@node     Regular Expressions, Formats, Passing By Reference, Top
@comment  node-name,  next,  previous,  up
@chapter Regular Expressions
@cindex Regular Expressions

The patterns used in pattern matching are regular expressions such as
those supplied in the Version 8 regexp routines.  (In fact, the routines
are derived from Henry Spencer's freely redistributable reimplementation
of the V8 routines.)  In addition, @samp{\w} matches an alphanumeric
character (including @samp{_}) and @samp{\W} a nonalphanumeric.  Word
boundaries may be matched by @samp{\b}, and non-boundaries by @samp{\B}.
A whitespace character is matched by @samp{\s}, non-whitespace by
@samp{\S}.  A numeric character is matched by @samp{\d}, non-numeric by
@samp{\D}.  You may use @samp{\w}, @samp{\s} and @samp{\d} within
character classes.  Also, @samp{\n}, @samp{\r}, @samp{\f}, @samp{\t} and
@samp{\NNN} have their normal interpretations.  Within character classes
@samp{\b} represents backspace rather than a word boundary.
Alternatives may be separated by @samp{|}.  The bracketing construct
@samp{(@dots{})} may also be used, in which case @samp{\<digit>} matches
the digit'th substring.  (Outside of the pattern, always use @samp{$}
instead of @samp{\} in front of the digit.  The scope of @samp{$<digit>}
(and @samp{$`}, @samp{$&} and @samp{$'}) extends to the end of the
enclosing BLOCK or eval string, or to the next pattern match with
subexpressions.  The @samp{\<digit>} notation sometimes works outside
the current pattern, but should not be relied upon.)  You may have as
many parentheses as you wish.  If you have more than 9 substrings, the
variables @samp{$10}, @samp{$11}, @dots{} refer to the corresponding
substring.  Within the pattern, @samp{\10}, @samp{\11}, etc. refer back
to substrings if there have been at least that many left parens before
the backreference.  Otherwise (for backward compatibilty) @samp{\10} is
the same as @samp{\010}, a backspace, and @samp{\11} the same as
@samp{\011}, a tab.  And so on.  (@samp{\1} through @samp{\9} are always
backreferences.)@refill

@samp{$+} returns whatever the last bracket match matched.  @samp{$&}
returns the entire matched string.  (@samp{$0} used to return the same
thing, but not any more.)  @samp{$`} returns everything before the
matched string.  @samp{$'} returns everything after the matched string.
Examples:@refill

@example
@cindex Examples of regular expressions
@cindex Regular expression examples
s/^([^ ]*) *([^ ]*)/$2 $1/;     # swap first two words

if (/Time: (..):(..):(..)/) @{
        $hours = $1;
        $minutes = $2;
        $seconds = $3;
@}
@end example

By default, the @samp{^} character is only guaranteed to match at the
beginning of the string, the @samp{$} character only at the end (or
before the newline at the end) and @emph{perl} does certain
optimizations with the assumption that the string contains only one
line.  The behavior of @samp{^} and @samp{$} on embedded newlines will
be inconsistent.  You may, however, wish to treat a string as a
multi-line buffer, such that the @samp{^} will match after any newline
within the string, and @samp{$} will match before any newline.  At the
cost of a little more overhead, you can do this by setting the variable
@samp{$*} to 1.  Setting it back to 0 makes @emph{perl} revert to its
old behavior.@refill

To facilitate multi-line substitutions, the @samp{.} character never
matches a newline (even when @samp{$*} is 0).  In particular, the
following leaves a newline on the @samp{$_} string:@refill

@example
$_ = <STDIN>;
s/.*(some_string).*/$1/;
@end example

If the newline is unwanted, try one of

@example
@cindex Examples of regular expressions
@cindex Regular expression examples
s/.*(some_string).*\n/$1/;
s/.*(some_string)[^\000]*/$1/;
s/.*(some_string)(.|\n)*/$1/;
chop; s/.*(some_string).*/$1/;
/(some_string)/ && ($_ = $1);
@end example

Any item of a regular expression may be followed with digits in curly
brackets of the form @samp{@{@var{n},@var{m}@}}, where @var{n} gives the
minimum number of times to match the item and @var{m} gives the maximum.
The form @samp{@{n@}} is equivalent to @samp{@{n,n@}} and matches exactly
@var{n} times.  The form @samp{@{n,@}} matches @var{n} or more times.  (If
a curly bracket occurs in any other context, it is treated as a regular
character.)  The @samp{*} modifier is equivalent to @samp{@{0,@}}, the
@samp{+} modifier to @samp{@{1,@}} and the @samp{?} modifier to
@samp{@{0,1@}}.  There is no limit to the size of @var{n} or @var{m}, but
large numbers will chew up more memory.@refill

You will note that all backslashed metacharacters in @emph{perl} are
alphanumeric, such as @samp{\b}, @samp{\w}, @samp{\n}.  Unlike some
other regular expression languages, there are no backslashed symbols
that aren't alphanumeric.  So anything that looks like @samp{\\},
@samp{\(}, @samp{\)}, @samp{\<}, @samp{\>}, @samp{\@{}, or @samp{\@}} is
always interpreted as a literal character, not a metacharacter.  This
makes it simple to quote a string that you want to use for a pattern but
that you are afraid might contain metacharacters.  Simply quote all the
non-alphanumeric characters:@refill

@example
$pattern =~ s/(\W)/\\$1/g;
@end example

@node     Formats, Interprocess Communication, Regular Expressions, Top
@comment  node-name,  next,  previous,  up
@chapter Formats
@cindex Formats

Output record formats for use with the @code{write} operator may
declared as follows:@refill

@display
@cindex Declaration of formats
@cindex Format declarations
format NAME =
FORMLIST
.
@end display

If name is omitted, format @samp{STDOUT} is defined.  @var{FORMLIST}
consists of a sequence of lines, each of which may be of one of three
types:@refill

@enumerate
@item
A comment.
@item
A ``picture'' line giving the format for one output line.
@item
An argument line supplying values to plug into a picture line.
@end enumerate

Picture lines are printed exactly as they look, except for certain
fields that substitute values into the line.  Each picture field starts
with either @samp{@@} or @samp{^}.  The @samp{@@} field (not to be
confused with the array marker @samp{@@}) is the normal case; @samp{^}
fields are used to do rudimentary multi-line text block filling.  The
length of the field is supplied by padding out the field with multiple
@samp{<}, @samp{>}, or @samp{|} characters to specify, respectively,
left justification, right justification, or centering.  As an alternate
form of right justification, you may also use @samp{#} characters (with
an optional @samp{.}) to specify a numeric field.  (Use of @samp{^}
instead of @samp{@@} causes the field to be blanked if undefined.)  If
any of the values supplied for these fields contains a newline, only the
text up to the newline is printed.  The special field @samp{@@*} can be
used for printing multi-line values.  It should appear by itself on a
line.@refill

The values are specified on the following line, in the same order as the
picture fields.  The values should be separated by commas.@refill

Picture fields that begin with @samp{^} rather than @samp{@@} are
treated specially.  The value supplied must be a scalar variable name
which contains a text string.  @emph{Perl} puts as much text as it can
into the field, and then chops off the front of the string so that the
next time the variable is referenced, more of the text can be printed.
Normally you would use a sequence of fields in a vertical stack to print
out a block of text.  If you like, you can end the final field with
@samp{@dots{}}, which will appear in the output if the text was too long
to appear in its entirety.  You can change which characters are legal to
break on by changing the variable @samp{$:} to a list of the desired
characters.@refill

Since use of @samp{^} fields can produce variable length records if the
text to be formatted is short, you can suppress blank lines by putting
the tilde (@samp{~}) character anywhere in the line.  (Normally you
should put it in the front if possible, for visibility.)  The tilde will
be translated to a space upon output.  If you put a second tilde
contiguous to the first, the line will be repeated until all the fields
on the line are exhausted.  (If you use a field of the @samp{@@}
variety, the expression you supply had better not give the same value
every time forever!)@refill

Examples:

@cindex Examples of formats/reports
@cindex Format/report examples
@cindex Report/format examples
@ifinfo
@cindex Example of a report of the @file{/etc/passwd} file
@cindex Example of a format for the @file{/etc/passwd} file
@end ifinfo
@cindex Example, @file{/etc/passwd} file report
@cindex Report for the @file{/etc/passwd} file, A
@cindex Format for the @file{/etc/passwd} file, A
@cindex Format example, @file{/etc/passwd} file
@example
# a report on the /etc/passwd file
format top =
                        Passwd File
Name                Login    Office   Uid   Gid Home
------------------------------------------------------------------
.
format STDOUT =
@@<<<<<<<<<<<<<<<<<< @@||||||| @@<<<<<<@@>>>> @@>>>> @@<<<<<<<<<<<<<<<<<
$name,              $login,  $office,$uid,$gid, $home
.

@cindex Example of a bug report format
@cindex Bug report format example
@cindex Format example, bug report
# a report from a bug report form
format top =
                        Bug Reports
@@<<<<<<<<<<<<<<<<<<<<<<<     @@|||         @@>>>>>>>>>>>>>>>>>>>>>>>
$system,                      $%,         $date
------------------------------------------------------------------
.
format STDOUT =
Subject: @@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
         $subject
Index: @@<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
       $index,                       $description
Priority: @@<<<<<<<<<< Date: @@<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
          $priority,        $date,   $description
From: @@<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
      $from,                         $description
Assigned to: @@<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
             $programmer,            $description
~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                     $description
~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                     $description
~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                     $description
~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                     $description
~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
                                     $description
.
@end example

It is possible to intermix @code{print}s with @code{write}s on the same output
channel, but you'll have to handle @samp{$-} (lines left on the page)
yourself.@refill

If you are printing lots of fields that are usually blank, you should
consider using the reset operator between records.  Not only is it more
efficient, but it can prevent the bug of adding another field and
forgetting to zero it.@refill

@node     Interprocess Communication, Predefined Names, Formats, Top
@comment  node-name,  next,  previous,  up
@chapter Interprocess Communication
@cindex Interprocess Communication
@cindex IPC (Interprocess Communication)

The IPC facilities of perl are built on the Berkeley socket mechanism.
If you don't have sockets, you can ignore this section.  The calls have
the same names as the corresponding system calls, but the arguments tend
to differ, for two reasons.  First, perl file handles work differently
than C file descriptors.  Second, perl already knows the length of its
strings, so you don't need to pass that information.  Here is a sample
client (untested):@refill

@ifinfo
@cindex Example, Interprocess Communication
@cindex Interprocess Communication example
@cindex Example of a client, Interprocess Communication
@cindex Interprocess Communication client example
@cindex Client example, Interprocess Communication
@end ifinfo
@cindex Example, IPC
@cindex IPC example
@cindex Example of an IPC client
@cindex IPC client example
@cindex Client example, IPC
@example
($them,$port) = @@ARGV;
$port = 2345 unless $port;
$them = 'localhost' unless $them;

$SIG@{'INT'@} = 'dokill';
sub dokill @{ kill 9,$child if $child; @}

require 'sys/socket.ph';

$sockaddr = 'S n a4 x8';
chop($hostname = `hostname`);

($name, $aliases, $proto) = getprotobyname('tcp');
($name, $aliases, $port) = getservbyname($port, 'tcp')
        unless $port =~ /^\d+$/;
($name, $aliases, $type, $len, $thisaddr) =
                                gethostbyname($hostname);
($name, $aliases, $type, $len, $thataddr) = gethostbyname($them);

$this = pack($sockaddr, &AF_INET, 0, $thisaddr);
$that = pack($sockaddr, &AF_INET, $port, $thataddr);

socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
bind(S, $this) || die "bind: $!";
connect(S, $that) || die "connect: $!";

select(S); $| = 1; select(stdout);

if ($child = fork) @{
        while (<>) @{
                print S;
        @}
        sleep 3;
        do dokill();
@}
else @{
        while (<S>) @{
                print;
        @}
@}
@end example

And here's a server:

@ifinfo
@cindex Example, Interprocess Communication
@cindex Interprocess Communication example
@cindex Example of a server, Interprocess Communication
@cindex Interprocess Communication server example
@cindex Server example, Interprocess Communication
@end ifinfo
@cindex Example, IPC
@cindex IPC example
@cindex Example of an IPC server
@cindex IPC server example
@cindex Server example, IPC
@example
($port) = @@ARGV;
$port = 2345 unless $port;

require 'sys/socket.ph';

$sockaddr = 'S n a4 x8';

($name, $aliases, $proto) = getprotobyname('tcp');
($name, $aliases, $port) = getservbyname($port, 'tcp')
        unless $port =~ /^\d+$/;

$this = pack($sockaddr, &AF_INET, $port, "\0\0\0\0");

select(NS); $| = 1; select(stdout);

socket(S, &PF_INET, &SOCK_STREAM, $proto) || die "socket: $!";
bind(S, $this) || die "bind: $!";
listen(S, 5) || die "connect: $!";

select(S); $| = 1; select(stdout);

for (;;) @{
        print "Listening again\n";
        ($addr = accept(NS,S)) || die $!;
        print "accept ok\n";

        ($af,$port,$inetaddr) = unpack($sockaddr,$addr);
        @@inetaddr = unpack('C4',$inetaddr);
        print "$af $port @@inetaddr\n";

        while (<NS>) @{
                print;
                print NS;
        @}
@}
@end example

@node     Predefined Names, Packages, Interprocess Communication, Top
@comment  node-name,  next,  previous,  up
@chapter Predefined Names
@cindex Predefined Names
@cindex Predefined variables
@cindex Variables, predefined
@cindex Names, predefined

The following names have special meaning to @emph{perl}.  I could have
used alphabetic symbols for some of these, but I didn't want to take the
chance that someone would say @samp{reset "a-zA-Z"} and wipe them all
out.  You'll just have to suffer along with these silly symbols.  Most
of them have reasonable mnemonics, or analogues in one of the
shells.@refill

@table @asis
@item $_
The default input and pattern-searching space.  The following pairs are
more or less equivalent:@refill

@example
@cindex Example of @samp{$_}
@cindex @samp{$_} examples
while (<>) @{@dots{}    # only equivalent in while!
while ($_ = <>) @{@dots{}

/^Subject:/
$_ =~ /^Subject:/

y/a-z/A-Z/
$_ =~ y/a-z/A-Z/

chop
chop($_)
@end example

(Mnemonic: underline is understood in certain operations.)

@item $.
The current input line number of the last filehandle that was read.
Readonly.  Remember that only an explicit close on the filehandle resets
the line number.  Since @samp{<>} never does an explicit close, line
numbers increase across @samp{ARGV} files (but see examples under
@code{eof}).  (Mnemonic: many programs use @samp{.} to mean the current
line number.)@refill

@item $/
The input record separator, newline by default.  Works like @code{awk}'s
RS variable, including treating blank lines as delimiters if set to the
null string.  You may set it to a multicharacter string to match a
multi-character delimiter.  (Mnemonic: @samp{/} is used to delimit line
boundaries when quoting poetry.)@refill

@item $,
The output field separator for the @code{print} operator.  Ordinarily the
@code{print} operator simply prints out the comma separated fields you
specify.  In order to get behavior more like @code{awk}, set this variable
as you would set @code{awk}'s OFS variable to specify what is printed
between fields.  (Mnemonic: what is printed when there is a @samp{,} in
your print statement.)@refill

@item $"
This is like @samp{$,} except that it applies to array values
interpolated into a double-quoted string (or similar interpreted
string).  Default is a space.  (Mnemonic: obvious, I think.)@refill

@item $\
The output record separator for the @code{print} operator.  Ordinarily the
@code{print} operator simply prints out the comma separated fields you specify,
with no trailing newline or record separator assumed.  In order to get
behavior more like @code{awk}, set this variable as you would set
@code{awk}'s ORS variable to specify what is printed at the end of the
print.  (Mnemonic: you set @samp{$\} instead of adding @samp{\n} at the
end of the print.  Also, it's just like @samp{/}, but it's what you get
``back'' from @emph{perl}.)@refill

@item $#
The output format for printed numbers.  This variable is a half-hearted
attempt to emulate @code{awk}'s OFMT variable.  There are times,
however, when @code{awk} and @emph{perl} have differing notions of what
is in fact numeric.  Also, the initial value is @samp{%.20g} rather than
@samp{%.6g}, so you need to set @samp{$#} explicitly to get @code{awk}'s
value.  (Mnemonic: @samp{#} is the number sign.)

@item $%
The current page number of the currently selected output channel.
(Mnemonic: @samp{%} is page number in nroff.)@refill

@item $=
The current page length (printable lines) of the currently selected
output channel.  Default is 60.  (Mnemonic: @samp{=} has horizontal
lines.)@refill

@item $-
The number of lines left on the page of the currently selected output
channel.  (Mnemonic: lines_on_page @minus{} lines_printed.)@refill

@item $~
The name of the current report format for the currently selected output
channel.  (Mnemonic: brother to @samp{$^}.)@refill

@item $^
The name of the current top-of-page format for the currently selected
output channel.  (Mnemonic: points to top of page.)@refill

@item $|
If set to nonzero, forces a flush after every @code{write} or @code{print}
on the currently selected output channel.  Default is 0.  Note that
@samp{STDOUT} will typically be line buffered if output is to the terminal
and block buffered otherwise.  Setting this variable is useful primarily
when you are outputting to a pipe, such as when you are running a
@emph{perl} script under rsh and want to see the output as it's happening.
(Mnemonic: when you want your pipes to be piping hot.)@refill

@item $$
The process number of the @emph{perl} running this script.  (Mnemonic:
same as shells.)@refill

@item $?
The status returned by the last pipe close, backtick (@`@`) command or
@code{system} operator.  Note that this is the status word returned by
the @code{wait()} system call, so the exit value of the subprocess is
actually @samp{($? >> 8)}.  @samp{$? & 255} gives which signal, if any,
the process died from, and whether there was a core dump.  (Mnemonic:
similar to @code{sh} and @code{ksh}.)@refill

@item $&
The string matched by the last pattern match (not counting any matches
hidden within a BLOCK or @code{eval} enclosed by the current BLOCK).
(Mnemonic: like @samp{&} in some editors.)@refill

@item $`
The string preceding whatever was matched by the last pattern match (not
counting any matches hidden within a BLOCK or @code{eval} enclosed by
the current BLOCK).  (Mnemonic: @` often precedes a quoted
string.)@refill

@item $'
The string following whatever was matched by the last pattern match (not
counting any matches hidden within a BLOCK or @code{eval} enclosed by
the current BLOCK).  (Mnemonic: @' often follows a quoted string.)
Example:@refill

@example
@cindex Example of @samp{$`} predefined variable
@cindex @samp{$`} predefined variable example
@cindex Example of @samp{$&} predefined variable
@cindex @samp{$&} predefined variable example
@cindex Example of @samp{$'} predefined variable
@cindex @samp{$'} predefined variable example
$_ = 'abcdefghi';
/def/;
print "$`:$&:$'\n";     # prints abc:def:ghi
@end example

@item $+
The last bracket matched by the last search pattern.  This is useful if
you don't know which of a set of alternative patterns matched.  For
example:@refill

@example
@cindex Example of @samp{$+} predefined variable
@cindex @samp{$+} predefined variable example
/Version: (.*)|Revision: (.*)/ && ($rev = $+);
@end example

(Mnemonic: be positive and forward looking.)

@item $*
Set to 1 to do multiline matching within a string, 0 to tell @emph{perl}
that it can assume that strings contain a single line, for the purpose
of optimizing pattern matches.  Pattern matches on strings containing
multiple newlines can produce confusing results when @samp{$*} is 0.
Default is 0.  Note that this variable only influences the
interpretation of @samp{^} and @samp{$}.  A literal newline can be
searched for even when @samp{$* == 0}.  (Mnemonic: @samp{*} matches
multiple things.)@refill

@item $0
Contains the name of the file containing the @emph{perl} script being
executed.  Assigning to @samp{$0} modifies the argument area that the
@code{ps(1)} program sees.  (Mnemonic: same as @code{sh} and
@code{ksh}.)@refill

@item $<digit>
Contains the subpattern from the corresponding set of parentheses in the
last pattern matched, not counting patterns matched in nested blocks
that have been exited already.  (Mnemonic: like @samp{\digit}.)@refill

@item $[
The index of the first element in an array, and of the first character
in a substring.  Default is 0, but you could set it to 1 to make
@emph{perl} behave more like @code{awk} (or Fortran) when subscripting
and when evaluating the @code{index()} and @code{substr()} functions.
(Mnemonic: @samp{[} begins subscripts.)@refill

@item $]
The string printed out when you say @samp{perl -v}.  It can be used to
determine at the beginning of a script whether the perl interpreter
executing the script is in the right range of versions.  If used in a
numeric context, returns the version + patchlevel / 1000.
Example:@refill

@example
@cindex Example of @samp{$]} predefined variable
@cindex @samp{$]} predefined variable example
# see if getc is available
($version,$patchlevel) =
         $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/;
print STDERR "(No filename completion available.)\n"
         if $version * 1000 + $patchlevel < 2016;
@end example

or, used numerically,

@example
warn "No checksumming!\n" if $] < 3.019;
@end example

(Mnemonic: Is this version of perl in the right bracket?)

@item $;
The subscript separator for multi-dimensional array emulation.
If you refer to an associative array element as@refill

@example
$foo@{$a,$b,$c@}
@end example

it really means

@example
$foo@{join($;, $a, $b, $c)@}
@end example

But don't put

@example
@@foo@{$a,$b,$c@}           # a slice--note the @@
@end example

which means

@example
($foo@{$a@},$foo@{$b@},$foo@{$c@})
@end example

Default is @samp{\034}, the same as SUBSEP in @code{awk}.  Note that if
your keys contain binary data there might not be any safe value for
@samp{$;}.  (Mnemonic: comma (the syntactic subscript separator) is a
semi-semicolon.  Yeah, I know, it's pretty lame, but @samp{$,} is
already taken for something more important.)@refill

@item $!
If used in a numeric context, yields the current value of errno, with all
the usual caveats.  (This means that you shouldn't depend on the value of
@samp{$!} to be anything in particular unless you've gotten a specific
error return indicating a system error.)  If used in a string context,
yields the corresponding system error string.  You can assign to @samp{$!}
in order to set errno if, for instance, you want @samp{$!} to return the
string for error @var{n}, or you want to set the exit value for the
@code{die} operator.  (Mnemonic: What just went bang?)@refill

@item $@@
The perl syntax error message from the last @code{eval} command.  If null,
the last @code{eval} parsed and executed correctly (although the
operations you invoked may have failed in the normal fashion).  (Mnemonic:
Where was the syntax error ``at''?)@refill

@item $<
The real uid of this process.  (Mnemonic: it's the uid you came
@strong{FROM}, if you're running setuid.)@refill

@item $>
The effective uid of this process.  Example:@refill

@example
@cindex Example of @samp{$<} predefined variable
@cindex @samp{$<} predefined variable example
@cindex Example of @samp{$>} predefined variable
@cindex @samp{$>} predefined variable example
@cindex Example of swapping real/effective uid
@cindex Swapping real/effective uid example
$< = $>;              # set real uid to the effective uid
($<,$>) = ($>,$<);    # swap real and effective uid
@end example

(Mnemonic: it's the uid you went @strong{TO}, if you're running setuid.)
Note: @samp{$<} and @samp{$>} can only be swapped on machines supporting
@code{setreuid()}.@refill

@item $(
The real gid of this process.  If you are on a machine that supports
membership in multiple groups simultaneously, gives a space separated list
of groups you are in.  The first number is the one returned by
@code{getgid()}, and the subsequent ones by @code{getgroups()}, one of
which may be the same as the first number.  (Mnemonic: parentheses are
used to @strong{GROUP} things.  The real gid is the group you
@strong{LEFT}, if you're running setgid.)@refill

@item $)
The effective gid of this process.  If you are on a machine that supports
membership in multiple groups simultaneously, gives a space separated list
of groups you are in.  The first number is the one returned by
@code{getegid()}, and the subsequent ones by @code{getgroups()}, one of
which may be the same as the first number.  (Mnemonic: parentheses are
used to @strong{GROUP} things.  The effective gid is the group that's
@strong{RIGHT} for you, if you're running setgid.)@refill

Note: @samp{$<}, @samp{$>}, @samp{$(} and @samp{$)} can only be set on
machines that support the corresponding @code{set[re][ug]id()} routine.
@samp{$(} and @samp{$)} can only be swapped on machines supporting
@code{setregid()}.@refill

@item $:
The current set of characters after which a string may be broken to fill
continuation fields (starting with @samp{^}) in a format.  Default is
@samp{ \n-}, to break on whitespace or hyphens.  (Mnemonic: a ``colon''
in poetry is a part of a line.)@refill

@item $^D
The current value of the debugging flags.  (Mnemonic: value of @samp{-D}
switch.)@refill

@item $^I
The current value of the inplace-edit extension.  Use @code{undef} to
disable inplace editing.  (Mnemonic: value of @samp{-i} switch.)@refill

@item $^P
The name that Perl itself was invoked as, from argv[0].

@item $^T
The time at which the script began running, in seconds since the epoch.
The values returned by the @samp{-M}, @samp{-A}, and @samp{-C} filetests
are based on this value.@refill

@item $^W
The current value of the warning switch.  (Mnemonic: related to the
@samp{-w} switch.)

@item $ARGV
The scalar variable @samp{$ARGV} contains the name of the current file
when reading from @samp{<>}.@refill

@item @@ARGV
The array @samp{ARGV} contains the command line arguments intended for the
script.  Note that @samp{$#ARGV} is the generally number of arguments
minus one, since @samp{$ARGV[0]} is the first argument, @strong{NOT} the
command name.  See @samp{$0} for the command name.@refill

@item @@INC
The array @samp{INC} contains the list of places to look for @emph{perl}
scripts to be evaluated by the @code{do EXPR} command or the
@code{require} command.  It initially consists of the arguments to any
@samp{-I} command line switches, followed by the default @emph{perl}
library, probably @file{/usr/local/lib/perl}, followed by @samp{.}, to
represent the current directory.@refill

@item %INC
The associative array @samp{INC} contains entries for each filename that
has been included via @code{do} or @code{require}.  The key is the
filename you specified, and the value is the location of the file
actually found.  The @code{require} command uses this array to determine
whether a given file has already been included.@refill

@item $ENV@{expr@}
The associative array @samp{ENV} contains your current environment.
Setting a value in @samp{ENV} changes the environment for child
processes.@refill

@item $SIG@{expr@}
The associative array @samp{SIG} is used to set signal handlers for
various signals.  Example:@refill

@example
@cindex Example of @samp{@@SIG} predefined variable
@cindex @samp{@@SIG} predefined variable example
@cindex Example of a signal handler
@cindex Signal handler example
@cindex Signals, predefined variable for
sub handler @{  # 1st argument is signal name
        local($sig) = @@_;
        print "Caught a SIG$sig--shutting down\n";
        close(LOG);
        exit(0);
@}

$SIG@{'INT'@} = 'handler';
$SIG@{'QUIT'@} = 'handler';
@dots{}
$SIG@{'INT'@} = 'DEFAULT';      # restore default action
$SIG@{'QUIT'@} = 'IGNORE';      # ignore SIGQUIT
@end example

The @samp{SIG} array only contains values for the signals actually set
within the perl script.@refill
@end table

@node     Packages, Style, Predefined Names, Top
@comment  node-name,  next,  previous,  up
@chapter Packages
@cindex Packages

Perl provides a mechanism for alternate namespaces to protect packages
from stomping on each others variables.  By default, a perl script
starts compiling into the package known as @samp{main}.  By use of the
@code{package} declaration, you can switch namespaces.  The scope of the
@code{package} declaration is from the declaration itself to the end of the
enclosing block (the same scope as the @code{local()} operator).
Typically it would be the first declaration in a file to be included by
the @code{require} operator.  You can switch into a package in more than
one place; it merely influences which symbol table is used by the
compiler for the rest of that block.  You can refer to variables and
filehandles in other packages by prefixing the identifier with the
package name and a single quote.  If the package name is null, the
@samp{main} package as assumed.@refill

Only identifiers starting with letters are stored in the packages symbol
table.  All other symbols are kept in package @samp{main}.  In addition,
the identifiers @samp{STDIN}, @samp{STDOUT}, @samp{STDERR}, @samp{ARGV},
@samp{ARGVOUT}, @samp{ENV}, @samp{INC} and @samp{SIG} are forced to be
in package @samp{main}, even when used for other purposes than their
built-in one.  Note also that, if you have a package called @samp{m},
@samp{s} or @samp{y}, the you can't use the qualified form of an
identifier since it will be interpreted instead as a pattern match, a
substitution or a translation.@refill

@code{eval}'ed strings are compiled in the package in which the
@code{eval} was compiled in.  (Assignments to @samp{$SIG@{@}}, however,
assume the signal handler specified is in the @samp{main} package.
Qualify the signal handler name if you wish to have a signal handler in a
package.)  For an example, examine @file{perldb.pl} in the perl library.
It initially switches to the @samp{DB} package so that the debugger
doesn't interfere with variables in the script you are trying to debug.
At various points, however, it temporarily switches back to the @samp{main}
package to evaluate various expressions in the context of the @samp{main}
package.@refill

The symbol table for a package happens to be stored in the associative
array of that name prepended with an underscore.  The value in each
entry of the associative array is what you are referring to when you use
the @samp{*name} notation.  In fact, the following have the same effect
(in package @samp{main}, anyway), though the first is more efficient
because it does the symbol table lookups at compile time:@refill

@example
local(*foo) = *bar;
local($_main@{'foo'@}) = $_main@{'bar'@};
@end example

You can use this to print out all the variables in a package, for
instance.  Here is @file{dumpvar.pl} from the perl library:@refill

@example
@cindex @file{dumpvar.pl} file
@cindex Example of a package, dumpvar
@cindex dumpvar package
package dumpvar;

sub main'dumpvar @{
    ($package) = @@_;
    local(*stab) = eval("*_$package");
    while (($key,$val) = each(%stab)) @{
        @{
            local(*entry) = $val;
            if (defined $entry) @{
                print "\$$key = '$entry'\n";
            @}
            if (defined @@entry) @{
                print "\@@$key = (\n";
                foreach $num ($[ .. $#entry) @{
                    print "  $num\t'",$entry[$num],"'\n";
                @}
                print ")\n";
            @}
            if ($key ne "_$package" && defined %entry) @{
                print "\%$key = (\n";
                foreach $key (sort keys(%entry)) @{
                    print "  $key\t'",$entry@{$key@},"'\n";
                @}
                print ")\n";
            @}
        @}
    @}
@}
@end example

Note that, even though the subroutine is compiled in package
@samp{dumpvar}, the name of the subroutine is qualified so that its name
is inserted into package @samp{main}.@refill

@node     Style, Debugging, Packages, Top
@comment  node-name,  next,  previous,  up
@chapter Style
@cindex Style

Each programmer will, of course, have his or her own preferences in regards
to formatting, but there are some general guidelines that will make your
programs easier to read.@refill

@enumerate
@item
Just because you @strong{CAN} do something a particular way doesn't mean
that you @strong{SHOULD} do it that way.  @emph{Perl} is designed to give
you several ways to do anything, so consider picking the most readable
one.  For instance@refill

@example
open(FOO,$foo) || die "Can't open $foo: $!";
@end example

is better than

@example
die "Can't open $foo: $!" unless open(FOO,$foo);
@end example

because the second way hides the main point of the statement in a modifier.
On the other hand@refill

@example
print "Starting analysis\n" if $verbose;
@end example

is better than

@example
$verbose && print "Starting analysis\n";
@end example

since the main point isn't whether the user typed @samp{-v} or not.@refill

Similarly, just because an operator lets you assume default arguments
doesn't mean that you have to make use of the defaults.  The defaults are
there for lazy systems programmers writing one-shot programs.  If you want
your program to be readable, consider supplying the argument.@refill

Along the same lines, just because you @strong{can} omit parentheses in many
places doesn't mean that you ought to:@refill

@example
return print reverse sort num values array;
return print(reverse(sort num (values(%array))));
@end example

When in doubt, parenthesize.  At the very least it will let some poor
schmuck bounce on the @kbd{%} key in @emph{vi}.@refill

Even if you aren't in doubt, consider the mental welfare of the person
who has to maintain the code after you, and who will probably put parens
in the wrong place.@refill

@item
Don't go through silly contortions to exit a loop at the top or the bottom,
when @emph{perl} provides the @code{last} operator so you can exit in the
middle.  Just outdent it a little to make it more visible:@refill

@example
line:
    for (;;) @{
        statements;
    last line if $foo;
        next line if /^#/;
        statements;
    @}
@end example

@item
Don't be afraid to use loop labels---they're there to enhance readability
as well as to allow multi-level loop breaks.  See last example.@refill

@item
For portability, when using features that may not be implemented on every
machine, test the construct in an @code{eval} to see if it fails.  If you
know what version or patchlevel a particular feature was implemented, you
can test @samp{$]} to see if it will be there.@refill

@item
Choose mnemonic identifiers.

@item
Be consistent.
@end enumerate

@node     Debugging, Setuid Scripts, Style, Top
@comment  node-name,  next,  previous,  up
@chapter Debugging
@cindex Debugging

If you invoke @emph{perl} with a @samp{-d} switch, your script will be run
under a debugging monitor.  It will halt before the first executable
statement and ask you for a command, such as:@refill

@table @samp
@item h
Prints out a help message.
@item T
Stack trace.
@item s
Single step.  Executes until it reaches the beginning of another
statement.@refill
@item n
Next.  Executes over subroutine calls, until it reaches the beginning of
the next statement.
@item f
Finish.  Executes statements until it has finished the current subroutine.
@item c
Continue.  Executes until the next breakpoint is reached.@refill
@item c @var{line}
Continue to the specified line.  Inserts a one-time-only breakpoint at
the specified line.
@c @@@@ does "c line" work with sub names?? maybe implement, if not? @@@@
@item <CR>
Repeat last @kbd{n} or @kbd{s}.
@item n
Single step around subroutine call.
@item l @var{min}+@var{incr}
List @samp{@var{incr}+1} lines starting at @var{min}.  If @var{min} is
omitted, starts where last listing left off.  If @var{incr} is omitted,
previous value of @var{incr} is used.@refill
@item l @var{min}-@var{max}
List lines in the indicated range.
@item l @var{line}
List just the indicated line.
@item l
List next window.
@item -
List previous window.
@item w @var{line}
List window around @var{line}
@item l @var{subname}
List subroutine.  If it's a long subroutine it just lists the beginning.
Use @kbd{l} to list more.@refill
@item /@var{pattern}/
Regular expression search forward for @var{pattern}; the final @samp{/}
is optional.@refill
@item ?@var{pattern}?
Regular expression search backward for @var{pattern}; the final
@samp{?} is optional.@refill
@item L
List lines that have breakpoints or actions.
@item S
Lists the names of all subroutines.
@item t
Toggle trace mode on or off.
@item b @var{line} @var{condition}
Set a breakpoint.  If @var{line} is omitted, sets a breakpoint on the
line that is about to be executed.  If a @var{condition} is specified,
it is evaluated each time the statement is reached and a breakpoint is
taken only if the condition is true.  Breakpoints may only be set on
lines that begin an executable statement.@refill
@item b @var{subname} @var{condition}
Set breakpoint at first executable line of subroutine.@refill
@item d @var{line}
Delete breakpoint.  If @var{line} is omitted, deletes the breakpoint on the
line that is about to be executed.@refill
@item D
Delete all breakpoints.
@item a @var{line} @var{command}
Set an action for @var{line}.  A multi-line @var{command} may be entered by
backslashing the newlines.@refill
@item A
Delete all line actions.
@item < @var{command}
Set an action to happen before every debugger prompt.  A multi-line command
may be entered by backslashing the newlines.@refill
@item > @var{command}
Set an action to happen after the prompt when you've just given a command
to return to executing the script.  A multi-line command may be entered by
backslashing the newlines.@refill
@item V @var{package}
List all variables in @var{package}.  Default is @samp{main}
package.@refill
@item ! @var{number}
Redo a debugging command.  If @var{number} is omitted, redoes the previous
command.@refill
@item ! -@var{number}
Redo the command that was that many (@var{number}) commands ago.@refill
@comment @@@@ SHOULD delete "that many" above @@@@
@item H -@var{number}
Display last @var{number} commands.  Only commands longer than one
character are listed.  If @var{number} is omitted, lists them all.@refill
@item q
@itemx @ctrl{D}
Quit.
@item @var{command}
Execute @var{command} as a perl statement.  A missing semicolon will be
supplied.@refill
@item p @var{expr}
Same as @code{print DB'OUT expr}.  The @samp{DB'OUT} filehandle is opened
to @file{/dev/tty}, regardless of where @samp{STDOUT} may be redirected
to.@refill
@end table

If you want to modify the debugger, copy @file{perldb.pl} from the perl
library to your current directory and modify it as necessary.  (You'll
also have to put @samp{-I.} on your command line.)  You can do some
customization by setting up a @file{.perldb} file which contains
initialization code.  For instance, you could make aliases like
these:@refill

@example
@cindex Example of debugger aliases
@cindex Debugger aliases
@cindex Setting up aliases in the debugger
@cindex perldb aliases
@cindex Aliases in the debugger
$DB'alias@{'len'@} = 's/^len(.*)/p length($1)/';
$DB'alias@{'stop'@} = 's/^stop (at|in)/b/';
$DB'alias@{'.'@} =
  's/^\./p "\$DB\'sub(\$DB\'line):\t",\$DB\'line[\$DB\'line]/';
@end example

@node     Setuid Scripts, Environment, Debugging, Top
@comment  node-name,  next,  previous,  up
@chapter Setuid Scripts
@cindex Setuid Scripts
@cindex Scripts, Setuid

@emph{Perl} is designed to make it easy to write secure setuid and setgid
scripts.  Unlike shells, which are based on multiple substitution passes on
each line of the script, @emph{perl} uses a more conventional evaluation
scheme with fewer hidden ``gotchas''.  Additionally, since the language has
more built-in functionality, it has to rely less upon external (and
possibly untrustworthy) programs to accomplish its purposes.@refill

In an unpatched 4.2 or 4.3bsd kernel, setuid scripts are intrinsically
insecure, but this kernel feature can be disabled.  If it is, @emph{perl}
can emulate the setuid and setgid mechanism when it notices the otherwise
useless setuid/gid bits on perl scripts.  If the kernel feature isn't
disabled, @emph{perl} will complain loudly that your setuid script is
insecure.  You'll need to either disable the kernel setuid script feature,
or put a C wrapper around the script.@refill

@cindex Tainted variables
@cindex Variables, tainted
When perl is executing a setuid script, it takes special precautions to
prevent you from falling into any obvious traps.  (In some ways, a perl
script is more secure than the corresponding C program.)  Any
@emph{command line argument}, @emph{environment variable}, or
@emph{input} is marked as @dfn{tainted}, and may not be used, directly
or indirectly, in any command that invokes a subshell, or in any command
that modifies files, directories or processes.  Any variable that is set
within an expression that has previously referenced a tainted value also
becomes tainted (even if it is logically impossible for the tainted
value to influence the variable).  For example:@refill

@example
@cindex Examples of tainted variables
@cindex Tainted variable examples
@comment @@@@ PUT INDEX entries here for Concept Index @@@@
$foo = shift;                   # $foo is tainted
$bar = $foo,'bar';              # $bar is also tainted
$xxx = <>;                      # Tainted
$path = $ENV@{'PATH'@};           # Tainted, but see below
$abc = 'abc';                   # Not tainted

system "echo $foo";             # Insecure
system "/bin/echo", $foo;       # Secure (doesn't use sh)
system "echo $bar";             # Insecure
system "echo $abc";             # Insecure until PATH set

$ENV@{'PATH'@} = '/bin:/usr/bin';
$ENV@{'IFS'@} = @'@' if $ENV@{'IFS'@} ne @'@';

$path = $ENV@{'PATH'@};           # Not tainted
system "echo $abc";             # Is secure now!

open(FOO,"$foo");               # OK
open(FOO,">$foo");              # Not OK

open(FOO,"echo $foo|");                 # Not OK, but...
open(FOO,"-|") || exec 'echo', $foo;    # OK

$zzz = `echo $foo`;             # Insecure, zzz tainted

unlink $abc,$foo;               # Insecure
umask $foo;                     # Insecure

exec "echo $foo";               # Insecure
exec "echo", $foo;              # Secure (doesn't use sh)
exec "sh", '-c', $foo;          # Considered secure, alas
@end example

The taintedness is associated with each scalar value, so some elements of
an array can be tainted, and others not.@refill

If you try to do something insecure, you will get a fatal error saying
something like ``Insecure dependency'' or ``Insecure PATH''.  Note that you
can still write an insecure system call or @code{exec}, but only by
explicitly doing something like the last example above.  You can also
bypass the tainting mechanism by referencing subpatterns---@emph{perl}
presumes that if you reference a substring using @samp{$1}, @samp{$2}, etc,
you knew what you were doing when you wrote the pattern:@refill

@example
$ARGV[0] =~ /^-P(\w+)$/;
$printer = $1;          # Not tainted
@end example

This is fairly secure since @samp{\w+} doesn't match shell metacharacters.
Use of @samp{.+} would have been insecure, but @emph{perl} doesn't check
for that, so you must be careful with your patterns.  This is the
@strong{ONLY} mechanism for untainting user supplied filenames if you want
to do file operations on them (unless you make @samp{$>} equal to
@samp{$<}).@refill

It's also possible to get into trouble with other operations that don't
care whether they use tainted values.  Make judicious use of the file tests
in dealing with any user-supplied filenames.  When possible, do opens and
such after setting @samp{$> = $<}.  @emph{Perl} doesn't prevent you from
opening tainted filenames for reading, so be careful what you print out.
The tainting mechanism is intended to prevent stupid mistakes, not to
remove the need for thought.@refill

@node     Environment, a2p, Setuid Scripts, Top
@comment  node-name,  next,  previous,  up
@chapter Environment
@cindex Environment

@emph{Perl} uses @samp{PATH} in executing subprocesses, and in finding the
script if @samp{-S} is used.  @samp{HOME} or @samp{LOGDIR} are used if
@code{chdir} has no argument.@refill

Apart from these, @emph{perl} uses no environment variables, except to make
them available to the script being executed, and to child processes.
However, scripts running setuid would do well to execute the following
lines before doing anything else, just to keep people honest:@refill

@example
$ENV@{'PATH'@} = '/bin:/usr/bin';    # or whatever you need
$ENV@{'SHELL'@} = '/bin/sh' if $ENV@{'SHELL'@} ne @'@';
$ENV@{'IFS'@} = @'@' if $ENV@{'IFS'@} ne @'@';
@end example

@section Files
@cindex Files

The only file that @emph{perl} creates, other than user specified files,
is:@refill

@example
/tmp/perl-eXXXXXX       temporary file for @samp{-e} commands.
@end example

@node     a2p, s2p, Environment, Top
@comment  node-name,  next,  previous,  up
@chapter a2p - Awk to Perl Translator
@cindex a2p (awk to perl translator)
@cindex Awk to Perl translator
@cindex Converting awk scripts into perl

@emph{A2p} takes an @code{awk} script specified on the command line (or
from standard input) and produces a comparable @emph{perl} script on the
standard output.

@menu
* a2p Options::         Options to a2p.
* a2p Considerations::  Considerations when using a2p.
* a2p Bugs::            Problems with a2p.
@end menu

@node     a2p Options, a2p Considerations, , a2p
@comment  node-name,  next,  previous,  up
@section Options for a2p
@cindex Options for a2p
@cindex a2p options

@noindent
Options include:

@table @samp
@item -D<number>
sets debugging flags.

@item -F<character>
tells @emph{a2p} that this @code{awk} script is always invoked with this
@samp{-F} switch.@refill

@item -n<fieldlist>
specifies the names of the input fields if input does not have to be
split into an array.  If you were translating an @code{awk} script that
processes the password file, you might say:@refill

@example
a2p -7 -nlogin.password.uid.gid.gcos.shell.home
@end example

Any delimiter can be used to separate the field names.

@item -<number>
causes @emph{a2p} to assume that input will always have that many
fields.@refill
@end table

@node     a2p Considerations, a2p Bugs, a2p Options, a2p
@comment  node-name,  next,  previous,  up
@section Considerations for Using a2p
@cindex Considerations for using a2p
@cindex a2p Considerations

@emph{A2p} cannot do as good a job translating as a human would, but it
usually does pretty well.  There are some areas where you may want to
examine the perl script produced and tweak it some.  Here are some of
them, in no particular order.@refill

There is an @code{awk} idiom of putting @code{int()} around a string
expression to force numeric interpretation, even though the argument is
always integer anyway.  This is generally unneeded in @emph{perl}, but
@emph{a2p} can't tell if the argument is always going to be integer, so
it leaves it in.  You may wish to remove it.@refill

Perl differentiates numeric comparison from string comparison.
@code{Awk} has one operator for both that decides at run time which
comparison to do.  @emph{A2p} does not try to do a complete job of
@code{awk} emulation at this point.  Instead it guesses which one you
want.  It's almost always right, but it can be spoofed.  All such
guesses are marked with the comment @samp{#???}.  You should go through
and check them.  You might want to run at least once with the @samp{-w}
switch to @emph{perl}, which will warn you if you use @samp{==} where
you should have used @emph{eq}.@refill

Perl does not attempt to emulate the behavior of @code{awk} in which
nonexistent array elements spring into existence simply by being
referenced.  If somehow you are relying on this mechanism to create null
entries for a subsequent for...in, they won't be there in perl.

If @emph{a2p} makes a split line that assigns to a list of variables
that looks like @samp{(Fld1, Fld2, Fld3...)} you may want to rerun
@emph{a2p} using the @samp{-n} option mentioned above.  This will let
you name the fields throughout the script.  If it splits to an array
instead, the script is probably referring to the number of fields
somewhere.@refill

The @code{exit} statement in @code{awk} doesn't necessarily exit; it
goes to the END block if there is one.  @code{Awk} scripts that do
contortions within the END block to bypass the block under such
circumstances can be simplified by removing the conditional in the END
block and just exiting directly from the perl script.@refill

@c @@@@ chged array to arrays in orig man pg @@@@
Perl has two kinds of arrays, numerically-indexed and associative.
@code{Awk} arrays are usually translated to associative arrays, but if
you happen to know that the index is always going to be numeric you
could change the @samp{@{@dots{}@}} to @samp{[@dots{}]}.  Iteration over
an associative array is done using the @code{keys()} function, but
iteration over a numeric array is NOT.  You might need to modify any
loop that is iterating over the array in question.@refill

@code{Awk} starts by assuming OFMT has the value @samp{%.6g}.  Perl
starts by assuming its equivalent, @samp{$#}, to have the value
@samp{%.20g}.  You'll want to set @samp{$#} explicitly if you use the
default value of OFMT.@refill

Near the top of the line loop will be the split operation that is
implicit in the @code{awk} script.  There are times when you can move
this down past some conditionals that test the entire record so that the
split is not done as often.

For aesthetic reasons you may wish to change the array base @samp{$[}
from 1 back to perl's default of 0, but remember to change all array
subscripts AND all @code{substr()} and @code{index()} operations to
match.@refill

Cute comments that say ``# Here is a workaround because awk is dumb''
are passed through unmodified.

@code{Awk} scripts are often embedded in a shell script that pipes stuff
into and out of @code{awk}.  Often the shell script wrapper can be
incorporated into the perl script, since perl can start up pipes into
and out of itself, and can do other things that @code{awk} can't do by
itself.

Scripts that refer to the special variables RSTART and RLENGTH can often
be simplified by referring to the variables @samp{$`}, @samp{$&} and
@samp{$'}, as long as they are within the scope of the pattern match
that sets them.@refill

The produced perl script may have subroutines defined to deal with awk's
semantics regarding @code{getline} and @code{print}.  Since @emph{a2p}
usually picks correctness over efficiency.  it is almost always possible
to rewrite such code to be more efficient by discarding the semantic
sugar.@refill

For efficiency, you may wish to remove the keyword from any return
statement that is the last statement executed in a subroutine.
@emph{A2p} catches the most common case, but doesn't analyze embedded
blocks for subtler cases.@refill

@samp{ARGV[0]} translates to @samp{$ARGV0}, but @samp{ARGV[n]}
translates to @samp{$ARGV[$n]}.  A loop that tries to iterate over
@samp{ARGV[0]} won't find it.@refill

@emph{A2p} uses no environment variables.

@node     a2p Bugs, , a2p Considerations, a2p
@comment  node-name,  next,  previous,  up
@section Bugs in a2p
@cindex a2p bugs
@cindex a2p problems
@cindex Problems converting awk scripts using a2p
@cindex Problems using a2p

It would be possible to emulate awk's behavior in selecting string
versus numeric operations at run time by inspection of the operands, but
it would be gross and inefficient.  Besides, @emph{a2p} almost always
guesses right.@refill

Storage for the @code{awk} syntax tree is currently static, and can run
out.

@node     s2p, h2ph, a2p, Top
@comment  node-name,  next,  previous,  up
@chapter s2p - Sed to Perl Translator
@cindex s2p (sed to perl translator)
@cindex Sed to Perl translator
@cindex Converting sed scripts into perl

@emph{S2p} takes a @code{sed} script specified on the command line (or
from standard input) and produces a comparable @emph{perl} script on the
standard output.@refill

@menu
* s2p Options::         Options to s2p
* s2p Considerations::  Considerations when using s2p.
@end menu

@node     s2p Options, s2p Considerations, , s2p
@comment  node-name,  next,  previous,  up
@section Options for s2p
@cindex Options for s2p
@cindex s2p options

@noindent
Options include:

@table @samp
@item -D<number>
sets debugging flags.

@item -n
specifies that this @code{sed} script was always invoked with a
@samp{sed -n}.  Otherwise a switch parser is prepended to the front of
the script.@refill

@item -p
specifies that this @code{sed} script was never invoked with a @samp{sed -n}.
Otherwise a switch parser is prepended to the front of the script.@refill
@end table

@node     s2p Considerations, , s2p Options, s2p
@comment  node-name,  next,  previous,  up
@section Considerations
@cindex Considerations for using s2p
@cindex s2p considerations

The perl script produced looks very @code{sed}-ish, and there may very
well be better ways to express what you want to do in perl.  For
instance, @emph{s2p} does not make any use of the @code{split} operator,
but you might want to.@refill

The perl script you end up with may be either faster or slower than the
original @code{sed} script.  If you're only interested in speed you'll
just have to try it both ways.  Of course, if you want to do something
@code{sed} doesn't do, you have no choice.@refill

@emph{S2p} uses no environment variables.

@node     h2ph, Diagnostics, s2p, Top
@comment  node-name,  next,  previous,  up
@chapter h2ph - Converting C header files into Perl
@cindex h2ph (C @file{.h} files to Perl @file{.ph} files)
@cindex Converting C header files to Perl header files
@cindex C header files
@cindex Perl header files
@c @@@@ NEED TO DISCUSS this more here @@@@
@c @@@@ ALSO include section on h2pl @@@@

@emph{h2ph} converts any C header files specified to the corresponding
Perl header file format.  It is most easily run while in
@file{/usr/include}:@refill

@example
cd /usr/include; h2ph * sys/*
@end example

C header files are located in the @file{/usr/include} directory and end
with the extension @file{.h}.  Perl header files are typically located
in @file{/usr/local/lib/perl}, with the extension @file{.ph} to
distinguish the files from a C header file.@refill

@section Tidbits and Messages in h2ph

No environment variables are used.  The only warnings you will probably
see from @emph{h2ph} are the usual warnings if it can't read or write
the files involved.@refill

@section Bugs in h2ph

@itemize @bullet
@item
@emph{h2ph} doesn't construct the @samp{%sizeof} array for you.

@item
It doesn't handle all C constructs, but it does attempt to isolate
definitions inside @code{eval}s so that you can get at the definitions
that it can translate.

@item
@emph{h2ph} is only intended as a rough tool.  You may need to dicker
with the files produced.
@end itemize

@node     Diagnostics, Traps, h2ph, Top
@comment  node-name,  next,  previous,  up
@chapter Diagnostics
@cindex Diagnostics

Compilation errors will tell you the line number of the error, with an
indication of the next token or token type that was to be examined.  (In
the case of a script passed to @emph{perl} via @samp{-e} switches, each
@samp{-e} is counted as one line.)@refill

Setuid scripts have additional constraints that can produce error messages
such as ``Insecure dependency''.  @xref{Setuid Scripts}.@refill

@node     Traps, Bugs, Diagnostics, Top
@comment  node-name,  next,  previous,  up
@chapter Traps
@cindex Traps
@c @@@@ Add description of Traps chapter @@@@

This chapter points out traps and pitfalls you may run into if you are
used to @code{awk}, @code{C}, @code{sed} or @code{shell} programming.

@menu
* Awk Traps::           Notes for awk users.
* C Traps::             Notes for C programmers.
* Sed Traps::           Notes for sed programmers.
* Shell Traps::         Notes for shell programmers.
@end menu

@node     Awk Traps, C Traps, , Traps
@comment  node-name,  next,  previous,  up
@section Awk Traps
@cindex Awk Traps
@cindex Traps, Awk

@noindent
Accustomed @code{awk} users should take special note of the
following:@refill

@itemize @bullet
@item
Semicolons are required after all simple statements in @emph{perl}.
Newline is not a statement delimiter.@refill
@item
Curly brackets are required on @code{if}s and @code{while}s.@refill
@item
Variables begin with @samp{$} or @samp{@@} in @emph{perl}.@refill
@item
Arrays index from 0 unless you set @samp{$[}.  Likewise string positions in
@code{substr()} and @code{index()}.@refill
@item
You have to decide whether your array has numeric or string indices.@refill
@item
Associative array values do not spring into existence upon mere
reference.@refill
@item
You have to decide whether you want to use string or numeric
comparisons.@refill
@item
Reading an input line does not split it for you.  You get to split it
yourself to an array.  And the @code{split} operator has different
arguments.@refill
@item
The current input line is normally in @samp{$_}, not @samp{$0}.  It
generally does not have the newline stripped.  (@samp{$0} is the name of
the program executed.)@refill
@item
@samp{$<digit>} does not refer to fields---it refers to substrings matched
by the last match pattern.@refill
@item
The @code{print} statement does not add field and record separators unless
you set @samp{$,} and @samp{$\}.@refill
@item
You must open your files before you print to them.@refill
@item
The range operator is @samp{..}, not comma.  (The comma operator works as
in C.)@refill
@item
The match operator is @samp{=~}, not @samp{~}.  (@samp{~} is the one's
complement operator, as in C.)@refill
@item
The exponentiation operator is @samp{**}, not @samp{^}.  (@samp{^} is the
XOR operator, as in C.)@refill
@item
The concatenation operator is @samp{.}, not the null string.  (Using the
null string would render @samp{/pat/ /pat/} unparsable, since the third
slash would be interpreted as a division operator---the tokener is in fact
slightly context sensitive for operators like @samp{/}, @samp{?}, and
@samp{<}.  And in fact, @samp{.} itself can be the beginning of a
number.)@refill
@item
@code{next}, @code{exit} and @code{continue} work differently.@refill
@item
The following variables work differently@refill

@example
@strong{Awk}                 @strong{Perl}
ARGC                  $#ARGV
ARGV[0]               $0
FILENAME              $ARGV
FNR                   $. - something
FS                    (whatever you like)
NF                    $#Fld, or some such
NR                    $.
OFMT                  $#
OFS                   $,
ORS                   $\
RLENGTH               length($&)
RS                    $/
RSTART                length($`)
SUBSEP                $;
@end example

@item
When in doubt, run the @code{awk} construct through @emph{a2p} and see what
it gives you (@pxref{a2p} for more info).@refill
@end itemize

@node     C Traps, Sed Traps, Awk Traps, Traps
@comment  node-name,  next,  previous,  up
@section C Traps
@cindex C Traps
@cindex Traps, C

@noindent
Cerebral C programmers should take note of the following:
@itemize @bullet
@item
Curly brackets are required on @code{if}s and @code{while}s.
@item
You should use @code{elsif} rather than @code{else if}
@item
@code{break} and @code{continue} become @code{last} and @code{next},
respectively.@refill
@item
There's no @code{switch} statement.
@item
Variables begin with @samp{$}, @samp{@@} or @samp{%} in @emph{perl}.@refill
@item
@code{printf} does not implement @samp{*}.
@item
Comments begin with @samp{#}, not @samp{/*}.
@item
You can't take the address of anything.
@item
@samp{ARGV} must be capitalized.
@item
The ``system'' calls @code{link}, @code{unlink}, @code{rename}, etc. return
nonzero for success, not zero (0).@refill
@item
Signal handlers deal with signal names, not numbers.@refill
@end itemize

@node     Sed Traps, Shell Traps, C Traps, Traps
@comment  node-name,  next,  previous,  up
@section Sed Traps
@cindex Sed Traps
@cindex Traps, Sed

@noindent
Seasoned @code{sed} programmers should take note of the following:@refill
@itemize @bullet
@item
Backreferences in substitutions use @samp{$} rather than @samp{\}.
@item
The pattern matching metacharacters @samp{(}, @samp{)}, and @samp{|} do not
have backslashes in front.@refill
@item
The range operator is @samp{..} rather than comma.
@end itemize

@node     Shell Traps, , Sed Traps, Traps
@comment  node-name,  next,  previous,  up
@section Shell Traps
@cindex Shell Traps
@cindex Traps, Shell

@noindent
Sharp shell programmers should take note of the following:
@itemize @bullet
@item
The backtick operator does variable interpretation without regard to the
presence of single quotes in the command.@refill
@item
The backtick operator does no translation of the return value, unlike
@code{csh}.@refill
@item
Shells (especially @code{csh}) do several levels of substitution on each
command line.  @emph{Perl} does substitution only in certain constructs
such as double quotes, backticks, angle brackets and search
patterns.@refill
@item
Shells interpret scripts a little bit at a time.  @emph{Perl} compiles the
whole program before executing it.@refill
@item
The arguments are available via @samp{@@ARGV}, not @samp{$1}, @samp{$2},
etc.@refill
@item
The environment is not automatically made available as variables.@refill
@end itemize

@node     Bugs, Credits, Traps, Top
@comment  node-name,  next,  previous,  up
@chapter Bugs
@cindex Bugs

@emph{Perl} is at the mercy of your machine's definitions of various
operations such as type casting, @code{atof()} and @code{sprintf()}.@refill

If your stdio requires a @code{seek} or @code{eof} between reads and writes
on a particular stream, so does @emph{perl}.  (This doesn't apply to
@code{sysread()} and @code{syswrite()}.)@refill

While none of the built-in data types have any arbitrary size limits (apart
from memory size), there are still a few arbitrary limits: a given
identifier may not be longer than 255 characters; @code{sprintf} is limited
on many machines to 128 characters per field (unless the format specifier
is exactly @samp{%s}); and no component of your @samp{PATH} may be longer
than 255 if you use @samp{-S}.@refill

@emph{Perl} actually stands for Pathologically Eclectic Rubbish Lister, but
don't tell anyone I said that.@refill

@node     Credits, Errata, Bugs, Top
@comment  node-name,  next,  previous,  up
@chapter The Credits
@cindex Authors
@cindex Credits

@noindent
Perl was designed and implemented by@dots{}
                @dots{}Larry Wall <lwall@@jpl-devvax.Jpl.Nasa.Gov>
@*
MS-DOS port of perl by@dots{}
                @dots{}Diomidis Spinellis <dds@@cc.ic.ac.uk>
@*
Texinfo version of @emph{perl} manual by@dots{}
                @dots{}Jeff Kellem <composer@@chem.bu.edu>

@node     Errata, Command Summary, Credits, Top
@comment  node-name,  next,  previous,  up
@chapter Errata and Addenda
@cindex Errata and Addenda
@cindex Addenda and Errata

The Perl book, @i{Programming Perl}, has the following omissions and
goofs.

@itemize @bullet
@item
On page 5, the examples which read

@example
eval '/usr/bin/perl
@end example

should read

@example
eval 'exec /usr/bin/perl
@end example

@item
On page 195, the equivalent to the System V @code{sum} program only works for
very small files.  To do larger files, use

@example
undef $/;
$checksum = unpack("%32C*",<>) % 32767;
@end example

@item
The @samp{-0} switch to set the initial value of @samp{$/} was added to
Perl after the book went to press.
@item
The @samp{-l} switch now does automatic line ending processing.
@item
The @code{qx//} construct is now a synonym for backticks.
@item
@samp{$0} may now be assigned to set the argument displayed by
@code{ps(1)}.@refill
@item
The new @samp{@@###.##} format was omitted accidentally from the
description on formats.@refill
@item
It wasn't known at press time that @code{s///ee} caused multiple
evaluations of the replacement expression.  This is to be construed as a
feature.@refill
@item
@code{(@var{LIST}) x $count} now does array replication.
@item
There is now no limit on the number of parentheses in a regular
expression.@refill
@item
In double-quote context, more escapes are supported: \e, \a, \x1b, \c[,
\l, \L, \u, \U, \E.  The latter five control up/lower case translation.
@item
The @samp{$/} variable may now be set to a multi-character delimiter.
@end itemize

@node     Command Summary, Function Index, Errata, Top
@comment  node-name,  next,  previous,  up
@appendix Command Summary (syntax only)
@cindex Command Summary (syntax only)
@cindex Syntax of all commands

@noindent
THIS SECTION IS CURRENTLY INCOMPLETE and may change without notice!!
@*
(As may the rest of this document... ;-)

@display
/PATTERN/io
?PATTERN?
@c @@@@ should this be ?PATTERN?io ?? @@@@

accept(NEWSOCKET,GENERICSOCKET)
atan2(X,Y)

bind(SOCKET,NAME)
binmode(FILEHANDLE)
binmode FILEHANDLE

chdir(EXPR)
chdir EXPR
chdir
chmod(LIST)
chmod LIST
chop(LIST)
chop(VARIABLE)
chop VARIABLE
chop
chown(LIST)
chown LIST
chroot(FILENAME)
chroot FILENAME
chroot
close(FILEHANDLE)
close FILEHANDLE
closedir(DIRHANDLE)
closedir DIRHANDLE
connect(SOCKET,NAME)
cos(EXPR)
cos EXPR
cos
crypt(PLAINTEXT,SALT)

dbmclose(ASSOC_ARRAY)
dbmclose ASSOC_ARRAY
dbmopen(ASSOC,DBNAME,MODE)
defined(EXPR)
defined EXPR
delete $ASSOC@{KEY@}
die(LIST)
die LIST
die
do BLOCK
do EXPR
do SUBROUTINE (LIST)
dump LABEL
dump

each(ASSOC_ARRAY)
each ASSOC_ARRAY
endpwent
endgrent
endhostent
endnetent
endprotoent
endpwent
endservent
eof(FILEHANDLE)
eof()
eof
eval(EXPR)
eval EXPR
eval
exec(LIST)
exec LIST
exit(EXPR)
exit EXPR
exp(EXPR)
exp EXPR
exp

fcntl(FILEHANDLE,FUNCTION,SCALAR)
fileno(FILEHANDLE)
fileno FILEHANDLE
flock(FILEHANDLE,OPERATION)
fork

getc(FILEHANDLE)
getc FILEHANDLE
getc
getgrent
getgrgid(GID)
getgrnam(NAME)
gethostbyaddr(ADDR,ADDRTYPE)
gethostbyname(NAME)
gethostent
getlogin
getnetbyaddr(ADDR,ADDRTYPE)
getnetbyname(NAME)
getnetent
getpeername(SOCKET)
getpgrp(PID)
getpgrp PID
getpgrp
getppid
getpriority(WHICH,WHO)
getprotobyname(NAME)
getprotobynumber(NUMBER)
getprotoent
getpwent
getpwnam(NAME)
getpwuid(UID)
getservbyname(NAME,PROTO)
getservbyport(PORT,PROTO)
getservent
getsockname(SOCKET)
getsockopt(SOCKET,LEVEL,OPTNAME)
gmtime(EXPR)
gmtime EXPR
gmtime
goto LABEL
grep(EXPR,LIST)

hex(EXPR)
hex EXPR
hex

index(STR,SUBSTR)
int(EXPR)
int EXPR
int
ioctl(FILEHANDLE,FUNCTION,SCALAR)

join(EXPR,LIST)
join(EXPR,ARRAY)

keys(ASSOC_ARRAY)
keys ASSOC_ARRAY
kill(LIST)
kill LIST

last LABEL
last
length(EXPR)
length EXPR
length
link(OLDFILE,NEWFILE)
listen(SOCKET,QUEUESIZE)
local(LIST)
localtime(EXPR)
localtime EXPR
localtime
log(EXPR)
log EXPR
log
lstat(FILEHANDLE)
lstat FILEHANDLE
lstat(EXPR)
lstat SCALARVARIABLE

m/PATTERN/io
/PATTERN/io
mkdir(FILENAME,MODE)

next LABEL
next

oct(EXPR)
oct EXPR
oct
open(FILEHANDLE,EXPR)
open(FILEHANDLE)
open FILEHANDLE
opendir(DIRHANDLE,EXPR)
ord(EXPR)
ord EXPR
ord

pack(TEMPLATE,LIST)
pipe(READHANDLE,WRITEHANDLE)
pop(ARRAY)
pop ARRAY
print(FILEHANDLE LIST)
print(LIST)
print FILEHANDLE LIST
print LIST
print
printf(FILEHANDLE LIST)
printf(LIST)
printf FILEHANDLE LIST
printf LIST
printf
push(ARRAY,LIST)

q/STRING/
qq/STRING/

rand(EXPR)
rand EXPR
rand
read(FILEHANDLE,SCALAR,LENGTH)
readdir(DIRHANDLE)
readdir DIRHANDLE
readlink(EXPR)
readlink EXPR
readlink
recv(SOCKET,SCALAR,LEN,FLAGS)
redo LABEL
redo
rename(OLDNAME,NEWNAME)
require(EXPR)
require EXPR
require
reset(EXPR)
reset EXPR
reset
return LIST
reverse(LIST)
reverse LIST
rewinddir(DIRHANDLE)
rewinddir DIRHANDLE
rindex(STR,SUBSTR)
rmdir(FILENAME)
rmdir FILENAME
rmdir

s/PATTERN/REPLACEMENT/gieo
seek(FILEHANDLE,POSITION,WHENCE)
seekdir(DIRHANDLE,POS)
select(FILEHANDLE)
select
select(RBITS,WBITS,EBITS,TIMEOUT)
send(SOCKET,MSG,FLAGS,TO)
send(SOCKET,MSG,FLAGS)
setgrent
sethostent(STAYOPEN)
setnetent(STAYOPEN)
setpgrp(PID,PGRP)
setpriority(WHICH,WHO,PRIORITY)
setprotoent(STAYOPEN)
setpwent
setservent(STAYOPEN)
setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)
shift(ARRAY)
shift ARRAY
shift
shutdown(SOCKET,HOW)
sin(EXPR)
sin EXPR
sin
sleep(EXPR)
sleep EXPR
sleep
socket(SOCKET,DOMAIN,TYPE,PROTOCOL)
socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)
sort(SUBROUTINE LIST)
sort(LIST)
sort SUBROUTINE LIST
sort LIST
splice(ARRAY,OFFSET,LENGTH,LIST)
splice(ARRAY,OFFSET,LENGTH)
splice(ARRAY,OFFSET)
split(/PATTERN/,EXPR,LIMIT)
split(/PATTERN/,EXPR)
split(/PATTERN/)
split
sprintf(FORMAT,LIST)
sqrt(EXPR)
sqrt EXPR
sqrt
srand(EXPR)
srand EXPR
srand
stat(FILEHANDLE)
stat FILEHANDLE
stat(EXPR)
stat SCALARVARIABLE
study(SCALAR)
study SCALAR
study
substr(EXPR,OFFSET,LEN)
symlink(OLDFILE,NEWFILE)
syscall(LIST)
syscall LIST
system(LIST)
system LIST

tell(FILEHANDLE)
tell FILEHANDLE
tell
telldir(DIRHANDLE)
telldir DIRHANDLE
time
times
tr/SEARCHLIST/REPLACEMENTLIST/

umask(EXPR)
umask EXPR
umask
undef(EXPR)
undef EXPR
undef
unlink(LIST)
unlink LIST
unlink
unpack(TEMPLATE,EXPR)
unshift(ARRAY,LIST)
utime(LIST)
utime LIST

values(ASSOC_ARRAY)
values ASSOC_ARRAY
vec(EXPR,OFFSET,BITS)

wait
wantarray
warn(LIST)
warn LIST
write(FILEHANDLE)
write(EXPR)
write

y/SEARCHLIST/REPLACEMENTLIST/
@end display

@node Function Index, Concept Index, Command Summary, Top
@comment  node-name,  next,  previous,  up
@unnumbered Function Index
@printindex fn

@node Concept Index, , Function Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index
@printindex cp

@summarycontents
@contents
@bye

@ignore
''' $Log:       perl.man.1,v $
''' Revision 3.0.1.11  91/01/11  18:15:46  lwall
''' patch42: added -0 option
'''
''' patch29: added DATA filehandle to read stuff after __END__
''' patch29: added cmp and <=>
''' patch29: added -M, -A and -C
'''
''' patch19: added -x switch to extract script from input trash
''' patch19: Added -c switch to do compilation only
''' patch19: bare identifiers are now strings if no other interpretation possible
''' patch19: -s now returns size of file
''' patch19: Added __LINE__ and __FILE__ tokens
''' patch19: Added __END__ token
'''
''' Revision 3.0.1.6  90/08/03  11:14:44  lwall
''' patch19: Intermediate diffs for Randal
'''
''' Revision 3.0.1.5  90/03/27  16:14:37  lwall
''' patch16: .. now works using magical string increment
'''
''' Revision 3.0.1.4  90/03/12  16:44:33  lwall
''' patch13: (LIST,) now legal
''' patch13: improved LIST documentation
''' patch13: example of if-elsif switch was wrong
'''
''' Revision 3.0.1.3  90/02/28  17:54:32  lwall
''' patch9: @array in scalar context now returns length of array
''' patch9: in manual, example of open and ?: was backwards
'''
''' Revision 3.0.1.2  89/11/17  15:30:03  lwall
''' patch5: fixed some manual typos and indent problems
'''
''' Revision 3.0.1.1  89/11/11  04:41:22  lwall
''' patch2: explained about sh and ${1+"$@"}
''' patch2: documented that space must separate word and '' string
'''
''' Revision 3.0  89/10/18  15:21:29  lwall
''' 3.0 baseline
'''
''' $Log:       perl.man.2,v $
''' Revision 3.0.1.10  90/11/10  01:46:29  lwall
''' patch38: random cleanup
''' patch38: added alarm function
'''
''' Revision 3.0.1.9  90/10/15  18:17:37  lwall
''' patch29: added caller
''' patch29: index and substr now have optional 3rd args
''' patch29: added SysV IPC
'''
''' patch28: documented that you can't interpolate $) or $| in pattern
'''
''' Revision 3.0.1.7  90/08/09  04:27:04  lwall
''' patch19: added require operator
'''
''' Revision 3.0.1.6  90/08/03  11:15:29  lwall
''' patch19: Intermediate diffs for Randal
'''
''' Revision 3.0.1.5  90/03/27  16:15:17  lwall
''' patch16: MSDOS support
'''
''' Revision 3.0.1.4  90/03/12  16:46:02  lwall
''' patch13: documented behavior of @array = /noparens/
'''
''' Revision 3.0.1.3  90/02/28  17:55:58  lwall
''' patch9: grep now returns number of items matched in scalar context
''' patch9: documented in-place modification capabilites of grep
'''
''' Revision 3.0.1.2  89/11/17  15:30:16  lwall
''' patch5: fixed some manual typos and indent problems
'''
''' Revision 3.0.1.1  89/11/11  04:43:10  lwall
''' patch2: made some line breaks depend on troff vs. nroff
''' patch2: example of unshift had args backwards
'''
''' Revision 3.0  89/10/18  15:21:37  lwall
''' 3.0 baseline
'''
''' $Log:       perl.man.3,v $
''' Revision 3.0.1.12  91/01/11  18:18:15  lwall
''' patch42: added binary and hex pack/unpack options
'''
''' Revision 3.0.1.11  90/11/10  01:48:21  lwall
''' patch38: random cleanup
''' patch38: documented tr///cds
'''
''' Revision 3.0.1.9  90/10/16  10:02:43  lwall
''' patch29: you can now read into the middle string
''' patch29: index and substr now have optional 3rd args
''' patch29: added scalar reverse
''' patch29: added scalar
''' patch29: added SysV IPC
''' patch29: added waitpid
''' patch29: added sysread and syswrite
'''
''' Revision 3.0.1.8  90/08/09  04:39:04  lwall
''' patch19: added require operator
''' patch19: added truncate operator
''' patch19: unpack can do checksumming
'''
''' Revision 3.0.1.7  90/08/03  11:15:42  lwall
''' patch19: Intermediate diffs for Randal
'''
''' Revision 3.0.1.6  90/03/27  16:17:56  lwall
''' patch16: MSDOS support
'''
''' Revision 3.0.1.5  90/03/12  16:52:21  lwall
''' patch13: documented that print $filehandle &foo is ambiguous
''' patch13: added splice operator: @oldelems = splice(@array,$offset,$len,LIST)
'''
''' Revision 3.0.1.4  90/02/28  18:00:09  lwall
''' patch9: added pipe function
''' patch9: documented how to handle arbitrary weird characters in filenames
''' patch9: documented the unflushed buffers problem on piped opens
''' patch9: documented how to force top of page
'''
''' Revision 3.0.1.3  89/12/21  20:10:12  lwall
''' patch7: documented that s`pat`repl` does command substitution on replacement
''' patch7: documented that $timeleft from select() is likely not implemented
'''
''' Revision 3.0.1.2  89/11/17  15:31:05  lwall
''' patch5: fixed some manual typos and indent problems
''' patch5: added warning about print making an array context
'''
''' Revision 3.0.1.1  89/11/11  04:45:06  lwall
''' patch2: made some line breaks depend on troff vs. nroff
'''
''' Revision 3.0  89/10/18  15:21:46  lwall
''' 3.0 baseline
'''
''' $Log:       perl.man.4,v $
''' Revision 3.0.1.14  91/01/11  18:18:53  lwall
''' patch42: started an addendum and errata section in the man page
'''
''' Revision 3.0.1.10  90/08/09  04:47:35  lwall
''' Revision 3.0.1.11  90/10/16  10:04:28  lwall
''' patch29: added @@###.## fields to format
'''
''' patch19: added require operator
''' patch19: added numeric interpretation of $]
'''
''' Revision 3.0.1.9  90/08/03  11:15:58  lwall
''' patch19: Intermediate diffs for Randal
'''
''' Revision 3.0.1.8  90/03/27  16:19:31  lwall
''' patch16: MSDOS support
'''
''' Revision 3.0.1.7  90/03/14  12:29:50  lwall
''' patch15: man page falsely states that you can't subscript array values
'''
''' Revision 3.0.1.6  90/03/12  16:54:04  lwall
''' patch13: improved documentation of *name
'''
''' Revision 3.0.1.5  90/02/28  18:01:52  lwall
''' patch9: $0 is now always the command name
'''
''' Revision 3.0.1.4  89/12/21  20:12:39  lwall
''' patch7: documented that package'filehandle works as well as $package'variable
''' patch7: documented which identifiers are always in package main
'''
''' Revision 3.0.1.3  89/11/17  15:32:25  lwall
''' patch5: fixed some manual typos and indent problems
''' patch5: clarified difference between $! and $@
'''
''' Revision 3.0.1.2  89/11/11  04:46:40  lwall
''' patch2: made some line breaks depend on troff vs. nroff
''' patch2: clarified operation of ^ and $ when $* is false
'''
''' Revision 3.0.1.1  89/10/26  23:18:43  lwall
''' patch1: documented the desirability of unnecessary parentheses
'''
''' Revision 3.0  89/10/18  15:21:55  lwall
''' 3.0 baseline
'''
@end ignore
