This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
my $utf8here, our $utf8here, and package variable $utf8here.
[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
34babc16 65 perlpacktut Perl open() 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
fd7b6849
MJD
139=head2 Platform-Specific
140
37d4d706 141 perlaix Perl notes for AIX
a83b6f46
JH
142 perlamiga Perl notes for AmigaOS
143 perlapollo Perl notes for Apollo DomainOS
144 perlbeos Perl notes for BeOS
dc5c060f 145 perlbs2000 Perl notes for POSIX-BC BS2000
a1f19229 146 perlce Perl notes for WinCE
49877630 147 perlcygwin Perl notes for Cygwin
245d750e 148 perldgux Perl notes for DG/UX
49877630 149 perldos Perl notes for DOS
9a997319 150 perlepoc Perl notes for EPOC
49877630 151 perlhpux Perl notes for HP-UX
a83b6f46 152 perlhurd Perl notes for Hurd
da369004 153 perlmachten Perl notes for Power MachTen
26d9b02f 154 perlmacos Perl notes for Mac OS (Classic)
a83b6f46 155 perlmint Perl notes for MiNT
ab648d5e 156 perlmpeix Perl notes for MPE/iX
9038e305 157 perlnetware Perl notes for NetWare
49877630
GS
158 perlos2 Perl notes for OS/2
159 perlos390 Perl notes for OS/390
a83b6f46
JH
160 perlplan9 Perl notes for Plan 9
161 perlqnx Perl notes for QNX
d420ca49 162 perlsolaris Perl notes for Solaris
772ff3b9 163 perltru64 Perl notes for Tru64
91144103 164 perluts Perl notes for UTS
cbe1151c 165 perlvmesa Perl notes for VM/ESA
49877630 166 perlvms Perl notes for VMS
9a997319 167 perlvos Perl notes for Stratus VOS
49877630
GS
168 perlwin32 Perl notes for Windows
169
a0d0e21e 170
19799a22 171By default, the manpages listed above are installed in the
fc952dec
CS
172F</usr/local/man/> directory.
173
174Extensive additional documentation for Perl modules is available. The
175default configuration for perl will place this additional documentation
176in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
177subdirectory of the Perl library directory). Some of this additional
178documentation is distributed standard with Perl, but you'll also find
179documentation for third-party modules there.
180
181You should be able to view Perl's documentation with your man(1)
182program by including the proper directories in the appropriate start-up
183files, or in the MANPATH environment variable. To find out where the
184configuration has installed the manpages, type:
16d20bd9 185
760ac839 186 perl -V:man.dir
16d20bd9 187
fc952dec
CS
188If the directories have a common stem, such as F</usr/local/man/man1>
189and F</usr/local/man/man3>, you need only to add that stem
190(F</usr/local/man>) to your man(1) configuration files or your MANPATH
191environment variable. If they do not share a stem, you'll have to add
192both stems.
16d20bd9
AD
193
194If that doesn't work for some reason, you can still use the
4633a7c4
LW
195supplied F<perldoc> script to view module information. You might
196also look into getting a replacement man program.
16d20bd9 197
a0d0e21e
LW
198If something strange has gone wrong with your program and you're not
199sure where you should look for help, try the B<-w> switch first. It
200will often point out exactly where the trouble is.
201
202=head1 DESCRIPTION
203
5f05dabc 204Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
205text files, extracting information from those text files, and printing
206reports based on that information. It's also a good language for many
207system management tasks. The language is intended to be practical
208(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47
PP
209elegant, minimal).
210
aa689395
PP
211Perl combines (in the author's opinion, anyway) some of the best
212features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
213those languages should have little difficulty with it. (Language
214historians will also note some vestiges of B<csh>, Pascal, and even
14218588 215BASIC-PLUS.) Expression syntax corresponds closely to C
a0d0e21e
LW
216expression syntax. Unlike most Unix utilities, Perl does not
217arbitrarily limit the size of your data--if you've got the memory,
aa689395 218Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 219unlimited depth. And the tables used by hashes (sometimes called
aa689395 220"associative arrays") grow as necessary to prevent degraded
0f31cffe 221performance. Perl can use sophisticated pattern matching techniques to
14218588 222scan large amounts of data quickly. Although optimized for
aa689395
PP
223scanning text, Perl can also deal with binary data, and can make dbm
224files look like hashes. Setuid Perl scripts are safer than C programs
14218588 225through a dataflow tracing mechanism that prevents many stupid
aa689395
PP
226security holes.
227
228If you have a problem that would ordinarily use B<sed> or B<awk> or
229B<sh>, but it exceeds their capabilities or must run a little faster,
230and you don't want to write the silly thing in C, then Perl may be for
231you. There are also translators to turn your B<sed> and B<awk>
232scripts into Perl scripts.
a0d0e21e
LW
233
234But wait, there's more...
235
19799a22
GS
236Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
237rewrite that provides the following additional benefits:
a0d0e21e 238
13a2d996 239=over 4
a0d0e21e 240
551e1d92
RB
241=item *
242
243modularity and reusability using innumerable modules
a0d0e21e 244
19799a22 245Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
a0d0e21e 246
551e1d92
RB
247=item *
248
249embeddable and extensible
a0d0e21e 250
19799a22
GS
251Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
252L<perlguts>, and L<xsubpp>.
a0d0e21e 253
551e1d92
RB
254=item *
255
256roll-your-own magic variables (including multiple simultaneous DBM implementations)
a0d0e21e 257
19799a22 258Described in L<perltie> and L<AnyDBM_File>.
a0d0e21e 259
551e1d92
RB
260=item *
261
262subroutines can now be overridden, autoloaded, and prototyped
a0d0e21e 263
19799a22 264Described in L<perlsub>.
a0d0e21e 265
551e1d92
RB
266=item *
267
268arbitrarily nested data structures and anonymous functions
a0d0e21e 269
19799a22 270Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
a0d0e21e 271
551e1d92
RB
272=item *
273
274object-oriented programming
a0d0e21e 275
f6b3c421
MJD
276Described in L<perlobj>, L<perlboot>, L<perltoot>, L<perltooc>,
277and L<perlbot>.
a0d0e21e 278
551e1d92
RB
279=item *
280
281compilability into C code or Perl bytecode
a0d0e21e 282
19799a22 283Described in L<B> and L<B::Bytecode>.
a0d0e21e 284
551e1d92
RB
285=item *
286
287support for light-weight processes (threads)
a0d0e21e 288
19799a22 289Described in L<perlthrtut> and L<Thread>.
a0d0e21e 290
551e1d92
RB
291=item *
292
293support for internationalization, localization, and Unicode
a0d0e21e 294
19799a22 295Described in L<perllocale> and L<utf8>.
a0d0e21e 296
551e1d92
RB
297=item *
298
299lexical scoping
a0d0e21e 300
19799a22 301Described in L<perlsub>.
a0d0e21e 302
551e1d92
RB
303=item *
304
305regular expression enhancements
a0d0e21e 306
19799a22 307Described in L<perlre>, with additional examples in L<perlop>.
a0d0e21e 308
551e1d92
RB
309=item *
310
311enhanced debugger and interactive Perl environment,
312with integrated editor support
a0d0e21e 313
f6b3c421 314Described in L<perldebtut>, L<perldebug> and L<perldebguts>.
a0d0e21e 315
551e1d92
RB
316=item *
317
318POSIX 1003.1 compliant library
5f05dabc 319
19799a22 320Described in L<POSIX>.
5f05dabc 321
a0d0e21e
LW
322=back
323
68dc0745 324Okay, that's I<definitely> enough hype.
a0d0e21e 325
8e465e4e
JH
326=head1 AVAILABILITY
327
14218588 328Perl is available for most operating systems, including virtually
055fd3a9
GS
329all Unix-like platforms. See L<perlport/"Supported Platforms">
330for a listing.
8bc4a6bb 331
a0d0e21e
LW
332=head1 ENVIRONMENT
333
1e422769 334See L<perlrun>.
a0d0e21e
LW
335
336=head1 AUTHOR
337
19799a22 338Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 339
a99b1639
TP
340If your Perl success stories and testimonials may be of help to others
341who wish to advocate the use of Perl in their applications,
342or if you wish to simply express your gratitude to Larry and the
19799a22 343Perl developers, please write to perl-thanks@perl.org .
a99b1639 344
a0d0e21e
LW
345=head1 FILES
346
5f05dabc 347 "@INC" locations of perl libraries
a0d0e21e
LW
348
349=head1 SEE ALSO
350
351 a2p awk to perl translator
352 s2p sed to perl translator
353
f6b3c421
MJD
354 http://www.perl.com/ the Perl Home Page
355 http://www.cpan.org/ the Comprehensive Perl Archive
356 http://www.perl.org/ Perl Mongers (Perl user groups)
19799a22 357
a0d0e21e
LW
358=head1 DIAGNOSTICS
359
9f1b1f2d
GS
360The C<use warnings> pragma (and the B<-w> switch) produces some
361lovely diagnostics.
a0d0e21e 362
5a964f20
TC
363See L<perldiag> for explanations of all Perl's diagnostics. The C<use
364diagnostics> pragma automatically turns Perl's normally terse warnings
365and errors into these longer forms.
a0d0e21e
LW
366
367Compilation errors will tell you the line number of the error, with an
368indication of the next token or token type that was to be examined.
14218588 369(In a script passed to Perl via B<-e> switches, each
a0d0e21e
LW
370B<-e> is counted as one line.)
371
372Setuid scripts have additional constraints that can produce error
373messages such as "Insecure dependency". See L<perlsec>.
374
375Did we mention that you should definitely consider using the B<-w>
376switch?
377
378=head1 BUGS
379
380The B<-w> switch is not mandatory.
381
382Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
383operations such as type casting, atof(), and floating-point
384output with sprintf().
a0d0e21e 385
748a9306 386If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
387particular stream, so does Perl. (This doesn't apply to sysread()
388and syswrite().)
389
390While none of the built-in data types have any arbitrary size limits
391(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
392given variable name may not be longer than 251 characters. Line numbers
393displayed by diagnostics are internally stored as short integers,
394so they are limited to a maximum of 65535 (higher numbers usually being
395affected by wraparound).
a0d0e21e 396
b0607b7a 397You may mail your bug reports (be sure to include full configuration
19799a22 398information as output by the myconfig program in the perl source
7f2de2d2 399tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded
055fd3a9 400in compiling perl, the B<perlbug> script in the F<utils/> subdirectory
19799a22 401can be used to help mail in a bug report.
4633a7c4 402
a0d0e21e
LW
403Perl actually stands for Pathologically Eclectic Rubbish Lister, but
404don't tell anyone I said that.
405
406=head1 NOTES
407
408The Perl motto is "There's more than one way to do it." Divining
409how many more is left as an exercise to the reader.
410
4633a7c4 411The three principal virtues of a programmer are Laziness,
a0d0e21e 412Impatience, and Hubris. See the Camel Book for why.
16d20bd9 413