This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Tweak for Cray-friendliness from Nicholas Clark.
[perl5.git] / pod / perl.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perl - Practical Extraction and Report Language
4
5=head1 SYNOPSIS
6
19799a22
GS
7B<perl> S<[ B<-sTuU> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
8 S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
9 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
10 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
11 S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I<dir>] ]>
12 S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ]
13 [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
c07a80fd 14
10151d09
JH
15If you're new to Perl, you should start with L<perlintro>, which is a
16general intro for beginners and provides some background to help you
17navigate the rest of Perl's extensive documentation.
18
19For ease of access, the Perl manual has been split up into several sections.
a0d0e21e 20
fd7b6849
MJD
21=head2 Overview
22
fb9cefb4 23 perl Perl overview (this section)
10151d09 24 perlintro Perl introduction for beginners
fb9cefb4 25 perltoc Perl documentation table of contents
760ac839 26
fd7b6849
MJD
27=head2 Tutorials
28
7a2320f0
AMS
29 perlreftut Perl references short introduction
30 perldsc Perl data structures intro
31 perllol Perl data structures: arrays of arrays
7a2320f0
AMS
32
33 perlrequick Perl regular expressions quick start
34 perlretut Perl regular expressions tutorial
35
36 perlboot Perl OO tutorial for beginners
37 perltoot Perl OO tutorial, part 1
38 perltooc Perl OO tutorial, part 2
39 perlbot Perl OO tricks and examples
40
41 perlstyle Perl style guide
42
43 perltrap Perl traps for the unwary
44 perldebtut Perl debugging tutorial
45
fd7b6849
MJD
46 perlfaq Perl frequently asked questions
47 perlfaq1 General Questions About Perl
48 perlfaq2 Obtaining and Learning about Perl
49 perlfaq3 Programming Tools
50 perlfaq4 Data Manipulation
51 perlfaq5 Files and Formats
52 perlfaq6 Regexes
53 perlfaq7 Perl Language Issues
54 perlfaq8 System Interaction
55 perlfaq9 Networking
0f542199 56
fd7b6849 57=head2 Reference Manual
413510b3 58
fb9cefb4 59 perlsyn Perl syntax
4755096e 60 perldata Perl data structures
fb9cefb4 61 perlop Perl operators and precedence
c2e66d9e 62 perlsub Perl subroutines
fd7b6849 63 perlfunc Perl built-in functions
413510b3 64 perlopentut Perl open() tutorial
c2e66d9e 65 perlpod Perl plain old documentation
8a93676d 66 perlpodspec Perl plain old documentation format specification
c2e66d9e
GS
67 perlrun Perl execution and options
68 perldiag Perl diagnostic messages
4755096e
GS
69 perllexwarn Perl warnings and their control
70 perldebug Perl debugging
fb9cefb4 71 perlvar Perl predefined variables
4755096e 72 perlre Perl regular expressions, the rest of the story
d396a558 73 perlref Perl references, the rest of the story
fb9cefb4 74 perlform Perl formats
d396a558 75 perlobj Perl objects
d396a558 76 perltie Perl objects hidden behind simple variables
fd7b6849 77 perldbmfilter Perl DBM filters
760ac839 78
c2e66d9e
GS
79 perlipc Perl interprocess communication
80 perlfork Perl fork() information
81 perlnumber Perl number semantics
53d7eaa8 82
c2e66d9e 83 perlthrtut Perl threads tutorial
fd7b6849 84 perlothrtut Perl threads tutorial
c2e66d9e
GS
85
86 perlport Perl portability guide
d396a558
JH
87 perllocale Perl locale support
88 perlunicode Perl unicode support
89 perlebcdic Considerations for running Perl on EBCDIC platforms
c2e66d9e 90
d396a558 91 perlsec Perl security
4755096e 92
c2e66d9e 93 perlmod Perl modules: how they work
35bf961c
JH
94 perlmodlib Perl modules: how to write and use
95 perlmodstyle Perl modules: how to write modules with style
fd7b6849 96 perlmodinstall Perl modules: how to install from CPAN
c2e66d9e 97 perlnewmod Perl modules: preparing a new module for distribution
760ac839 98
fd7b6849 99 perlutil utilities packaged with the Perl distribution
760ac839 100
4755096e 101 perlcompile Perl compiler suite intro
760ac839 102
fd7b6849
MJD
103 perlfilter Perl source filters
104
105=head2 Internals and C Language Interface
106
fb9cefb4 107 perlembed Perl ways to embed perl in your C or C++ application
055fd3a9 108 perldebguts Perl debugging guts and tips
fb9cefb4 109 perlxstut Perl XS tutorial
4755096e 110 perlxs Perl XS application programming interface
f40a6c71 111 perlclib Internal replacements for standard C library functions
fb9cefb4
GS
112 perlguts Perl internal functions for those doing extensions
113 perlcall Perl calling conventions from C
fd7b6849 114
954c1994
GS
115 perlapi Perl API listing (autogenerated)
116 perlintern Perl internal functions (autogenerated)
dc5c060f 117 perliol C API for Perl's implementation of IO in Layers
4755096e 118 perlapio Perl internal IO abstraction interface
fd7b6849 119
e8cd7eae 120 perlhack Perl hackers guide
4755096e 121
fd7b6849
MJD
122=head2 Miscellaneous
123
124 perlbook Perl book information
fd7b6849
MJD
125 perltodo Perl things to do
126
fb9cefb4 127 perlhist Perl history records
4755096e 128 perldelta Perl changes since previous version
245d750e 129 perl572delta Perl changes in version 5.7.2
1db9e106
JH
130 perl571delta Perl changes in version 5.7.1
131 perl570delta Perl changes in version 5.7.0
4755096e
GS
132 perl56delta Perl changes in version 5.6
133 perl5005delta Perl changes in version 5.005
134 perl5004delta Perl changes in version 5.004
d516a115 135
fd7b6849
MJD
136=head2 Platform-Specific
137
37d4d706 138 perlaix Perl notes for AIX
a83b6f46
JH
139 perlamiga Perl notes for AmigaOS
140 perlapollo Perl notes for Apollo DomainOS
141 perlbeos Perl notes for BeOS
dc5c060f 142 perlbs2000 Perl notes for POSIX-BC BS2000
a1f19229 143 perlce Perl notes for WinCE
49877630 144 perlcygwin Perl notes for Cygwin
245d750e 145 perldgux Perl notes for DG/UX
49877630 146 perldos Perl notes for DOS
9a997319 147 perlepoc Perl notes for EPOC
49877630 148 perlhpux Perl notes for HP-UX
a83b6f46 149 perlhurd Perl notes for Hurd
da369004 150 perlmachten Perl notes for Power MachTen
26d9b02f 151 perlmacos Perl notes for Mac OS (Classic)
a83b6f46 152 perlmint Perl notes for MiNT
ab648d5e 153 perlmpeix Perl notes for MPE/iX
9038e305 154 perlnetware Perl notes for NetWare
49877630
GS
155 perlos2 Perl notes for OS/2
156 perlos390 Perl notes for OS/390
a83b6f46
JH
157 perlplan9 Perl notes for Plan 9
158 perlqnx Perl notes for QNX
d420ca49 159 perlsolaris Perl notes for Solaris
772ff3b9 160 perltru64 Perl notes for Tru64
91144103 161 perluts Perl notes for UTS
cbe1151c 162 perlvmesa Perl notes for VM/ESA
49877630 163 perlvms Perl notes for VMS
9a997319 164 perlvos Perl notes for Stratus VOS
49877630
GS
165 perlwin32 Perl notes for Windows
166
a0d0e21e 167
19799a22 168By default, the manpages listed above are installed in the
fc952dec
CS
169F</usr/local/man/> directory.
170
171Extensive additional documentation for Perl modules is available. The
172default configuration for perl will place this additional documentation
173in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
174subdirectory of the Perl library directory). Some of this additional
175documentation is distributed standard with Perl, but you'll also find
176documentation for third-party modules there.
177
178You should be able to view Perl's documentation with your man(1)
179program by including the proper directories in the appropriate start-up
180files, or in the MANPATH environment variable. To find out where the
181configuration has installed the manpages, type:
16d20bd9 182
760ac839 183 perl -V:man.dir
16d20bd9 184
fc952dec
CS
185If the directories have a common stem, such as F</usr/local/man/man1>
186and F</usr/local/man/man3>, you need only to add that stem
187(F</usr/local/man>) to your man(1) configuration files or your MANPATH
188environment variable. If they do not share a stem, you'll have to add
189both stems.
16d20bd9
AD
190
191If that doesn't work for some reason, you can still use the
4633a7c4
LW
192supplied F<perldoc> script to view module information. You might
193also look into getting a replacement man program.
16d20bd9 194
a0d0e21e
LW
195If something strange has gone wrong with your program and you're not
196sure where you should look for help, try the B<-w> switch first. It
197will often point out exactly where the trouble is.
198
199=head1 DESCRIPTION
200
5f05dabc 201Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
202text files, extracting information from those text files, and printing
203reports based on that information. It's also a good language for many
204system management tasks. The language is intended to be practical
205(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47
PP
206elegant, minimal).
207
aa689395
PP
208Perl combines (in the author's opinion, anyway) some of the best
209features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
210those languages should have little difficulty with it. (Language
211historians will also note some vestiges of B<csh>, Pascal, and even
14218588 212BASIC-PLUS.) Expression syntax corresponds closely to C
a0d0e21e
LW
213expression syntax. Unlike most Unix utilities, Perl does not
214arbitrarily limit the size of your data--if you've got the memory,
aa689395 215Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 216unlimited depth. And the tables used by hashes (sometimes called
aa689395 217"associative arrays") grow as necessary to prevent degraded
0f31cffe 218performance. Perl can use sophisticated pattern matching techniques to
14218588 219scan large amounts of data quickly. Although optimized for
aa689395
PP
220scanning text, Perl can also deal with binary data, and can make dbm
221files look like hashes. Setuid Perl scripts are safer than C programs
14218588 222through a dataflow tracing mechanism that prevents many stupid
aa689395
PP
223security holes.
224
225If you have a problem that would ordinarily use B<sed> or B<awk> or
226B<sh>, but it exceeds their capabilities or must run a little faster,
227and you don't want to write the silly thing in C, then Perl may be for
228you. There are also translators to turn your B<sed> and B<awk>
229scripts into Perl scripts.
a0d0e21e
LW
230
231But wait, there's more...
232
19799a22
GS
233Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
234rewrite that provides the following additional benefits:
a0d0e21e 235
13a2d996 236=over 4
a0d0e21e 237
551e1d92
RB
238=item *
239
240modularity and reusability using innumerable modules
a0d0e21e 241
19799a22 242Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
a0d0e21e 243
551e1d92
RB
244=item *
245
246embeddable and extensible
a0d0e21e 247
19799a22
GS
248Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
249L<perlguts>, and L<xsubpp>.
a0d0e21e 250
551e1d92
RB
251=item *
252
253roll-your-own magic variables (including multiple simultaneous DBM implementations)
a0d0e21e 254
19799a22 255Described in L<perltie> and L<AnyDBM_File>.
a0d0e21e 256
551e1d92
RB
257=item *
258
259subroutines can now be overridden, autoloaded, and prototyped
a0d0e21e 260
19799a22 261Described in L<perlsub>.
a0d0e21e 262
551e1d92
RB
263=item *
264
265arbitrarily nested data structures and anonymous functions
a0d0e21e 266
19799a22 267Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
a0d0e21e 268
551e1d92
RB
269=item *
270
271object-oriented programming
a0d0e21e 272
19799a22 273Described in L<perlobj>, L<perltoot>, and L<perlbot>.
a0d0e21e 274
551e1d92
RB
275=item *
276
277compilability into C code or Perl bytecode
a0d0e21e 278
19799a22 279Described in L<B> and L<B::Bytecode>.
a0d0e21e 280
551e1d92
RB
281=item *
282
283support for light-weight processes (threads)
a0d0e21e 284
19799a22 285Described in L<perlthrtut> and L<Thread>.
a0d0e21e 286
551e1d92
RB
287=item *
288
289support for internationalization, localization, and Unicode
a0d0e21e 290
19799a22 291Described in L<perllocale> and L<utf8>.
a0d0e21e 292
551e1d92
RB
293=item *
294
295lexical scoping
a0d0e21e 296
19799a22 297Described in L<perlsub>.
a0d0e21e 298
551e1d92
RB
299=item *
300
301regular expression enhancements
a0d0e21e 302
19799a22 303Described in L<perlre>, with additional examples in L<perlop>.
a0d0e21e 304
551e1d92
RB
305=item *
306
307enhanced debugger and interactive Perl environment,
308with integrated editor support
a0d0e21e 309
19799a22 310Described in L<perldebug>.
a0d0e21e 311
551e1d92
RB
312=item *
313
314POSIX 1003.1 compliant library
5f05dabc 315
19799a22 316Described in L<POSIX>.
5f05dabc 317
a0d0e21e
LW
318=back
319
68dc0745 320Okay, that's I<definitely> enough hype.
a0d0e21e 321
8e465e4e
JH
322=head1 AVAILABILITY
323
14218588 324Perl is available for most operating systems, including virtually
055fd3a9
GS
325all Unix-like platforms. See L<perlport/"Supported Platforms">
326for a listing.
8bc4a6bb 327
a0d0e21e
LW
328=head1 ENVIRONMENT
329
1e422769 330See L<perlrun>.
a0d0e21e
LW
331
332=head1 AUTHOR
333
19799a22 334Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 335
a99b1639
TP
336If your Perl success stories and testimonials may be of help to others
337who wish to advocate the use of Perl in their applications,
338or if you wish to simply express your gratitude to Larry and the
19799a22 339Perl developers, please write to perl-thanks@perl.org .
a99b1639 340
a0d0e21e
LW
341=head1 FILES
342
5f05dabc 343 "@INC" locations of perl libraries
a0d0e21e
LW
344
345=head1 SEE ALSO
346
347 a2p awk to perl translator
348 s2p sed to perl translator
349
19799a22 350 http://www.perl.com/ the Perl Home Page
5a3e7812 351 http://www.perl.com/CPAN the Comprehensive Perl Archive
19799a22 352
a0d0e21e
LW
353=head1 DIAGNOSTICS
354
9f1b1f2d
GS
355The C<use warnings> pragma (and the B<-w> switch) produces some
356lovely diagnostics.
a0d0e21e 357
5a964f20
TC
358See L<perldiag> for explanations of all Perl's diagnostics. The C<use
359diagnostics> pragma automatically turns Perl's normally terse warnings
360and errors into these longer forms.
a0d0e21e
LW
361
362Compilation errors will tell you the line number of the error, with an
363indication of the next token or token type that was to be examined.
14218588 364(In a script passed to Perl via B<-e> switches, each
a0d0e21e
LW
365B<-e> is counted as one line.)
366
367Setuid scripts have additional constraints that can produce error
368messages such as "Insecure dependency". See L<perlsec>.
369
370Did we mention that you should definitely consider using the B<-w>
371switch?
372
373=head1 BUGS
374
375The B<-w> switch is not mandatory.
376
377Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
378operations such as type casting, atof(), and floating-point
379output with sprintf().
a0d0e21e 380
748a9306 381If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
382particular stream, so does Perl. (This doesn't apply to sysread()
383and syswrite().)
384
385While none of the built-in data types have any arbitrary size limits
386(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
387given variable name may not be longer than 251 characters. Line numbers
388displayed by diagnostics are internally stored as short integers,
389so they are limited to a maximum of 65535 (higher numbers usually being
390affected by wraparound).
a0d0e21e 391
b0607b7a 392You may mail your bug reports (be sure to include full configuration
19799a22 393information as output by the myconfig program in the perl source
7f2de2d2 394tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded
055fd3a9 395in compiling perl, the B<perlbug> script in the F<utils/> subdirectory
19799a22 396can be used to help mail in a bug report.
4633a7c4 397
a0d0e21e
LW
398Perl actually stands for Pathologically Eclectic Rubbish Lister, but
399don't tell anyone I said that.
400
401=head1 NOTES
402
403The Perl motto is "There's more than one way to do it." Divining
404how many more is left as an exercise to the reader.
405
4633a7c4 406The three principal virtues of a programmer are Laziness,
a0d0e21e 407Impatience, and Hubris. See the Camel Book for why.
16d20bd9 408