1=head1 NAME 2 3perl - Practical Extraction and Report Language 4 5=head1 SYNOPSIS 6 7B<perl> S<[ B<-sTtuUWX> ]> 8 S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]> 9 S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]> 10 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]> 11 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]> 12 S<[ B<-C [I<number/list>] >]> 13 S<[ B<-P> ]> 14 S<[ B<-S> ]> 15 S<[ B<-x>[I<dir>] ]> 16 S<[ B<-i>[I<extension>] ]> 17 S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...> 18 19If you're new to Perl, you should start with L<perlintro>, which is a 20general intro for beginners and provides some background to help you 21navigate the rest of Perl's extensive documentation. 22 23For ease of access, the Perl manual has been split up into several sections. 24 25=head2 Overview 26 27 perl Perl overview (this section) 28 perlintro Perl introduction for beginners 29 perltoc Perl documentation table of contents 30 31=head2 Tutorials 32 33 perlreftut Perl references short introduction 34 perldsc Perl data structures intro 35 perllol Perl data structures: arrays of arrays 36 37 perlrequick Perl regular expressions quick start 38 perlretut Perl regular expressions tutorial 39 40 perlboot Perl OO tutorial for beginners 41 perltoot Perl OO tutorial, part 1 42 perltooc Perl OO tutorial, part 2 43 perlbot Perl OO tricks and examples 44 45 perlstyle Perl style guide 46 47 perlcheat Perl cheat sheet 48 perltrap Perl traps for the unwary 49 perldebtut Perl debugging tutorial 50 51 perlfaq Perl frequently asked questions 52 perlfaq1 General Questions About Perl 53 perlfaq2 Obtaining and Learning about Perl 54 perlfaq3 Programming Tools 55 perlfaq4 Data Manipulation 56 perlfaq5 Files and Formats 57 perlfaq6 Regexes 58 perlfaq7 Perl Language Issues 59 perlfaq8 System Interaction 60 perlfaq9 Networking 61 62=head2 Reference Manual 63 64 perlsyn Perl syntax 65 perldata Perl data structures 66 perlop Perl operators and precedence 67 perlsub Perl subroutines 68 perlfunc Perl built-in functions 69 perlopentut Perl open() tutorial 70 perlpacktut Perl pack() and unpack() tutorial 71 perlpod Perl plain old documentation 72 perlpodspec Perl plain old documentation format specification 73 perlrun Perl execution and options 74 perldiag Perl diagnostic messages 75 perllexwarn Perl warnings and their control 76 perldebug Perl debugging 77 perlvar Perl predefined variables 78 perlre Perl regular expressions, the rest of the story 79 perlrebackslash Perl regular expression backslash sequences 80 perlrecharclass Perl regular expression character classes 81 perlreref Perl regular expressions quick reference 82 perlref Perl references, the rest of the story 83 perlform Perl formats 84 perlobj Perl objects 85 perltie Perl objects hidden behind simple variables 86 perldbmfilter Perl DBM filters 87 88 perlipc Perl interprocess communication 89 perlfork Perl fork() information 90 perlnumber Perl number semantics 91 92 perlthrtut Perl threads tutorial 93 perlothrtut Old Perl threads tutorial 94 95 perlport Perl portability guide 96 perllocale Perl locale support 97 perluniintro Perl Unicode introduction 98 perlunicode Perl Unicode support 99 perlunifaq Perl Unicode FAQ 100 perlunitut Perl Unicode tutorial 101 perlebcdic Considerations for running Perl on EBCDIC platforms 102 103 perlsec Perl security 104 105 perlmod Perl modules: how they work 106 perlmodlib Perl modules: how to write and use 107 perlmodstyle Perl modules: how to write modules with style 108 perlmodinstall Perl modules: how to install from CPAN 109 perlnewmod Perl modules: preparing a new module for distribution 110 perlpragma Perl modules: writing a user pragma 111 112 perlutil utilities packaged with the Perl distribution 113 114 perlcompile Perl compiler suite intro 115 116 perlfilter Perl source filters 117 118 perlglossary Perl Glossary 119 120=head2 Internals and C Language Interface 121 122 perlembed Perl ways to embed perl in your C or C++ application 123 perldebguts Perl debugging guts and tips 124 perlxstut Perl XS tutorial 125 perlxs Perl XS application programming interface 126 perlclib Internal replacements for standard C library functions 127 perlguts Perl internal functions for those doing extensions 128 perlcall Perl calling conventions from C 129 perlreapi Perl regular expression plugin interface 130 perlreguts Perl regular expression engine internals 131 132 perlapi Perl API listing (autogenerated) 133 perlintern Perl internal functions (autogenerated) 134 perliol C API for Perl's implementation of IO in Layers 135 perlapio Perl internal IO abstraction interface 136 137 perlhack Perl hackers guide 138 139=head2 Miscellaneous 140 141 perlbook Perl book information 142 perlcommunity Perl community information 143 perltodo Perl things to do 144 145 perldoc Look up Perl documentation in Pod format 146 147 perlhist Perl history records 148 perldelta Perl changes since previous version 149 perl595delta Perl changes in version 5.9.5 150 perl594delta Perl changes in version 5.9.4 151 perl593delta Perl changes in version 5.9.3 152 perl592delta Perl changes in version 5.9.2 153 perl591delta Perl changes in version 5.9.1 154 perl590delta Perl changes in version 5.9.0 155 perl588delta Perl changes in version 5.8.8 156 perl587delta Perl changes in version 5.8.7 157 perl586delta Perl changes in version 5.8.6 158 perl585delta Perl changes in version 5.8.5 159 perl584delta Perl changes in version 5.8.4 160 perl583delta Perl changes in version 5.8.3 161 perl582delta Perl changes in version 5.8.2 162 perl581delta Perl changes in version 5.8.1 163 perl58delta Perl changes in version 5.8.0 164 perl573delta Perl changes in version 5.7.3 165 perl572delta Perl changes in version 5.7.2 166 perl571delta Perl changes in version 5.7.1 167 perl570delta Perl changes in version 5.7.0 168 perl561delta Perl changes in version 5.6.1 169 perl56delta Perl changes in version 5.6 170 perl5005delta Perl changes in version 5.005 171 perl5004delta Perl changes in version 5.004 172 173 perlartistic Perl Artistic License 174 perlgpl GNU General Public License 175 176=head2 Language-Specific 177 178 perlcn Perl for Simplified Chinese (in EUC-CN) 179 perljp Perl for Japanese (in EUC-JP) 180 perlko Perl for Korean (in EUC-KR) 181 perltw Perl for Traditional Chinese (in Big5) 182 183=head2 Platform-Specific 184 185 perlaix Perl notes for AIX 186 perlamiga Perl notes for AmigaOS 187 perlapollo Perl notes for Apollo DomainOS 188 perlbeos Perl notes for BeOS 189 perlbs2000 Perl notes for POSIX-BC BS2000 190 perlce Perl notes for WinCE 191 perlcygwin Perl notes for Cygwin 192 perldgux Perl notes for DG/UX 193 perldos Perl notes for DOS 194 perlepoc Perl notes for EPOC 195 perlfreebsd Perl notes for FreeBSD 196 perlhpux Perl notes for HP-UX 197 perlhurd Perl notes for Hurd 198 perlirix Perl notes for Irix 199 perllinux Perl notes for Linux 200 perlmachten Perl notes for Power MachTen 201 perlmacos Perl notes for Mac OS (Classic) 202 perlmacosx Perl notes for Mac OS X 203 perlmint Perl notes for MiNT 204 perlmpeix Perl notes for MPE/iX 205 perlnetware Perl notes for NetWare 206 perlopenbsd Perl notes for OpenBSD 207 perlos2 Perl notes for OS/2 208 perlos390 Perl notes for OS/390 209 perlos400 Perl notes for OS/400 210 perlplan9 Perl notes for Plan 9 211 perlqnx Perl notes for QNX 212 perlriscos Perl notes for RISC OS 213 perlsolaris Perl notes for Solaris 214 perlsymbian Perl notes for Symbian 215 perltru64 Perl notes for Tru64 216 perluts Perl notes for UTS 217 perlvmesa Perl notes for VM/ESA 218 perlvms Perl notes for VMS 219 perlvos Perl notes for Stratus VOS 220 perlwin32 Perl notes for Windows 221 222 223By default, the manpages listed above are installed in the 224F</usr/local/man/> directory. 225 226Extensive additional documentation for Perl modules is available. The 227default configuration for perl will place this additional documentation 228in the F</usr/local/lib/perl5/man> directory (or else in the F<man> 229subdirectory of the Perl library directory). Some of this additional 230documentation is distributed standard with Perl, but you'll also find 231documentation for third-party modules there. 232 233You should be able to view Perl's documentation with your man(1) 234program by including the proper directories in the appropriate start-up 235files, or in the MANPATH environment variable. To find out where the 236configuration has installed the manpages, type: 237 238 perl -V:man.dir 239 240If the directories have a common stem, such as F</usr/local/man/man1> 241and F</usr/local/man/man3>, you need only to add that stem 242(F</usr/local/man>) to your man(1) configuration files or your MANPATH 243environment variable. If they do not share a stem, you'll have to add 244both stems. 245 246If that doesn't work for some reason, you can still use the 247supplied F<perldoc> script to view module information. You might 248also look into getting a replacement man program. 249 250If something strange has gone wrong with your program and you're not 251sure where you should look for help, try the B<-w> switch first. It 252will often point out exactly where the trouble is. 253 254=head1 DESCRIPTION 255 256Perl is a language optimized for scanning arbitrary 257text files, extracting information from those text files, and printing 258reports based on that information. It's also a good language for many 259system management tasks. The language is intended to be practical 260(easy to use, efficient, complete) rather than beautiful (tiny, 261elegant, minimal). 262 263Perl combines (in the author's opinion, anyway) some of the best 264features of C, B<sed>, B<awk>, and B<sh>, so people familiar with 265those languages should have little difficulty with it. (Language 266historians will also note some vestiges of B<csh>, Pascal, and even 267BASIC-PLUS.) Expression syntax corresponds closely to C 268expression syntax. Unlike most Unix utilities, Perl does not 269arbitrarily limit the size of your data--if you've got the memory, 270Perl can slurp in your whole file as a single string. Recursion is of 271unlimited depth. And the tables used by hashes (sometimes called 272"associative arrays") grow as necessary to prevent degraded 273performance. Perl can use sophisticated pattern matching techniques to 274scan large amounts of data quickly. Although optimized for 275scanning text, Perl can also deal with binary data, and can make dbm 276files look like hashes. Setuid Perl scripts are safer than C programs 277through a dataflow tracing mechanism that prevents many stupid 278security holes. 279 280If you have a problem that would ordinarily use B<sed> or B<awk> or 281B<sh>, but it exceeds their capabilities or must run a little faster, 282and you don't want to write the silly thing in C, then Perl may be for 283you. There are also translators to turn your B<sed> and B<awk> 284scripts into Perl scripts. 285 286But wait, there's more... 287 288Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete 289rewrite that provides the following additional benefits: 290 291=over 4 292 293=item * 294 295modularity and reusability using innumerable modules 296 297Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>. 298 299=item * 300 301embeddable and extensible 302 303Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>, 304L<perlguts>, and L<xsubpp>. 305 306=item * 307 308roll-your-own magic variables (including multiple simultaneous DBM 309implementations) 310 311Described in L<perltie> and L<AnyDBM_File>. 312 313=item * 314 315subroutines can now be overridden, autoloaded, and prototyped 316 317Described in L<perlsub>. 318 319=item * 320 321arbitrarily nested data structures and anonymous functions 322 323Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>. 324 325=item * 326 327object-oriented programming 328 329Described in L<perlobj>, L<perlboot>, L<perltoot>, L<perltooc>, 330and L<perlbot>. 331 332=item * 333 334support for light-weight processes (threads) 335 336Described in L<perlthrtut> and L<threads>. 337 338=item * 339 340support for Unicode, internationalization, and localization 341 342Described in L<perluniintro>, L<perllocale> and L<Locale::Maketext>. 343 344=item * 345 346lexical scoping 347 348Described in L<perlsub>. 349 350=item * 351 352regular expression enhancements 353 354Described in L<perlre>, with additional examples in L<perlop>. 355 356=item * 357 358enhanced debugger and interactive Perl environment, 359with integrated editor support 360 361Described in L<perldebtut>, L<perldebug> and L<perldebguts>. 362 363=item * 364 365POSIX 1003.1 compliant library 366 367Described in L<POSIX>. 368 369=back 370 371Okay, that's I<definitely> enough hype. 372 373=head1 AVAILABILITY 374 375Perl is available for most operating systems, including virtually 376all Unix-like platforms. See L<perlport/"Supported Platforms"> 377for a listing. 378 379=head1 ENVIRONMENT 380 381See L<perlrun>. 382 383=head1 AUTHOR 384 385Larry Wall <larry@wall.org>, with the help of oodles of other folks. 386 387If your Perl success stories and testimonials may be of help to others 388who wish to advocate the use of Perl in their applications, 389or if you wish to simply express your gratitude to Larry and the 390Perl developers, please write to perl-thanks@perl.org . 391 392=head1 FILES 393 394 "@INC" locations of perl libraries 395 396=head1 SEE ALSO 397 398 a2p awk to perl translator 399 s2p sed to perl translator 400 401 http://www.perl.org/ the Perl homepage 402 http://www.perl.com/ Perl articles (O'Reilly) 403 http://www.cpan.org/ the Comprehensive Perl Archive 404 http://www.pm.org/ the Perl Mongers 405 406=head1 DIAGNOSTICS 407 408The C<use warnings> pragma (and the B<-w> switch) produces some 409lovely diagnostics. 410 411See L<perldiag> for explanations of all Perl's diagnostics. The C<use 412diagnostics> pragma automatically turns Perl's normally terse warnings 413and errors into these longer forms. 414 415Compilation errors will tell you the line number of the error, with an 416indication of the next token or token type that was to be examined. 417(In a script passed to Perl via B<-e> switches, each 418B<-e> is counted as one line.) 419 420Setuid scripts have additional constraints that can produce error 421messages such as "Insecure dependency". See L<perlsec>. 422 423Did we mention that you should definitely consider using the B<-w> 424switch? 425 426=head1 BUGS 427 428The B<-w> switch is not mandatory. 429 430Perl is at the mercy of your machine's definitions of various 431operations such as type casting, atof(), and floating-point 432output with sprintf(). 433 434If your stdio requires a seek or eof between reads and writes on a 435particular stream, so does Perl. (This doesn't apply to sysread() 436and syswrite().) 437 438While none of the built-in data types have any arbitrary size limits 439(apart from memory size), there are still a few arbitrary limits: a 440given variable name may not be longer than 251 characters. Line numbers 441displayed by diagnostics are internally stored as short integers, 442so they are limited to a maximum of 65535 (higher numbers usually being 443affected by wraparound). 444 445You may mail your bug reports (be sure to include full configuration 446information as output by the myconfig program in the perl source 447tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded 448in compiling perl, the B<perlbug> script in the F<utils/> subdirectory 449can be used to help mail in a bug report. 450 451Perl actually stands for Pathologically Eclectic Rubbish Lister, but 452don't tell anyone I said that. 453 454=head1 NOTES 455 456The Perl motto is "There's more than one way to do it." Divining 457how many more is left as an exercise to the reader. 458 459The three principal virtues of a programmer are Laziness, 460Impatience, and Hubris. See the Camel Book for why. 461 462