This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate with Sarathy.
[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
14218588
GS
15For ease of access, the Perl manual has been split up into several
16sections:
a0d0e21e 17
fb9cefb4
GS
18 perl Perl overview (this section)
19 perldelta Perl changes since previous version
9bc80687
GS
20 perl5005delta Perl changes in version 5.005
21 perl5004delta Perl changes in version 5.004
fb9cefb4
GS
22 perlfaq Perl frequently asked questions
23 perltoc Perl documentation table of contents
760ac839 24
fb9cefb4
GS
25 perldata Perl data structures
26 perlsyn Perl syntax
27 perlop Perl operators and precedence
28 perlre Perl regular expressions
29 perlrun Perl execution and options
30 perlfunc Perl builtin functions
2605996a 31 perlopentut Perl open() tutorial
fb9cefb4
GS
32 perlvar Perl predefined variables
33 perlsub Perl subroutines
34 perlmod Perl modules: how they work
35 perlmodlib Perl modules: how to write and use
36 perlmodinstall Perl modules: how to install from CPAN
37 perlform Perl formats
49877630 38 perlunicode Perl unicode support
fb9cefb4 39 perllocale Perl locale support
760ac839 40
a1e2a320 41 perlreftut Perl references short introduction
19799a22 42 perlref Perl references, the rest of the story
fb9cefb4 43 perldsc Perl data structures intro
19799a22 44 perllol Perl data structures: arrays of arrays
694468e3 45 perlboot Perl OO tutorial for beginners
19799a22
GS
46 perltoot Perl OO tutorial, part 1
47 perltootc Perl OO tutorial, part 2
fb9cefb4
GS
48 perlobj Perl objects
49 perltie Perl objects hidden behind simple variables
50 perlbot Perl OO tricks and examples
51 perlipc Perl interprocess communication
7766f137 52 perlfork Perl fork() information
2605996a 53 perlthrtut Perl threads tutorial
49877630 54 perllexwarn Perl warnings and their control
c93fa817 55 perlfilter Perl source filters
49877630 56 perldbmfilter Perl DBM filters
760ac839 57
54a137f5 58 perlcompile Perl compiler suite intro
fb9cefb4
GS
59 perldebug Perl debugging
60 perldiag Perl diagnostic messages
ac65edd0 61 perlnumber Perl number semantics
fb9cefb4
GS
62 perlsec Perl security
63 perltrap Perl traps for the unwary
64 perlport Perl portability guide
65 perlstyle Perl style guide
760ac839 66
fb9cefb4
GS
67 perlpod Perl plain old documentation
68 perlbook Perl book information
760ac839 69
fb9cefb4
GS
70 perlembed Perl ways to embed perl in your C or C++ application
71 perlapio Perl internal IO abstraction interface
72 perlxs Perl XS application programming interface
73 perlxstut Perl XS tutorial
74 perlguts Perl internal functions for those doing extensions
75 perlcall Perl calling conventions from C
954c1994
GS
76 perlapi Perl API listing (autogenerated)
77 perlintern Perl internal functions (autogenerated)
a0d0e21e 78
e50bb9a1 79 perltodo Perl things to do
e8cd7eae 80 perlhack Perl hackers guide
fb9cefb4 81 perlhist Perl history records
d516a115 82
49877630
GS
83 perlamiga Perl notes for Amiga
84 perlcygwin Perl notes for Cygwin
85 perldos Perl notes for DOS
86 perlhpux Perl notes for HP-UX
87 perlos2 Perl notes for OS/2
88 perlos390 Perl notes for OS/390
89 perlvms Perl notes for VMS
90 perlwin32 Perl notes for Windows
91
a0d0e21e
LW
92(If you're intending to read these straight through for the first time,
93the suggested order will tend to reduce the number of forward references.)
94
19799a22 95By default, the manpages listed above are installed in the
fc952dec
CS
96F</usr/local/man/> directory.
97
98Extensive additional documentation for Perl modules is available. The
99default configuration for perl will place this additional documentation
100in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
101subdirectory of the Perl library directory). Some of this additional
102documentation is distributed standard with Perl, but you'll also find
103documentation for third-party modules there.
104
105You should be able to view Perl's documentation with your man(1)
106program by including the proper directories in the appropriate start-up
107files, or in the MANPATH environment variable. To find out where the
108configuration has installed the manpages, type:
16d20bd9 109
760ac839 110 perl -V:man.dir
16d20bd9 111
fc952dec
CS
112If the directories have a common stem, such as F</usr/local/man/man1>
113and F</usr/local/man/man3>, you need only to add that stem
114(F</usr/local/man>) to your man(1) configuration files or your MANPATH
115environment variable. If they do not share a stem, you'll have to add
116both stems.
16d20bd9
AD
117
118If that doesn't work for some reason, you can still use the
4633a7c4
LW
119supplied F<perldoc> script to view module information. You might
120also look into getting a replacement man program.
16d20bd9 121
a0d0e21e
LW
122If something strange has gone wrong with your program and you're not
123sure where you should look for help, try the B<-w> switch first. It
124will often point out exactly where the trouble is.
125
126=head1 DESCRIPTION
127
5f05dabc 128Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
129text files, extracting information from those text files, and printing
130reports based on that information. It's also a good language for many
131system management tasks. The language is intended to be practical
132(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47 133elegant, minimal).
134
aa689395 135Perl combines (in the author's opinion, anyway) some of the best
136features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
137those languages should have little difficulty with it. (Language
138historians will also note some vestiges of B<csh>, Pascal, and even
14218588 139BASIC-PLUS.) Expression syntax corresponds closely to C
a0d0e21e
LW
140expression syntax. Unlike most Unix utilities, Perl does not
141arbitrarily limit the size of your data--if you've got the memory,
aa689395 142Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 143unlimited depth. And the tables used by hashes (sometimes called
aa689395 144"associative arrays") grow as necessary to prevent degraded
0f31cffe 145performance. Perl can use sophisticated pattern matching techniques to
14218588 146scan large amounts of data quickly. Although optimized for
aa689395 147scanning text, Perl can also deal with binary data, and can make dbm
148files look like hashes. Setuid Perl scripts are safer than C programs
14218588 149through a dataflow tracing mechanism that prevents many stupid
aa689395 150security holes.
151
152If you have a problem that would ordinarily use B<sed> or B<awk> or
153B<sh>, but it exceeds their capabilities or must run a little faster,
154and you don't want to write the silly thing in C, then Perl may be for
155you. There are also translators to turn your B<sed> and B<awk>
156scripts into Perl scripts.
a0d0e21e
LW
157
158But wait, there's more...
159
19799a22
GS
160Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
161rewrite that provides the following additional benefits:
a0d0e21e 162
19799a22 163=over
a0d0e21e 164
19799a22 165=item * modularity and reusability using innumerable modules
a0d0e21e 166
19799a22 167Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
a0d0e21e 168
19799a22 169=item * embeddable and extensible
a0d0e21e 170
19799a22
GS
171Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
172L<perlguts>, and L<xsubpp>.
a0d0e21e 173
19799a22 174=item * roll-your-own magic variables (including multiple simultaneous DBM implementations)
a0d0e21e 175
19799a22 176Described in L<perltie> and L<AnyDBM_File>.
a0d0e21e 177
19799a22 178=item * subroutines can now be overridden, autoloaded, and prototyped
a0d0e21e 179
19799a22 180Described in L<perlsub>.
a0d0e21e 181
19799a22 182=item * arbitrarily nested data structures and anonymous functions
a0d0e21e 183
19799a22 184Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
a0d0e21e 185
19799a22 186=item * object-oriented programming
a0d0e21e 187
19799a22 188Described in L<perlobj>, L<perltoot>, and L<perlbot>.
a0d0e21e 189
19799a22 190=item * compilability into C code or Perl bytecode
a0d0e21e 191
19799a22 192Described in L<B> and L<B::Bytecode>.
a0d0e21e 193
19799a22 194=item * support for light-weight processes (threads)
a0d0e21e 195
19799a22 196Described in L<perlthrtut> and L<Thread>.
a0d0e21e 197
19799a22 198=item * support for internationalization, localization, and Unicode
a0d0e21e 199
19799a22 200Described in L<perllocale> and L<utf8>.
a0d0e21e 201
19799a22 202=item * lexical scoping
a0d0e21e 203
19799a22 204Described in L<perlsub>.
a0d0e21e 205
19799a22 206=item * regular expression enhancements
a0d0e21e 207
19799a22 208Described in L<perlre>, with additional examples in L<perlop>.
a0d0e21e 209
14218588 210=item * enhanced debugger and interactive Perl environment, with integrated editor support
a0d0e21e 211
19799a22 212Described in L<perldebug>.
a0d0e21e 213
19799a22 214=item * POSIX 1003.1 compliant library
5f05dabc 215
19799a22 216Described in L<POSIX>.
5f05dabc 217
a0d0e21e
LW
218=back
219
68dc0745 220Okay, that's I<definitely> enough hype.
a0d0e21e 221
8e465e4e
JH
222=head1 AVAILABILITY
223
14218588
GS
224Perl is available for most operating systems, including virtually
225all Unix-like platforms.
8e465e4e 226
14218588
GS
227As of May 1999, the following platforms are able to build Perl
228from the standard source code distribution available at
19799a22 229http://www.perl.com/CPAN/src/index.html
8e465e4e 230
58493fc4
JH
231 AIX Linux SCO ODT/OSR
232 A/UX MachTen Solaris
233 BeOS MPE/iX SunOS
234 BSD/OS NetBSD SVR4
235 DG/UX NextSTEP Tru64 UNIX 3)
236 DomainOS OpenBSD Ultrix
237 DOS DJGPP 1) OpenSTEP UNICOS
238 DYNIX/ptx OS/2 VMS
239 FreeBSD OS390 2) VOS
240 HP-UX PowerMAX Windows 3.1 1)
241 Hurd QNX Windows 95 1) 4)
242 IRIX Windows 98 1) 4)
243 Windows NT 1) 4)
8e465e4e
JH
244
245 1) in DOS mode either the DOS or OS/2 ports can be used
58493fc4
JH
246 2) formerly known as MVS
247 3) formerly known as Digital UNIX and before that DEC OSF/1
873b149f 248 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++
c47ff5f1 249
14218588
GS
250The following platforms have been known to build Perl from source,
251but we haven't been able to verify their status for the current release,
252either because the hardware/software platforms are rare or
19799a22 253because we don't have an active champion on these platforms--or both.
c47ff5f1 254
8e465e4e 255 3b1 FPS Plan 9
04251ce8
JH
256 AmigaOS GENIX PowerUX
257 ConvexOS Greenhills RISC/os
258 CX/UX ISC Stellar
259 DC/OSx MachTen 68k SVR2
260 DDE SMES MiNT TI1500
82cda36e
JH
261 DOS EMX MPC TitanOS
262 Dynix NEWS-OS UNICOS/mk
263 EP/IX Opus Unisys Dynix
264 ESIX Unixware
8e465e4e 265
14218588
GS
266Support for the following platforms is planned for the next major
267Perl release.
8e465e4e
JH
268
269 BS2000
00ad96e1
JH
270 Netware
271 Rhapsody
8e465e4e
JH
272 VM/ESA
273
274The following platforms have their own source code distributions and
19799a22 275binaries available via http://www.perl.com/CPAN/ports/index.html.
8e465e4e
JH
276
277 Perl release
278
279 AS/400 5.003
2e04d155 280 MacOS 5.004
04251ce8 281 Netware 5.003_07
8e465e4e
JH
282 Tandem Guardian 5.004
283
284The following platforms have only binaries available via
19799a22 285http://www.perl.com/CPAN/ports/index.html.
8e465e4e
JH
286
287 Perl release
288
d845c4a6 289 Acorn RISCOS 5.005_02
8e465e4e
JH
290 AOS 5.002
291 LynxOS 5.004_02
8e465e4e 292
a0d0e21e
LW
293=head1 ENVIRONMENT
294
1e422769 295See L<perlrun>.
a0d0e21e
LW
296
297=head1 AUTHOR
298
19799a22 299Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 300
a99b1639
TP
301If your Perl success stories and testimonials may be of help to others
302who wish to advocate the use of Perl in their applications,
303or if you wish to simply express your gratitude to Larry and the
19799a22 304Perl developers, please write to perl-thanks@perl.org .
a99b1639 305
a0d0e21e
LW
306=head1 FILES
307
5f05dabc 308 "@INC" locations of perl libraries
a0d0e21e
LW
309
310=head1 SEE ALSO
311
312 a2p awk to perl translator
313 s2p sed to perl translator
314
19799a22 315 http://www.perl.com/ the Perl Home Page
5a3e7812 316 http://www.perl.com/CPAN the Comprehensive Perl Archive
19799a22 317
a0d0e21e
LW
318=head1 DIAGNOSTICS
319
320The B<-w> switch produces some lovely diagnostics.
321
5a964f20
TC
322See L<perldiag> for explanations of all Perl's diagnostics. The C<use
323diagnostics> pragma automatically turns Perl's normally terse warnings
324and errors into these longer forms.
a0d0e21e
LW
325
326Compilation errors will tell you the line number of the error, with an
327indication of the next token or token type that was to be examined.
14218588 328(In a script passed to Perl via B<-e> switches, each
a0d0e21e
LW
329B<-e> is counted as one line.)
330
331Setuid scripts have additional constraints that can produce error
332messages such as "Insecure dependency". See L<perlsec>.
333
334Did we mention that you should definitely consider using the B<-w>
335switch?
336
337=head1 BUGS
338
339The B<-w> switch is not mandatory.
340
341Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
342operations such as type casting, atof(), and floating-point
343output with sprintf().
a0d0e21e 344
748a9306 345If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
346particular stream, so does Perl. (This doesn't apply to sysread()
347and syswrite().)
348
349While none of the built-in data types have any arbitrary size limits
350(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
351given variable name may not be longer than 251 characters. Line numbers
352displayed by diagnostics are internally stored as short integers,
353so they are limited to a maximum of 65535 (higher numbers usually being
354affected by wraparound).
a0d0e21e 355
b0607b7a 356You may mail your bug reports (be sure to include full configuration
19799a22
GS
357information as output by the myconfig program in the perl source
358tree, or by C<perl -V>) to perlbug@perl.com . If you've succeeded
359in compiling perl, the perlbug script in the utils/ subdirectory
360can be used to help mail in a bug report.
4633a7c4 361
a0d0e21e
LW
362Perl actually stands for Pathologically Eclectic Rubbish Lister, but
363don't tell anyone I said that.
364
365=head1 NOTES
366
367The Perl motto is "There's more than one way to do it." Divining
368how many more is left as an exercise to the reader.
369
4633a7c4 370The three principal virtues of a programmer are Laziness,
a0d0e21e 371Impatience, and Hubris. See the Camel Book for why.
16d20bd9 372