This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
avoid warnings in diagnostics.pm; pod tweaks (from Peter Prymmer
[perl5.git] / pod / perlrun.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlrun - how to execute the Perl interpreter
4
5=head1 SYNOPSIS
6
46487f74 7B<perl> S<[ B<-CsTuUWX> ]>
e0ebc809
PP
8 S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
9 S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
10 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
11 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
12 S<[ B<-P> ]>
13 S<[ B<-S> ]>
14 S<[ B<-x>[I<dir>] ]>
15 S<[ B<-i>[I<extension>] ]>
16 S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
a0d0e21e
LW
17
18=head1 DESCRIPTION
19
19799a22
GS
20The normal way to run a Perl program is by making it directly
21executable, or else by passing the name of the source file as an
22argument on the command line. (An interactive Perl environment
23is also possible--see L<perldebug> for details on how to do that.)
24Upon startup, Perl looks for your program in one of the following
a0d0e21e
LW
25places:
26
27=over 4
28
29=item 1.
30
31Specified line by line via B<-e> switches on the command line.
32
33=item 2.
34
35Contained in the file specified by the first filename on the command line.
a3cb178b
GS
36(Note that systems supporting the #! notation invoke interpreters this
37way. See L<Location of Perl>.)
a0d0e21e
LW
38
39=item 3.
40
5f05dabc 41Passed in implicitly via standard input. This works only if there are
19799a22
GS
42no filename arguments--to pass arguments to a STDIN-read program you
43must explicitly specify a "-" for the program name.
a0d0e21e
LW
44
45=back
46
47With methods 2 and 3, Perl starts parsing the input file from the
48beginning, unless you've specified a B<-x> switch, in which case it
49scans for the first line starting with #! and containing the word
19799a22 50"perl", and starts there instead. This is useful for running a program
a0d0e21e 51embedded in a larger message. (In this case you would indicate the end
19799a22 52of the program using the C<__END__> token.)
a0d0e21e 53
5f05dabc
PP
54The #! line is always examined for switches as the line is being
55parsed. Thus, if you're on a machine that allows only one argument
56with the #! line, or worse, doesn't even recognize the #! line, you
57still can get consistent switch behavior regardless of how Perl was
19799a22
GS
58invoked, even if B<-x> was used to find the beginning of the program.
59
60Because historically some operating systems silently chopped off
61kernel interpretation of the #! line after 32 characters, some
62switches may be passed in on the command line, and some may not;
63you could even get a "-" without its letter, if you're not careful.
64You probably want to make sure that all your switches fall either
65before or after that 32-character boundary. Most switches don't
66actually care if they're processed redundantly, but getting a "-"
67instead of a complete switch could cause Perl to try to execute
68standard input instead of your program. And a partial B<-I> switch
a0d0e21e
LW
69could also cause odd results.
70
19799a22
GS
71Some switches do care if they are processed twice, for instance
72combinations of B<-l> and B<-0>. Either put all the switches after
73the 32-character boundary (if applicable), or replace the use of
74B<-0>I<digits> by C<BEGIN{ $/ = "\0digits"; }>.
fb73857a 75
a0d0e21e
LW
76Parsing of the #! switches starts wherever "perl" is mentioned in the line.
77The sequences "-*" and "- " are specifically ignored so that you could,
78if you were so inclined, say
79
80 #!/bin/sh -- # -*- perl -*- -p
19799a22 81 eval 'exec perl -wS $0 ${1+"$@"}'
5f05dabc 82 if $running_under_some_shell;
a0d0e21e 83
19799a22
GS
84to let Perl see the B<-p> switch.
85
86A similar trick involves the B<env> program, if you have it.
87
88 #!/usr/bin/env perl
89
90The examples above use a relative path to the perl interpreter,
91getting whatever version is first in the user's path. If you want
92a specific version of Perl, say, perl5.005_57, you should place
93that directly in the #! line's path.
a0d0e21e
LW
94
95If the #! line does not contain the word "perl", the program named after
96the #! is executed instead of the Perl interpreter. This is slightly
97bizarre, but it helps people on machines that don't do #!, because they
19799a22 98can tell a program that their SHELL is F</usr/bin/perl>, and Perl will then
a0d0e21e
LW
99dispatch the program to the correct interpreter for them.
100
19799a22 101After locating your program, Perl compiles the entire program to an
a0d0e21e 102internal form. If there are any compilation errors, execution of the
19799a22 103program is not attempted. (This is unlike the typical shell script,
54310121 104which might run part-way through before finding a syntax error.)
a0d0e21e 105
19799a22 106If the program is syntactically correct, it is executed. If the program
a0d0e21e
LW
107runs off the end without hitting an exit() or die() operator, an implicit
108C<exit(0)> is provided to indicate successful completion.
109
68dc0745
PP
110=head2 #! and quoting on non-Unix systems
111
112Unix's #! technique can be simulated on other systems:
113
114=over 4
115
116=item OS/2
117
118Put
119
120 extproc perl -S -your_switches
121
19799a22 122as the first line in C<*.cmd> file (B<-S> due to a bug in cmd.exe's
68dc0745
PP
123`extproc' handling).
124
54310121 125=item MS-DOS
68dc0745 126
19799a22 127Create a batch file to run your program, and codify it in
68dc0745
PP
128C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source
129distribution for more information).
130
131=item Win95/NT
132
6c6a61e2 133The Win95/NT installation, when using the ActiveState installer for Perl,
c8db1d39 134will modify the Registry to associate the F<.pl> extension with the perl
6c6a61e2
GS
135interpreter. If you install Perl by other means (including building from
136the sources), you may have to modify the Registry yourself. Note that
137this means you can no longer tell the difference between an executable
138Perl program and a Perl library file.
68dc0745
PP
139
140=item Macintosh
141
19799a22 142A Macintosh perl program will have the appropriate Creator and
68dc0745
PP
143Type, so that double-clicking them will invoke the perl application.
144
bd3fa61c
CB
145=item VMS
146
147Put
148
149 $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
150 $ exit++ + ++$status != 0 and $exit = $status = undef;
151
19799a22
GS
152at the top of your program, where B<-mysw> are any command line switches you
153want to pass to Perl. You can now invoke the program directly, by saying
154C<perl program>, or as a DCL procedure, by saying C<@program> (or implicitly
155via F<DCL$PATH> by just using the name of the program).
bd3fa61c
CB
156
157This incantation is a bit much to remember, but Perl will display it for
158you if you say C<perl "-V:startperl">.
159
68dc0745
PP
160=back
161
162Command-interpreters on non-Unix systems have rather different ideas
163on quoting than Unix shells. You'll need to learn the special
164characters in your command-interpreter (C<*>, C<\> and C<"> are
165common) and how to protect whitespace and these characters to run
19799a22 166one-liners (see B<-e> below).
68dc0745
PP
167
168On some systems, you may have to change single-quotes to double ones,
19799a22 169which you must I<not> do on Unix or Plan9 systems. You might also
68dc0745
PP
170have to change a single % to a %%.
171
172For example:
173
174 # Unix
175 perl -e 'print "Hello world\n"'
176
54310121 177 # MS-DOS, etc.
68dc0745
PP
178 perl -e "print \"Hello world\n\""
179
54310121 180 # Macintosh
68dc0745
PP
181 print "Hello world\n"
182 (then Run "Myscript" or Shift-Command-R)
183
184 # VMS
185 perl -e "print ""Hello world\n"""
186
19799a22
GS
187The problem is that none of this is reliable: it depends on the
188command and it is entirely possible neither works. If B<4DOS> were
189the command shell, this would probably work better:
68dc0745
PP
190
191 perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
192
19799a22 193B<CMD.EXE> in Windows NT slipped a lot of standard Unix functionality in
68dc0745
PP
194when nobody was looking, but just try to find documentation for its
195quoting rules.
196
54310121 197Under the Macintosh, it depends which environment you are using. The MacPerl
68dc0745 198shell, or MPW, is much like Unix shells in its support for several
54310121 199quoting variants, except that it makes free use of the Macintosh's non-ASCII
68dc0745
PP
200characters as control characters.
201
202There is no general solution to all of this. It's just a mess.
203
a3cb178b
GS
204=head2 Location of Perl
205
206It may seem obvious to say, but Perl is useful only when users can
19799a22
GS
207easily find it. When possible, it's good for both F</usr/bin/perl>
208and F</usr/local/bin/perl> to be symlinks to the actual binary. If
209that can't be done, system administrators are strongly encouraged
210to put (symlinks to) perl and its accompanying utilities into a
211directory typically found along a user's PATH, or in some other
212obvious and convenient place.
213
214In this documentation, C<#!/usr/bin/perl> on the first line of the program
215will stand in for whatever method works on your system. You are
216advised to use a specific path if you care about a specific version.
a3cb178b 217
19799a22 218 #!/usr/local/bin/perl5.00554
a3cb178b 219
19799a22
GS
220or if you just want to be running at least version, place a statement
221like this at the top of your program:
a0d0e21e 222
19799a22 223 use 5.005_54;
a0d0e21e 224
19799a22
GS
225=head2 Command Switches
226
227As with all standard commands, a single-character switch may be
228clustered with the following switch, if any.
229
230 #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
a0d0e21e
LW
231
232Switches include:
233
234=over 5
235
e0ebc809 236=item B<-0>[I<digits>]
a0d0e21e 237
55497cff 238specifies the input record separator (C<$/>) as an octal number. If there are
a0d0e21e
LW
239no digits, the null character is the separator. Other switches may
240precede or follow the digits. For example, if you have a version of
241B<find> which can print filenames terminated by the null character, you
242can say this:
243
19799a22 244 find . -name '*.orig' -print0 | perl -n0e unlink
a0d0e21e
LW
245
246The special value 00 will cause Perl to slurp files in paragraph mode.
5f05dabc 247The value 0777 will cause Perl to slurp files whole because there is no
a0d0e21e
LW
248legal character with that value.
249
250=item B<-a>
251
252turns on autosplit mode when used with a B<-n> or B<-p>. An implicit
253split command to the @F array is done as the first thing inside the
254implicit while loop produced by the B<-n> or B<-p>.
255
256 perl -ane 'print pop(@F), "\n";'
257
258is equivalent to
259
260 while (<>) {
261 @F = split(' ');
262 print pop(@F), "\n";
263 }
264
265An alternate delimiter may be specified using B<-F>.
266
46487f74
GS
267=item B<-C>
268
269enables Perl to use the native wide character APIs on the target system.
270The magic variable C<${^WIDE_SYSTEM_CALLS}> reflects the state of
271this switch. See L<perlvar/"${^WIDE_SYSTEM_CALLS}">.
272
273This feature is currently only implemented on the Win32 platform.
274
a0d0e21e
LW
275=item B<-c>
276
19799a22 277causes Perl to check the syntax of the program and then exit without
7d30b5c4 278executing it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and
4f25aa18
GS
279C<use> blocks, because these are considered as occurring outside the
280execution of your program. C<INIT> and C<END> blocks, however, will
281be skipped.
a0d0e21e
LW
282
283=item B<-d>
284
19799a22 285runs the program under the Perl debugger. See L<perldebug>.
a0d0e21e 286
e0ebc809 287=item B<-d:>I<foo>
3c81428c 288
19799a22
GS
289runs the program under the control of a debugging, profiling, or
290tracing module installed as Devel::foo. E.g., B<-d:DProf> executes
291the program using the Devel::DProf profiler. See L<perldebug>.
3c81428c 292
db2ba183 293=item B<-D>I<letters>
a0d0e21e 294
db2ba183 295=item B<-D>I<number>
a0d0e21e 296
19799a22 297sets debugging flags. To watch how it executes your program, use
db2ba183
TB
298B<-Dtls>. (This works only if debugging is compiled into your
299Perl.) Another nice value is B<-Dx>, which lists your compiled
300syntax tree. And B<-Dr> displays compiled regular expressions. As an
301alternative, specify a number instead of list of letters (e.g., B<-D14> is
a0d0e21e
LW
302equivalent to B<-Dtls>):
303
db2ba183
TB
304 1 p Tokenizing and parsing
305 2 s Stack snapshots
306 4 l Context (loop) stack processing
307 8 t Trace execution
308 16 o Method and overloading resolution
309 32 c String/numeric conversions
310 64 P Print preprocessor command for -P
311 128 m Memory allocation
312 256 f Format processing
313 512 r Regular expression parsing and execution
314 1024 x Syntax tree dump
315 2048 u Tainting checks
19799a22 316 4096 L Memory leaks (needs -DLEAKTEST when compiling Perl)
db2ba183
TB
317 8192 H Hash dump -- usurps values()
318 16384 X Scratchpad allocation
319 32768 D Cleaning up
8b73bbec 320 65536 S Thread synchronization
a0d0e21e 321
19799a22
GS
322All these flags require B<-DDEBUGGING> when you compile the Perl
323executable. See the F<INSTALL> file in the Perl source distribution
324for how to do this. This flag is automatically set if you include B<-g>
8c52afec
IZ
325option when C<Configure> asks you about optimizer/debugger flags.
326
19799a22
GS
327If you're just trying to get a print out of each line of Perl code
328as it executes, the way that C<sh -x> provides for shell scripts,
329you can't use Perl's B<-D> switch. Instead do this
330
331 # Bourne shell syntax
332 $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
333
334 # csh syntax
335 % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS program)
336
337See L<perldebug> for details and variations.
338
a0d0e21e
LW
339=item B<-e> I<commandline>
340
19799a22
GS
341may be used to enter one line of program. If B<-e> is given, Perl
342will not look for a filename in the argument list. Multiple B<-e>
343commands may be given to build up a multi-line script. Make sure
344to use semicolons where you would in a normal program.
a0d0e21e 345
e0ebc809 346=item B<-F>I<pattern>
a0d0e21e 347
e0ebc809 348specifies the pattern to split on if B<-a> is also in effect. The
5f05dabc 349pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
e0ebc809 350put in single quotes.
a0d0e21e 351
e0ebc809
PP
352=item B<-h>
353
354prints a summary of the options.
355
356=item B<-i>[I<extension>]
a0d0e21e 357
2d259d92
CK
358specifies that files processed by the C<E<lt>E<gt>> construct are to be
359edited in-place. It does this by renaming the input file, opening the
360output file by the original name, and selecting that output file as the
361default for print() statements. The extension, if supplied, is used to
362modify the name of the old file to make a backup copy, following these
363rules:
364
365If no extension is supplied, no backup is made and the current file is
366overwritten.
367
19799a22
GS
368If the extension doesn't contain a C<*>, then it is appended to the
369end of the current filename as a suffix. If the extension does
370contain one or more C<*> characters, then each C<*> is replaced
371with the current filename. In Perl terms, you could think of this
372as:
2d259d92 373
66606d78 374 ($backup = $extension) =~ s/\*/$file_name/g;
2d259d92
CK
375
376This allows you to add a prefix to the backup file, instead of (or in
377addition to) a suffix:
378
19799a22 379 $ perl -pi 'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
2d259d92
CK
380
381Or even to place backup copies of the original files into another
382directory (provided the directory already exists):
383
19799a22 384 $ perl -pi 'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
2d259d92 385
66606d78
CK
386These sets of one-liners are equivalent:
387
388 $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
19799a22 389 $ perl -pi '*' -e 's/bar/baz/' fileA # overwrite current file
66606d78 390
19799a22
GS
391 $ perl -pi '.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
392 $ perl -pi '*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
66606d78 393
2d259d92 394From the shell, saying
a0d0e21e 395
19799a22 396 $ perl -p -i.orig -e "s/foo/bar/; ... "
a0d0e21e 397
19799a22 398is the same as using the program:
a0d0e21e 399
19799a22 400 #!/usr/bin/perl -pi.orig
a0d0e21e
LW
401 s/foo/bar/;
402
403which is equivalent to
404
405 #!/usr/bin/perl
19799a22
GS
406 $extension = '.orig';
407 LINE: while (<>) {
a0d0e21e 408 if ($ARGV ne $oldargv) {
66606d78
CK
409 if ($extension !~ /\*/) {
410 $backup = $ARGV . $extension;
411 }
412 else {
413 ($backup = $extension) =~ s/\*/$ARGV/g;
414 }
415 rename($ARGV, $backup);
a0d0e21e
LW
416 open(ARGVOUT, ">$ARGV");
417 select(ARGVOUT);
418 $oldargv = $ARGV;
419 }
420 s/foo/bar/;
421 }
422 continue {
423 print; # this prints to original filename
424 }
425 select(STDOUT);
426
427except that the B<-i> form doesn't need to compare $ARGV to $oldargv to
428know when the filename has changed. It does, however, use ARGVOUT for
66606d78
CK
429the selected filehandle. Note that STDOUT is restored as the default
430output filehandle after the loop.
431
432As shown above, Perl creates the backup file whether or not any output
433is actually changed. So this is just a fancy way to copy files:
434
19799a22
GS
435 $ perl -p -i '/some/file/path/*' -e 1 file1 file2 file3...
436or
437 $ perl -p -i '.orig' -e 1 file1 file2 file3...
66606d78
CK
438
439You can use C<eof> without parentheses to locate the end of each input
440file, in case you want to append to each file, or reset line numbering
441(see example in L<perlfunc/eof>).
442
443If, for a given file, Perl is unable to create the backup file as
444specified in the extension then it will skip that file and continue on
445with the next one (if it exists).
446
19799a22
GS
447For a discussion of issues surrounding file permissions and B<-i>,
448see L<perlfaq5/Why does Perl let me delete read-only files? Why
449does -i clobber protected files? Isn't this a bug in Perl?>.
66606d78
CK
450
451You cannot use B<-i> to create directories or to strip extensions from
452files.
a0d0e21e 453
19799a22
GS
454Perl does not expand C<~> in filenames, which is good, since some
455folks use it for their backup files:
a0d0e21e 456
19799a22
GS
457 $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
458
459Finally, the B<-i> switch does not impede execution when no
a2008d6d
GS
460files are given on the command line. In this case, no backup is made
461(the original file cannot, of course, be determined) and processing
462proceeds from STDIN to STDOUT as might be expected.
463
a0d0e21e
LW
464=item B<-I>I<directory>
465
e0ebc809 466Directories specified by B<-I> are prepended to the search path for
1fef88e7 467modules (C<@INC>), and also tells the C preprocessor where to search for
e0ebc809
PP
468include files. The C preprocessor is invoked with B<-P>; by default it
469searches /usr/include and /usr/lib/perl.
a0d0e21e 470
e0ebc809 471=item B<-l>[I<octnum>]
a0d0e21e 472
19799a22
GS
473enables automatic line-ending processing. It has two separate
474effects. First, it automatically chomps C<$/> (the input record
475separator) when used with B<-n> or B<-p>. Second, it assigns C<$\>
476(the output record separator) to have the value of I<octnum> so
477that any print statements will have that separator added back on.
478If I<octnum> is omitted, sets C<$\> to the current value of
479C<$/>. For instance, to trim lines to 80 columns:
a0d0e21e
LW
480
481 perl -lpe 'substr($_, 80) = ""'
482
483Note that the assignment C<$\ = $/> is done when the switch is processed,
484so the input record separator can be different than the output record
485separator if the B<-l> switch is followed by a B<-0> switch:
486
487 gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
488
1fef88e7 489This sets C<$\> to newline and then sets C<$/> to the null character.
a0d0e21e 490
e0ebc809
PP
491=item B<-m>[B<->]I<module>
492
493=item B<-M>[B<->]I<module>
c07a80fd 494
e0ebc809
PP
495=item B<-M>[B<->]I<'module ...'>
496
497=item B<-[mM]>[B<->]I<module=arg[,arg]...>
3c81428c 498
19799a22
GS
499B<-m>I<module> executes C<use> I<module> C<();> before executing your
500program.
3c81428c 501
19799a22
GS
502B<-M>I<module> executes C<use> I<module> C<;> before executing your
503program. You can use quotes to add extra code after the module name,
504e.g., C<'-Mmodule qw(foo bar)'>.
3c81428c 505
19799a22 506If the first character after the B<-M> or B<-m> is a dash (C<->)
a5f75d66
AD
507then the 'use' is replaced with 'no'.
508
54310121 509A little builtin syntactic sugar means you can also say
19799a22
GS
510B<-mmodule=foo,bar> or B<-Mmodule=foo,bar> as a shortcut for
511C<'-Mmodule qw(foo bar)'>. This avoids the need to use quotes when
512importing symbols. The actual code generated by B<-Mmodule=foo,bar> is
e0ebc809 513C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
19799a22 514removes the distinction between B<-m> and B<-M>.
3c81428c 515
a0d0e21e
LW
516=item B<-n>
517
19799a22 518causes Perl to assume the following loop around your program, which
a0d0e21e
LW
519makes it iterate over filename arguments somewhat like B<sed -n> or
520B<awk>:
521
19799a22 522 LINE:
a0d0e21e 523 while (<>) {
19799a22 524 ... # your program goes here
a0d0e21e
LW
525 }
526
527Note that the lines are not printed by default. See B<-p> to have
08e9d68e 528lines printed. If a file named by an argument cannot be opened for
19799a22 529some reason, Perl warns you about it and moves on to the next file.
08e9d68e
DD
530
531Here is an efficient way to delete all files older than a week:
a0d0e21e 532
19799a22 533 find . -mtime +7 -print | perl -nle unlink
a0d0e21e 534
19799a22
GS
535This is faster than using the B<-exec> switch of B<find> because you don't
536have to start a process on every filename found. It does suffer from
537the bug of mishandling newlines in pathnames, which you can fix if
538you
a0d0e21e
LW
539
540C<BEGIN> and C<END> blocks may be used to capture control before or after
19799a22 541the implicit program loop, just as in B<awk>.
a0d0e21e
LW
542
543=item B<-p>
544
19799a22 545causes Perl to assume the following loop around your program, which
a0d0e21e
LW
546makes it iterate over filename arguments somewhat like B<sed>:
547
548
19799a22 549 LINE:
a0d0e21e 550 while (<>) {
19799a22 551 ... # your program goes here
a0d0e21e 552 } continue {
08e9d68e 553 print or die "-p destination: $!\n";
a0d0e21e
LW
554 }
555
08e9d68e
DD
556If a file named by an argument cannot be opened for some reason, Perl
557warns you about it, and moves on to the next file. Note that the
c2611fb3 558lines are printed automatically. An error occurring during printing is
08e9d68e
DD
559treated as fatal. To suppress printing use the B<-n> switch. A B<-p>
560overrides a B<-n> switch.
a0d0e21e
LW
561
562C<BEGIN> and C<END> blocks may be used to capture control before or after
19799a22 563the implicit loop, just as in B<awk>.
a0d0e21e
LW
564
565=item B<-P>
566
19799a22
GS
567causes your program to be run through the C preprocessor before
568compilation by Perl. (Because both comments and B<cpp> directives begin
a0d0e21e 569with the # character, you should avoid starting comments with any words
5f05dabc 570recognized by the C preprocessor such as "if", "else", or "define".)
a0d0e21e
LW
571
572=item B<-s>
573
19799a22
GS
574enables rudimentary switch parsing for switches on the command
575line after the program name but before any filename arguments (or before
a0d0e21e 576a B<-->). Any switch found there is removed from @ARGV and sets the
19799a22 577corresponding variable in the Perl program. The following program
3c0facb2
GS
578prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
579if it is invoked with B<-xyz=abc>.
a0d0e21e
LW
580
581 #!/usr/bin/perl -s
3c0facb2 582 if ($xyz) { print "$xyz\n" }
a0d0e21e
LW
583
584=item B<-S>
585
586makes Perl use the PATH environment variable to search for the
19799a22
GS
587program (unless the name of the program contains directory separators).
588
2a92aaa0
GS
589On some platforms, this also makes Perl append suffixes to the
590filename while searching for it. For example, on Win32 platforms,
591the ".bat" and ".cmd" suffixes are appended if a lookup for the
592original name fails, and if the name does not already end in one
593of those suffixes. If your Perl was compiled with DEBUGGING turned
594on, using the -Dp switch to Perl shows how the search progresses.
595
2a92aaa0
GS
596Typically this is used to emulate #! startup on platforms that
597don't support #!. This example works on many platforms that
598have a shell compatible with Bourne shell:
a0d0e21e
LW
599
600 #!/usr/bin/perl
a3cb178b 601 eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
a0d0e21e
LW
602 if $running_under_some_shell;
603
19799a22
GS
604The system ignores the first line and feeds the program to F</bin/sh>,
605which proceeds to try to execute the Perl program as a shell script.
a0d0e21e
LW
606The shell executes the second line as a normal shell command, and thus
607starts up the Perl interpreter. On some systems $0 doesn't always
608contain the full pathname, so the B<-S> tells Perl to search for the
19799a22 609program if necessary. After Perl locates the program, it parses the
a0d0e21e 610lines and ignores them because the variable $running_under_some_shell
19799a22 611is never true. If the program will be interpreted by csh, you will need
a3cb178b
GS
612to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
613embedded spaces (and such) in the argument list. To start up sh rather
a0d0e21e
LW
614than csh, some systems may have to replace the #! line with a line
615containing just a colon, which will be politely ignored by Perl. Other
616systems can't control that, and need a totally devious construct that
19799a22 617will work under any of B<csh>, B<sh>, or Perl, such as the following:
a0d0e21e 618
19799a22 619 eval '(exit $?0)' && eval 'exec perl -wS $0 ${1+"$@"}'
a3cb178b 620 & eval 'exec /usr/bin/perl -wS $0 $argv:q'
5f05dabc 621 if $running_under_some_shell;
a0d0e21e 622
19799a22
GS
623If the filename supplied contains directory separators (i.e., is an
624absolute or relative pathname), and if that file is not found,
625platforms that append file extensions will do so and try to look
626for the file with those extensions added, one by one.
627
628On DOS-like platforms, if the program does not contain directory
629separators, it will first be searched for in the current directory
630before being searched for on the PATH. On Unix platforms, the
631program will be searched for strictly on the PATH.
632
a0d0e21e
LW
633=item B<-T>
634
a3cb178b 635forces "taint" checks to be turned on so you can test them. Ordinarily
19799a22
GS
636these checks are done only when running setuid or setgid. It's a
637good idea to turn them on explicitly for programs that run on behalf
638of someone else whom you might not necessarily trust, such as CGI
639programs or any internet servers you might write in Perl. See
640L<perlsec> for details. For security reasons, this option must be
641seen by Perl quite early; usually this means it must appear early
642on the command line or in the #! line for systems which support
643that construct.
a0d0e21e
LW
644
645=item B<-u>
646
19799a22
GS
647This obsolete switch causes Perl to dump core after compiling your
648program. You can then in theory take this core dump and turn it
649into an executable file by using the B<undump> program (not supplied).
650This speeds startup at the expense of some disk space (which you
651can minimize by stripping the executable). (Still, a "hello world"
652executable comes out to about 200K on my machine.) If you want to
653execute a portion of your program before dumping, use the dump()
654operator instead. Note: availability of B<undump> is platform
655specific and may not be available for a specific port of Perl.
656
657This switch has been superseded in favor of the new Perl code
658generator backends to the compiler. See L<B> and L<B::Bytecode>
659for details.
a0d0e21e
LW
660
661=item B<-U>
662
663allows Perl to do unsafe operations. Currently the only "unsafe"
664operations are the unlinking of directories while running as superuser,
665and running setuid programs with fatal taint checks turned into
19799a22
GS
666warnings. Note that the B<-w> switch (or the C<$^W> variable) must
667be used along with this option to actually I<generate> the
fb73857a 668taint-check warnings.
a0d0e21e
LW
669
670=item B<-v>
671
19799a22 672prints the version and patchlevel of your perl executable.
a0d0e21e 673
3c81428c
PP
674=item B<-V>
675
676prints summary of the major perl configuration values and the current
19799a22 677values of @INC.
3c81428c 678
e0ebc809 679=item B<-V:>I<name>
3c81428c
PP
680
681Prints to STDOUT the value of the named configuration variable.
19799a22 682For example,
3c81428c 683
19799a22
GS
684 $ perl -V:man.dir
685
686will provide strong clues about what your MANPATH variable should
687be set to in order to access the Perl documentation.
a0d0e21e 688
19799a22 689=item B<-w>
774d564b 690
19799a22
GS
691prints warnings about dubious constructs, such as variable names
692that are mentioned only once and scalar variables that are used
693before being set, redefined subroutines, references to undefined
694filehandles or filehandles opened read-only that you are attempting
695to write on, values used as a number that doesn't look like numbers,
696using an array as though it were a scalar, if your subroutines
697recurse more than 100 deep, and innumerable other things.
698
699This switch really just enables the internal C<^$W> variable. You
700can disable or promote into fatal errors specific warnings using
701C<__WARN__> hooks, as described in L<perlvar> and L<perlfunc/warn>.
702See also L<perldiag> and L<perltrap>. A new, fine-grained warning
703facility is also available if you want to manipulate entire classes
9f1b1f2d 704of warnings; see L<warnings> or L<perllexwarn>.
a0d0e21e 705
0453d815
PM
706=item B<-W>
707
3c0facb2 708Enables all warnings regardless of C<no warnings> or C<$^W>.
0453d815
PM
709See L<perllexwarn>.
710
711=item B<-X>
712
3c0facb2 713Disables all warnings regardless of C<use warnings> or C<$^W>.
0453d815
PM
714See L<perllexwarn>.
715
a0d0e21e
LW
716=item B<-x> I<directory>
717
19799a22
GS
718tells Perl that the program is embedded in a larger chunk of unrelated
719ASCII text, such as in a mail message. Leading garbage will be
720discarded until the first line that starts with #! and contains the
721string "perl". Any meaningful switches on that line will be applied.
722If a directory name is specified, Perl will switch to that directory
723before running the program. The B<-x> switch controls only the
724disposal of leading garbage. The program must be terminated with
725C<__END__> if there is trailing garbage to be ignored (the program
726can process any or all of the trailing garbage via the DATA filehandle
727if desired).
a0d0e21e 728
1e422769
PP
729=back
730
731=head1 ENVIRONMENT
732
733=over 12
734
735=item HOME
736
737Used if chdir has no argument.
738
739=item LOGDIR
740
741Used if chdir has no argument and HOME is not set.
742
743=item PATH
744
19799a22 745Used in executing subprocesses, and in finding the program if B<-S> is
1e422769
PP
746used.
747
748=item PERL5LIB
749
750A colon-separated list of directories in which to look for Perl library
751files before looking in the standard library and the current
951ba7fe
GS
752directory. Any architecture-specific directories under the specified
753locations are automatically included if they exist. If PERL5LIB is not
754defined, PERLLIB is used.
755
756When running taint checks (either because the program was running setuid
757or setgid, or the B<-T> switch was used), neither variable is used.
758The program should instead say:
1e422769
PP
759
760 use lib "/my/directory";
761
54310121
PP
762=item PERL5OPT
763
764Command-line options (switches). Switches in this variable are taken
765as if they were on every Perl command line. Only the B<-[DIMUdmw]>
19799a22 766switches are allowed. When running taint checks (because the program
54310121 767was running setuid or setgid, or the B<-T> switch was used), this
74288ac8
GS
768variable is ignored. If PERL5OPT begins with B<-T>, tainting will be
769enabled, and any subsequent options ignored.
54310121 770
1e422769
PP
771=item PERLLIB
772
773A colon-separated list of directories in which to look for Perl library
774files before looking in the standard library and the current directory.
775If PERL5LIB is defined, PERLLIB is not used.
776
777=item PERL5DB
778
779The command used to load the debugger code. The default is:
780
781 BEGIN { require 'perl5db.pl' }
782
19799a22 783=item PERL5SHELL (specific to the Win32 port)
174c211a
GS
784
785May be set to an alternative shell that perl must use internally for
ce1da67e
GS
786executing "backtick" commands or system(). Default is C<cmd.exe /x/c>
787on WindowsNT and C<command.com /c> on Windows95. The value is considered
19799a22 788to be space-separated. Precede any character that needs to be protected
ce1da67e
GS
789(like a space or backslash) with a backslash.
790
791Note that Perl doesn't use COMSPEC for this purpose because
792COMSPEC has a high degree of variability among users, leading to
793portability concerns. Besides, perl can use a shell that may not be
794fit for interactive use, and setting COMSPEC to such a shell may
795interfere with the proper functioning of other programs (which usually
796look in COMSPEC to find a shell fit for interactive use).
174c211a 797
1e422769
PP
798=item PERL_DEBUG_MSTATS
799
67ce8856 800Relevant only if perl is compiled with the malloc included with the perl
a3cb178b
GS
801distribution (that is, if C<perl -V:d_mymalloc> is 'define').
802If set, this causes memory statistics to be dumped after execution. If set
1e422769
PP
803to an integer greater than one, also causes memory statistics to be dumped
804after compilation.
805
806=item PERL_DESTRUCT_LEVEL
807
808Relevant only if your perl executable was built with B<-DDEBUGGING>,
809this controls the behavior of global destruction of objects and other
810references.
a0d0e21e 811
3d0ae7ba
GS
812=item PERL_ROOT (specific to the VMS port)
813
814A translation concealed rooted logical name that contains perl and the
815logical device for the @INC path on VMS only. Other logical names that
816affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and
817SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in
818L<perlvms> and in F<README.vms> in the Perl source distribution.
819
820=item SYS$LOGIN (specific to the VMS port)
821
822Used if chdir has no argument and HOME and LOGDIR are not set.
823
a0d0e21e 824=back
1e422769
PP
825
826Perl also has environment variables that control how Perl handles data
827specific to particular natural languages. See L<perllocale>.
828
829Apart from these, Perl uses no other environment variables, except
19799a22
GS
830to make them available to the program being executed, and to child
831processes. However, programs running setuid would do well to execute
1e422769
PP
832the following lines before doing anything else, just to keep people
833honest:
834
19799a22 835 $ENV{PATH} = '/bin:/usr/bin'; # or whatever you need
7bac28a0 836 $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
c90c0ff4 837 delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};