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