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