This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
assuming that removing the libbind will be a good idea
[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
PP
133elegant, minimal).
134
aa689395
PP
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
PP
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
PP
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
fb533e5b
JH
227As of early March 2000 (the Perl release 5.6.0), the following
228platforms are able to build Perl from the standard source code
229distribution available at http://www.perl.com/CPAN/src/index.html
230
231 AIX
232 DOS DJGPP 1)
233 FreeBSD
234 HP-UX
235 IRIX
236 Linux
237 MachTen
238 MPE/iX
239 NetBSD
240 OpenBSD
241 OS/2
242 Rhapsody/Darwin 2)
243 Solaris
244 Tru64 UNIX 3)
245 UNICOS
246 UNICOS/mk
247 VMS
248 VOS
249 Windows 3.1 1)
250 Windows 95 1) 4)
251 Windows 98 1) 4)
252 Windows NT 1) 4)
8e465e4e
JH
253
254 1) in DOS mode either the DOS or OS/2 ports can be used
c6018dae 255 2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X
fb533e5b 256 3) formerly known as Digital UNIX and before that DEC OSF/1
873b149f 257 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++
c47ff5f1 258
c6018dae
GS
259The following platforms worked for the previous major release (5.005_03
260being the latest maintenance release of that, as of March 2000), but we
261did not manage to test these in time for the 5.6.0 release of Perl.
fb533e5b
JH
262There is a very good chance that these will work just fine with 5.6.0.
263
264 A/UX
265 BeOS
266 BSD/OS
267 DG/UX
268 DYNIX/ptx
269 DomainOS
270 Hurd
271 NextSTEP
272 OpenSTEP
273 PowerMAX
274 QNX
275 SCO ODT/OSR
276 SunOS
277 SVR4
278 Ultrix
279
c6018dae
GS
280The following platform worked for the previous major release (5.005_03
281being the latest maintenance release of that, as of March 2000).
282However, standardization on UTF-8 as the internal string representation
283in 5.6.0 has introduced incompatibilities with this EBCDIC platform.
284Support for this platform may be enabled in a future release:
fb533e5b
JH
285
286 OS390 1)
287
288 1) Previously known as MVS, or OpenEdition MVS.
289
290Strongly related to the OS390 platform by also being EBCDIC-based
c6018dae 291mainframe platforms are the following platforms:
fb533e5b
JH
292
293 BS2000
294 VM/ESA
295
c6018dae
GS
296These are also not expected to work under 5.6.0 for the same reasons
297as OS390. Contact the mailing list perl-mvs@perl.org for more details.
fb533e5b 298
c6018dae
GS
299MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source
300does work with 5.6.0, but additional MacOS specific source code is needed
301for a complete port. Contact the mailing list macperl-porters@macperl.org
fb533e5b
JH
302for more more information.
303
304The following platforms have been known to build Perl from source in
305the past, but we haven't been able to verify their status for the
306current release, either because the hardware/software platforms are
307rare or because we don't have an active champion on these
c6018dae 308platforms--or both:
fb533e5b
JH
309
310 3b1
311 AmigaOS
312 ConvexOS
313 CX/UX
314 DC/OSx
315 DDE SMES
316 DOS EMX
317 Dynix
318 EP/IX
319 ESIX
320 FPS
321 GENIX
322 Greenhills
323 ISC
324 MachTen 68k
325 MiNT
326 MPC
327 NEWS-OS
328 Opus
329 Plan 9
330 PowerUX
331 RISC/os
332 Stellar
333 SVR2
334 TI1500
335 TitanOS
336 Unisys Dynix
337 Unixware
338
c6018dae 339Support for the following platform is planned for a future Perl release:
fb533e5b 340
00ad96e1 341 Netware
8e465e4e
JH
342
343The following platforms have their own source code distributions and
c6018dae 344binaries available via http://www.perl.com/CPAN/ports/index.html :
8e465e4e
JH
345
346 Perl release
347
348 AS/400 5.003
04251ce8 349 Netware 5.003_07
8e465e4e
JH
350 Tandem Guardian 5.004
351
352The following platforms have only binaries available via
c6018dae 353http://www.perl.com/CPAN/ports/index.html :
8e465e4e
JH
354
355 Perl release
356
d845c4a6 357 Acorn RISCOS 5.005_02
8e465e4e
JH
358 AOS 5.002
359 LynxOS 5.004_02
8e465e4e 360
a0d0e21e
LW
361=head1 ENVIRONMENT
362
1e422769 363See L<perlrun>.
a0d0e21e
LW
364
365=head1 AUTHOR
366
19799a22 367Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 368
a99b1639
TP
369If your Perl success stories and testimonials may be of help to others
370who wish to advocate the use of Perl in their applications,
371or if you wish to simply express your gratitude to Larry and the
19799a22 372Perl developers, please write to perl-thanks@perl.org .
a99b1639 373
a0d0e21e
LW
374=head1 FILES
375
5f05dabc 376 "@INC" locations of perl libraries
a0d0e21e
LW
377
378=head1 SEE ALSO
379
380 a2p awk to perl translator
381 s2p sed to perl translator
382
19799a22 383 http://www.perl.com/ the Perl Home Page
5a3e7812 384 http://www.perl.com/CPAN the Comprehensive Perl Archive
19799a22 385
a0d0e21e
LW
386=head1 DIAGNOSTICS
387
388The B<-w> switch produces some lovely diagnostics.
389
5a964f20
TC
390See L<perldiag> for explanations of all Perl's diagnostics. The C<use
391diagnostics> pragma automatically turns Perl's normally terse warnings
392and errors into these longer forms.
a0d0e21e
LW
393
394Compilation errors will tell you the line number of the error, with an
395indication of the next token or token type that was to be examined.
14218588 396(In a script passed to Perl via B<-e> switches, each
a0d0e21e
LW
397B<-e> is counted as one line.)
398
399Setuid scripts have additional constraints that can produce error
400messages such as "Insecure dependency". See L<perlsec>.
401
402Did we mention that you should definitely consider using the B<-w>
403switch?
404
405=head1 BUGS
406
407The B<-w> switch is not mandatory.
408
409Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
410operations such as type casting, atof(), and floating-point
411output with sprintf().
a0d0e21e 412
748a9306 413If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
414particular stream, so does Perl. (This doesn't apply to sysread()
415and syswrite().)
416
417While none of the built-in data types have any arbitrary size limits
418(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
419given variable name may not be longer than 251 characters. Line numbers
420displayed by diagnostics are internally stored as short integers,
421so they are limited to a maximum of 65535 (higher numbers usually being
422affected by wraparound).
a0d0e21e 423
b0607b7a 424You may mail your bug reports (be sure to include full configuration
19799a22
GS
425information as output by the myconfig program in the perl source
426tree, or by C<perl -V>) to perlbug@perl.com . If you've succeeded
427in compiling perl, the perlbug script in the utils/ subdirectory
428can be used to help mail in a bug report.
4633a7c4 429
a0d0e21e
LW
430Perl actually stands for Pathologically Eclectic Rubbish Lister, but
431don't tell anyone I said that.
432
433=head1 NOTES
434
435The Perl motto is "There's more than one way to do it." Divining
436how many more is left as an exercise to the reader.
437
4633a7c4 438The three principal virtues of a programmer are Laziness,
a0d0e21e 439Impatience, and Hubris. See the Camel Book for why.
16d20bd9 440