3.2 Command-Line Options

Perl expects any command-line options, also known as switches or flags , to come first on the command line. The next item is usually the name of the script, followed by any additional arguments (often filenames) to be passed into the script. Some of these additional arguments may be switches, but if so, they must be processed by the script, since Perl gives up parsing switches as soon as it sees either a non-switch item or the special -- switch that terminates switch processing.

A single-character switch with no argument may be combined (bundled) with the switch that follows it, if any. For example:

#!/usr/bin/perl -spi.bak

is the same as:

#!/usr/bin/perl -s -p -i.bak

Perl recognizes the switches listed in Table 3.1 .


Table 3.1: Perl Switches
Switch Function
--

Terminates switch processing, even if the next argument starts with a minus. It has no other effect.

-0 [ octnum ]

Specifies the record separator ( $/ ) as an octal number. If octnum is not present, the null character is the separator. Other switches may precede or follow the octal number.

-a

Turns on autosplit mode when used with -n or -p . An implicit split of the @F array is inserted as the first command inside the implicit while loop produced by -n or -p . The default field delimiter is whitespace; a different field delimiter may be specified using -F .

-c

Causes Perl to check the syntax of the script and then exit without executing it. More or less equivalent to having exit(0) as the first statement in your program.

-d

Runs the script under the Perl debugger. See Chapter 6, Debugging .

-d:foo

Runs the script under the control of a debugging or tracing module installed in the Perl library as Devel:: foo . For example, -d:DProf executes the script using the Devel::DProf profiler. See also the section on DProf in Chapter 6 .

-Dnumber

Sets debugging flags. (This only works if debugging was compiled into the version of Perl you are running.) You may specify either a number that is the sum of the bits you want, or a list of letters. To watch how Perl executes your script, for instance, use -D14 or -Dslt . Another useful value is -D1024 ( -Dx ), which lists your compiled syntax tree. And -D512 ( -Dr ) displays compiled regular expressions. The numeric value of the flags is available internally as the special variable $^D . Here are the assigned bit values:

-Dlist

Bit Letter Meaning
1 p Tokenizing and parsing
2 s Stack snapshots
4 l Label stack processing
8 t Trace execution
16 o Object method lookup
32 c String/numeric conversions
64 P

Print preprocessor command for -P

128 m Memory allocation
256 f Format processing
512 r Regular expression processing
1,024 x Syntax tree dump
2,048 u Tainting checks
4,096 L Memory leaks (not supported any more)
8,192 H

Hash dump - usurps values

16,384 X Scratchpad allocation
32,768 D Cleaning up
-e commandline

May be used to enter one or more lines of script. If -e is used, Perl does not look for the name of a script in the argument list. Multiple -e commands may be given to build up a multiline script. (Make sure to use semicolons where you would in a normal program.)

-Fpattern

Specifies the pattern to split on if -a is also in effect. The pattern may be surrounded by // , '' , or "" ; otherwise it is put in single quotes.

-h

Prints a summary of Perl's command-line options.

-i [ extension ]

Specifies that files processed by the <> construct are to be edited in-place. Perl does this by renaming the input file, opening the output file by the original name, and selecting that output file as the default for print statements. The extension, if supplied, is added to the name of the old file to make a backup copy. If no extension is supplied, no backup is made.

-Idirectory

Directories specified by -I are prepended to @INC , which holds the search path for modules. If -P is also specified, to invoke the C preprocessor, -I tells the preprocessor where to search for include files. By default, it searches /usr/include and /usr/lib/perl .

-l [ octnum ]

Enables automatic line-end processing. This switch has two effects: first, when it's used with -n or -p , it causes the line terminator to be automatically chomp ed, and second, it sets $\ to the value of octnum so any print statements will have a line terminator of ASCII value octnum added back on. If octnum is omitted, $\ is set to the current value of $/ , which is typically a newline. So, to trim lines to 80 columns, say this:

perl -lpe 'substr($_, 80) = ""'

-m [ - ] module

Executes use module before executing your script.

-M [ - ] module
-M [ - ] 'module ...'
-[ mM ][ - ] module arg [ ,arg ] ...
-m module

-Mmodule

Executes use module before executing your script. The command is formed by interpolation, so you can use quotes to add extra code after the module name, for example, -M'module qw(foo bar)' . If the first character after the -M or -m is a minus ( - ), then the use is replaced with no .

You can also say -m module=foo,bar or -Mmodule= foo,bar as a shortcut for -M'module qw(foo bar) '. This avoids the need to use quotes when importing symbols. The actual code generated by -Mmodule=foo,bar is:

use module split(/,/, q{foo,bar})
The = form removes the distinction between -m and -M .

-n

Causes Perl to assume the following loop around your script, which makes it iterate over filename arguments:

LINE:
while (<>) {
   ...      # your script goes here
By default, the lines are not printed. See -p to have lines printed. BEGIN and END blocks may be used to capture control before or after the implicit loop.

-p

Causes Perl to assume the following loop around your script, which makes it iterate over filename arguments:

LINE:
while (<>) {
    ...     # your script goes here
} continue {
    print;
The lines are printed automatically. To suppress printing, use the -n switch. If both are specified, the -p switch overrides -n . BEGIN and END blocks may be used to capture control before or after the implicit loop.

-P

Causes your script to be run through the C preprocessor before compilation by Perl. (Since both comments and cpp directives begin with the # character, you should avoid starting comments with any words recognized by the C preprocessor such as if , else , or define .)

-s

Enables some rudimentary parsing of switches on the command line after the script name but before any filename arguments or the -- switch terminator. Any switch found there is removed from @ARGV , and a variable of the same name as the switch is set in the Perl script. No switch bundling is allowed, since multicharacter switches are allowed.

-S

Makes Perl use the PATH environment variable to search for the script (unless the name of the script starts with a slash). Typically this is used to emulate #! startup on machines that don't support #! .

-T

Forces "taint" checks to be turned on. Ordinarily, these checks are done only when running setuid or setgid. It's a good idea to turn them on explicitly for programs run on another user's behalf, such as CGI programs.

-u

Causes Perl to dump core after compiling your script. You can then take this core dump and turn it into an executable file by using the undump program (not supplied). This speeds startup at the expense of some disk space (which you can minimize by stripping the executable). If you want to execute a portion of your script before dumping, use Perl's dump operator instead. Note: availability of undump is platform-specific; it may not be available for a specific port of Perl.

-U

Allows Perl to do unsafe operations. Currently, the only "unsafe" operations are the unlinking of directories while running as superuser and running setuid programs with fatal taint checks turned into warnings.

-v

Prints the version and patch level of your Perl executable.

-V

Prints a summary of the major Perl configuration values and the current value of @INC .

-V:name

Prints the value of the named configuration variable to STDOUT.

-w

Prints warnings about identifiers that are mentioned only once and scalar variables that are used before being set. Also warns about redefined subroutines and references to undefined filehandles or to filehandles opened as read-only that you are attempting to write on. Warns you if you use a non-number as though it were a number, if you use an array as though it were a scalar, if your subroutines recurse more than 100 levels deep, etc.

-x [ directory ]

Tells Perl to extract a script that is embedded in a message, by looking for the first line that starts with #! and contains the string "perl". Any meaningful switches on that line after the word "perl" are applied. If a directory name is specified, Perl switches to that directory before running the script. The script must be terminated with __END__ or __DATA__ if there is trailing text to be ignored. (The script can process any or all of the trailing text via the DATA filehandle if desired.)