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