=head1 SYNOPSIS
+B<perl> S<[ B<-sTuU> ]>
+ S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+ S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+ S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+ S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
+ S<[ B<-P> ]>
+ S<[ B<-S> ]>
+ S<[ B<-x>[I<dir>] ]>
+ S<[ B<-i>[I<extension>] ]>
+ S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+
For ease of access, the Perl manual has been split up into a number
of sections:
perl Perl overview (this section)
+ perldelta Perl changes since previous version
+ perlfaq Perl frequently asked questions
+
perldata Perl data structures
perlsyn Perl syntax
perlop Perl operators and precedence
perlfunc Perl builtin functions
perlvar Perl predefined variables
perlsub Perl subroutines
- perlmod Perl modules
- perlref Perl references and nested data structures
+ perlmod Perl modules: how they work
+ perlmodlib Perl modules: how to write and use
+ perlform Perl formats
+ perllocale Perl locale support
+
+ perlref Perl references
+ perldsc Perl data structures intro
+ perllol Perl data structures: lists of lists
+ perltoot Perl OO tutorial
perlobj Perl objects
+ perltie Perl objects hidden behind simple variables
perlbot Perl OO tricks and examples
+ perlipc Perl interprocess communication
+
perldebug Perl debugging
perldiag Perl diagnostic messages
- perlform Perl formats
- perlipc Perl interprocess communication
perlsec Perl security
perltrap Perl traps for the unwary
perlstyle Perl style guide
- perlapi Perl application programming interface
- perlguts Perl internal functions for those doing extensions
- perlcall Perl calling conventions from C
- perlovl Perl overloading semantics
+
+ perlpod Perl plain old documentation
perlbook Perl book information
+ perlembed Perl ways to embed perl in your C or C++ application
+ perlapio Perl internal IO abstraction interface
+ perlxs Perl XS application programming interface
+ perlxstut Perl XS tutorial
+ perlguts Perl internal functions for those doing extensions
+ perlcall Perl calling conventions from C
+
+ perlhist Perl history records
+
(If you're intending to read these straight through for the first time,
the suggested order will tend to reduce the number of forward references.)
-Additional documentation for perl modules is available in
-the F</usr/local/lib/perl5/man/man3> directory. You can view this
-with a man(1) program by including the following in the
-appropriate start-up files. (You may have to adjust the path to
-match $Config{'man3dir'}.)
+By default, all of the above manpages are installed in the
+F</usr/local/man/> directory.
+
+Extensive additional documentation for Perl modules is available. The
+default configuration for perl will place this additional documentation
+in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
+subdirectory of the Perl library directory). Some of this additional
+documentation is distributed standard with Perl, but you'll also find
+documentation for third-party modules there.
+
+You should be able to view Perl's documentation with your man(1)
+program by including the proper directories in the appropriate start-up
+files, or in the MANPATH environment variable. To find out where the
+configuration has installed the manpages, type:
- .profile (for sh, bash or ksh users):
- MANPATH=$MANPATH:/usr/local/lib/perl5/man
- export MANPATH
+ perl -V:man.dir
- .login (for csh or tcsh users):
- setenv MANPATH $MANPATH:/usr/local/lib/perl5/man
+If the directories have a common stem, such as F</usr/local/man/man1>
+and F</usr/local/man/man3>, you need only to add that stem
+(F</usr/local/man>) to your man(1) configuration files or your MANPATH
+environment variable. If they do not share a stem, you'll have to add
+both stems.
If that doesn't work for some reason, you can still use the
-supplied perldoc script to view module information.
+supplied F<perldoc> script to view module information. You might
+also look into getting a replacement man program.
If something strange has gone wrong with your program and you're not
sure where you should look for help, try the B<-w> switch first. It
=head1 DESCRIPTION
-Perl is an interpreted language optimized for scanning arbitrary
+Perl is a 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 C, B<sed>, B<awk>, and B<sh>, so people
-familiar with those languages should have little difficulty with it.
-(Language historians will also note some vestiges of B<csh>, Pascal,
-and even BASIC-PLUS.) Expression syntax corresponds quite closely to C
+elegant, minimal).
+
+Perl combines (in the author's opinion, anyway) some of the best
+features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
+those languages should have little difficulty with it. (Language
+historians will also note some vestiges of B<csh>, Pascal, and even
+BASIC-PLUS.) Expression syntax corresponds quite closely to C
expression syntax. Unlike most Unix utilities, Perl does not
arbitrarily limit the size of your data--if you've got the memory,
-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. Perl uses
-sophisticated pattern matching techniques to scan large amounts of data
-very quickly. Although optimized for scanning text, Perl can also
-deal with binary data, and can make dbm files look like associative
-arrays (where dbm is available). Setuid 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
-B<sed> or B<awk> or B<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 Perl may be for you. There are also translators to turn your
-B<sed> and B<awk> scripts into Perl scripts.
+Perl can slurp in your whole file as a single string. Recursion is of
+unlimited depth. And the tables used by hashes (previously called
+"associative arrays") grow as necessary to prevent degraded
+performance. Perl uses sophisticated pattern matching techniques to
+scan large amounts of data very quickly. Although optimized for
+scanning text, Perl can also deal with binary data, and can make dbm
+files look like hashes. Setuid 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 B<sed> or B<awk> or
+B<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 Perl may be for
+you. There are also translators to turn your B<sed> and B<awk>
+scripts into Perl scripts.
But wait, there's more...
Perl variables may now be declared within a lexical scope, like "auto"
variables in C. Not only is this more efficient, but it contributes
-to better privacy for "programming in the large".
+to better privacy for "programming in the large". Anonymous
+subroutines exhibit deep binding of lexical variables (closures).
=item * Arbitrarily nested data structures
virtual methods are supported in a straightforward manner and with very
little new syntax. Filehandles may now be treated as objects.
-=item * Embeddible and Extensible
+=item * Embeddable and Extensible
Perl may now be embedded easily in your C or C++ application, and can
either call or be called by your routines through a documented
interface. The XS preprocessor is provided to make it easy to glue
your C or C++ routines into Perl. Dynamic loading of modules is
-supported.
+supported, and Perl itself can be made into a dynamic library.
=item * POSIX compliant
=item * Subroutine definitions may now be autoloaded
In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
-semantics for undefined subroutine calls. It's not just for autoloading.
+semantics for undefined subroutine calls. It's not for just autoloading.
=item * Regular expression enhancements
-You can now specify non-greedy quantifiers. You can now do grouping
+You can now specify nongreedy quantifiers. You can now do grouping
without creating a backreference. You can now write regular expressions
with embedded whitespace and comments for readability. A consistent
extensibility mechanism has been added that is upwardly compatible with
all old regular expressions.
-=back
-
-Ok, that's I<definitely> enough hype.
+=item * Innumerable Unbundled Modules
-=head1 ENVIRONMENT
+The Comprehensive Perl Archive Network described in L<perlmodlib>
+contains hundreds of plug-and-play modules full of reusable code.
+See F<http://www.perl.com/CPAN> for a site near you.
-=over 12
-
-=item HOME
-
-Used if chdir has no argument.
-
-=item LOGDIR
-
-Used if chdir has no argument and HOME is not set.
-
-=item PATH
-
-Used in executing subprocesses, and in finding the script if B<-S> is
-used.
-
-=item PERL5LIB
-
-A colon-separated list of directories in which to look for Perl library
-files before looking in the standard library and the current
-directory. If PERL5LIB is not defined, PERLLIB is used.
-
-=item PERL5DB
-
-The command used to get the debugger code. If unset, uses
-
- BEGIN { require 'perl5db.pl' }
-
-=item PERLLIB
-
-A colon-separated list of directories in which to look for Perl library
-files before looking in the standard library and the current
-directory. If PERL5LIB is defined, PERLLIB is not used.
+=item * Compilability
+While not yet in full production mode, a working perl-to-C compiler
+does exist. It can generate portable byte code, simple C, or
+optimized C code.
=back
-Apart from these, Perl uses no other 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:
+Okay, that's I<definitely> enough hype.
- $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need
- $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'};
- $ENV{'IFS'} = '' if defined $ENV{'IFS'};
+=head1 ENVIRONMENT
+
+See L<perlrun>.
=head1 AUTHOR
-Larry Wall <F<lwall@netlabs.com.>, with the help of oodles of other folks.
+Larry Wall <F<larry@wall.org>>, with the help of oodles of other folks.
+
+If your Perl success stories and testimonials may be of help to others
+who wish to advocate the use of Perl in their applications,
+or if you wish to simply express your gratitude to Larry and the
+Perl developers, please write to <F<perl-thanks@perl.org>>.
=head1 FILES
"/tmp/perl-e$$" temporary file for -e commands
- "@INC" locations of perl 5 libraries
+ "@INC" locations of perl libraries
=head1 SEE ALSO
a2p awk to perl translator
+
s2p sed to perl translator
=head1 DIAGNOSTICS
The B<-w> switch is not mandatory.
Perl is at the mercy of your machine's definitions of various
-operations such as type casting, atof() and sprintf().
+operations such as type casting, atof(), and floating-point
+output with sprintf().
If your stdio requires a seek or eof between reads and writes on a
particular stream, so does Perl. (This doesn't apply to sysread()
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, and no
+given variable name may not be longer than 255 characters, and no
component of your PATH may be longer than 255 if you use B<-S>. A regular
expression may not compile to more than 32767 bytes internally.
+You may mail your bug reports (be sure to include full configuration
+information as output by the myconfig program in the perl source tree,
+or by C<perl -V>) to <F<perlbug@perl.com>>.
+If you've succeeded in compiling perl, the perlbug script in the utils/
+subdirectory can be used to help mail in a bug report.
+
Perl actually stands for Pathologically Eclectic Rubbish Lister, but
don't tell anyone I said that.
The Perl motto is "There's more than one way to do it." Divining
how many more is left as an exercise to the reader.
-The three principle virtues of a programmer are Laziness,
+The three principal virtues of a programmer are Laziness,
Impatience, and Hubris. See the Camel Book for why.