=head1 SYNOPSIS
-B<perl> [switches] filename args
+B<perl> S<[ B<-sTuU> ]>
+ S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+ S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+ S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+ S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
+ S<[ B<-P> ]>
+ S<[ B<-S> ]>
+ S<[ B<-x>[I<dir>] ]>
+ S<[ B<-i>[I<extension>] ]>
+ S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
=head1 DESCRIPTION
=item 3.
-Passed in implicitly via standard input. This only works if there are
+Passed in implicitly via standard input. This works only if there are
no filename arguments--to pass arguments to a STDIN script you
must explicitly specify a "-" for the script name.
embedded in a larger message. (In this case you would indicate the end
of the script using the __END__ token.)
-As of Perl 5, the #! line is always examined for switches as the line is
-being parsed. Thus, if you're on a machine that only allows one argument
-with the #! line, or worse, doesn't even recognize the #! line, you still
-can get consistent switch behavior regardless of how Perl was invoked,
-even if B<-x> was used to find the beginning of the script.
+The #! line is always examined for switches as the line is being
+parsed. Thus, if you're on a machine that allows only one argument
+with the #! line, or worse, doesn't even recognize the #! line, you
+still can get consistent switch behavior regardless of how Perl was
+invoked, even if B<-x> was used to find the beginning of the script.
Because many operating systems silently chop off kernel interpretation of
the #! line after 32 characters, some switches may be passed in on the
if you were so inclined, say
#!/bin/sh -- # -*- perl -*- -p
- eval 'exec perl $0 -S ${1+"$@"}'
- if 0;
+ eval 'exec /usr/bin/perl $0 -S ${1+"$@"}'
+ if $running_under_some_shell;
to let Perl see the B<-p> switch.
runs off the end without hitting an exit() or die() operator, an implicit
C<exit(0)> is provided to indicate successful completion.
+=head2 #! and quoting on non-Unix systems
+
+Unix's #! technique can be simulated on other systems:
+
+=over 4
+
+=item OS/2
+
+Put
+
+ extproc perl -S -your_switches
+
+as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's
+`extproc' handling).
+
+=item DOS
+
+Create a batch file to run your script, and codify it in
+C<ALTERNATIVE_SHEBANG> (see the F<dosish.h> file in the source
+distribution for more information).
+
+=item Win95/NT
+
+The Win95/NT installation, when using the Activeware port of Perl,
+will modify the Registry to associate the .pl extension with the perl
+interpreter. If you install another port of Perl, including the one
+in the win32 directory of the Perl distribution, then you'll have to
+modify the Registry yourself.
+
+=item Macintosh
+
+Macintosh perl scripts will have the the appropriate Creator and
+Type, so that double-clicking them will invoke the perl application.
+
+=back
+
+Command-interpreters on non-Unix systems have rather different ideas
+on quoting than Unix shells. You'll need to learn the special
+characters in your command-interpreter (C<*>, C<\> and C<"> are
+common) and how to protect whitespace and these characters to run
+one-liners (see C<-e> below).
+
+On some systems, you may have to change single-quotes to double ones,
+which you must I<NOT> do on Unix or Plan9 systems. You might also
+have to change a single % to a %%.
+
+For example:
+
+ # Unix
+ perl -e 'print "Hello world\n"'
+
+ # DOS, etc.
+ perl -e "print \"Hello world\n\""
+
+ # Mac
+ print "Hello world\n"
+ (then Run "Myscript" or Shift-Command-R)
+
+ # VMS
+ perl -e "print ""Hello world\n"""
+
+The problem is that none of this is reliable: it depends on the command
+tirely possible neither works. If 4DOS was the command shell, this would
+probably work better:
+
+ perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
+
+CMD.EXE in Windows NT slipped a lot of standard Unix functionality in
+when nobody was looking, but just try to find documentation for its
+quoting rules.
+
+Under the Mac, it depends which environment you are using. The MacPerl
+shell, or MPW, is much like Unix shells in its support for several
+quoting variants, except that it makes free use of the Mac's non-ASCII
+characters as control characters.
+
+There is no general solution to all of this. It's just a mess.
+
=head2 Switches
A single-character switch may be combined with the following switch, if
=over 5
-=item B<-0>I<digits>
+=item B<-0>[I<digits>]
-specifies the record separator (C<$/>) as an octal number. If there are
+specifies the input record separator (C<$/>) as an octal number. If there are
no digits, the null character is the separator. Other switches may
precede or follow the digits. For example, if you have a version of
B<find> which can print filenames terminated by the null character, you
find . -name '*.bak' -print0 | perl -n0e unlink
The special value 00 will cause Perl to slurp files in paragraph mode.
-The value 0777 will cause Perl to slurp files whole since there is no
+The value 0777 will cause Perl to slurp files whole because there is no
legal character with that value.
=item B<-a>
causes Perl to check the syntax of the script and then exit without
executing it. Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks,
-since these are considered as occurring outside the execution of
+because these are considered as occurring outside the execution of
your program.
=item B<-d>
runs the script under the Perl debugger. See L<perldebug>.
-=item B<-d:foo>
+=item B<-d:>I<foo>
runs the script under the control of a debugging or tracing module
-installed as Devel::foo. E.g., -d:DProf executes the script using the
+installed as Devel::foo. E.g., B<-d:DProf> executes the script using the
Devel::DProf profiler. See L<perldebug>.
=item B<-D>I<number>
=item B<-D>I<list>
sets debugging flags. To watch how it executes your script, use
-B<-D14>. (This only works if debugging is compiled into your
+B<-D14>. (This works only if debugging is compiled into your
Perl.) Another nice value is B<-D1024>, which lists your compiled
syntax tree. And B<-D512> displays compiled regular expressions. As an
-alternative specify a list of letters instead of numbers (e.g. B<-D14> is
+alternative specify a list of letters instead of numbers (e.g., B<-D14> is
equivalent to B<-Dtls>):
1 p Tokenizing and Parsing
be given to build up a multi-line script.
Make sure to use semicolons where you would in a normal program.
-=item B<-F>I<regexp>
+=item B<-F>I<pattern>
+
+specifies the pattern to split on if B<-a> is also in effect. The
+pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
+put in single quotes.
+
+=item B<-h>
-specifies a regular expression to split on if B<-a> is also in effect.
-If regexp has C<//> around it, the slashes will be ignored.
+prints a summary of the options.
-=item B<-i>I<extension>
+=item B<-i>[I<extension>]
specifies that files processed by the C<E<lt>E<gt>> construct are to be edited
in-place. It does this by renaming the input file, opening the output
=item B<-I>I<directory>
-may be used in conjunction with B<-P> to tell the C preprocessor where
-to look for include files. By default /usr/include and /usr/lib/perl
-are searched.
+Directories specified by B<-I> are prepended to the search path for
+modules (C<@INC>), and also tells the C preprocessor where to search for
+include files. The C preprocessor is invoked with B<-P>; by default it
+searches /usr/include and /usr/lib/perl.
-=item B<-l>I<octnum>
+=item B<-l>[I<octnum>]
enables automatic line-ending processing. It has two effects: first,
-it automatically chomps the line terminator when used with B<-n> or
-B<-p>, and second, it assigns "C<$\>" to have the value of I<octnum> so that
-any print statements will have that line terminator added back on. If
+it automatically chomps "C<$/>" (the input record separator) when used
+with B<-n> or B<-p>, and second, it assigns "C<$\>"
+(the output record separator) to have the value of I<octnum> so that
+any print statements will have that separator added back on. If
I<octnum> is omitted, sets "C<$\>" to the current value of "C<$/>". For
instance, to trim lines to 80 columns:
gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
-This sets $\ to newline and then sets $/ to the null character.
+This sets C<$\> to newline and then sets C<$/> to the null character.
-=item B<-M>I<module>
+=item B<-m>[B<->]I<module>
-executes C<use> I<module> C<;> before executing your script. You can
-also do C<-M'Foo qw(Bar Baz)'>.
+=item B<-M>[B<->]I<module>
-=item B<-m>I<module>
+=item B<-M>[B<->]I<'module ...'>
-executes C<use> I<module> C<();> before executing your script.
+=item B<-[mM]>[B<->]I<module=arg[,arg]...>
+
+C<-m>I<module> executes C<use> I<module> C<();> before executing your
+script.
+
+C<-M>I<module> executes C<use> I<module> C<;> before executing your
+script. You can use quotes to add extra code after the module name,
+e.g., C<-M'module qw(foo bar)'>.
+
+If the first character after the C<-M> or C<-m> is a dash (C<->)
+then the 'use' is replaced with 'no'.
+
+A little built-in syntactic sugar means you can also say
+C<-mmodule=foo,bar> or C<-Mmodule=foo,bar> as a shortcut for
+C<-M'module qw(foo bar)'>. This avoids the need to use quotes when
+importing symbols. The actual code generated by C<-Mmodule=foo,bar> is
+C<use module split(/,/,q{foo,bar})>. Note that the C<=> form
+removes the distinction between C<-m> and C<-M>.
=item B<-n>
=item B<-P>
causes your script to be run through the C preprocessor before
-compilation by Perl. (Since both comments and cpp directives begin
+compilation by Perl. (Because 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".)
+recognized by the C preprocessor such as "if", "else", or "define".)
=item B<-s>
in the following manner:
#!/usr/bin/perl
- eval "exec /usr/bin/perl -S $0 $*"
+ eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
if $running_under_some_shell;
The system ignores the first line and feeds the script to /bin/sh,
lines and ignores them because the variable $running_under_some_shell
is never true. A better construct than C<$*> would be C<${1+"$@"}>, which
handles embedded spaces and such in the filenames, but doesn't work if
-the script is being interpreted by csh. In order to start up sh rather
+the script is being interpreted by csh. To start up sh rather
than csh, some systems may have to replace the #! line with a line
containing just a colon, which will be politely ignored by Perl. Other
systems can't control that, and need a totally devious construct that
-will work under any of csh, sh or Perl, such as the following:
+will work under any of csh, sh, or Perl, such as the following:
eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
& eval 'exec /usr/bin/perl -S $0 $argv:q'
- if 0;
+ if $running_under_some_shell;
=item B<-T>
prints summary of the major perl configuration values and the current
value of @INC.
-=item B<-V:name>
+=item B<-V:>I<name>
Prints to STDOUT the value of the named configuration variable.
=item B<-w>
-prints warnings about identifiers that are mentioned only once, and
+prints warnings about variable names 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
-filehandles opened readonly that you are attempting to write on. Also
-warns you if you use values as a number that doesn't look like numbers, using
-an array as though it were a scalar, if
-your subroutines recurse more than 100 deep, and innumerable other things.
-See L<perldiag> and L<perltrap>.
+filehandles opened read-only that you are attempting to write on. Also
+warns you if you use values as a number that doesn't look like numbers,
+using an array as though it were a scalar, if your subroutines recurse
+more than 100 deep, and innumerable other things.
+
+You can disable specific warnings using C<__WARN__> hooks, as described
+in L<perlvar> and L<perlfunc/warn>. See also L<perldiag> and L<perltrap>.
=item B<-x> I<directory>
tells Perl that the script is embedded in a message. Leading
garbage will be discarded until the first line that starts with #! and
contains the string "perl". Any meaningful switches on that line will
-be applied (but only one group of switches, as with normal #!
-processing). If a directory name is specified, Perl will switch to
-that directory before running the script. The B<-x> switch only
-controls the the disposal of leading garbage. The script must be
+be applied. If a directory name is specified, Perl will switch to
+that directory before running the script. The B<-x> switch controls
+only the disposal of leading garbage. The script must be
terminated with C<__END__> if there is trailing garbage to be ignored (the
script can process any or all of the trailing garbage via the DATA
filehandle if desired).
+=back
+
+=head1 ENVIRONMENT
+
+=over 12
+
+=item HOME
+
+Used if chdir has no argument.
+
+=item LOGDIR
+
+Used if chdir has no argument and HOME is not set.
+
+=item PATH
+
+Used in executing subprocesses, and in finding the script if B<-S> is
+used.
+
+=item PERL5LIB
+
+A colon-separated list of directories in which to look for Perl library
+files before looking in the standard library and the current
+directory. If PERL5LIB is not defined, PERLLIB is used. When running
+taint checks (because the script was running setuid or setgid, or the
+B<-T> switch was used), neither variable is used. The script should
+instead say
+
+ use lib "/my/directory";
+
+=item PERLLIB
+
+A colon-separated list of directories in which to look for Perl library
+files before looking in the standard library and the current directory.
+If PERL5LIB is defined, PERLLIB is not used.
+
+=item PERL5DB
+
+The command used to load the debugger code. The default is:
+
+ BEGIN { require 'perl5db.pl' }
+
+=item PERL_DEBUG_MSTATS
+
+Relevant only if your perl executable was built with B<-DDEBUGGING_MSTATS>,
+if set, this causes memory statistics to be dumped after execution. If set
+to an integer greater than one, also causes memory statistics to be dumped
+after compilation.
+
+=item PERL_DESTRUCT_LEVEL
+
+Relevant only if your perl executable was built with B<-DDEBUGGING>,
+this controls the behavior of global destruction of objects and other
+references.
=back
+
+Perl also has environment variables that control how Perl handles data
+specific to particular natural languages. See L<perllocale>.
+
+Apart from these, Perl uses no other environment variables, except
+to make them available to the script being executed, and to child
+processes. However, scripts running setuid would do well to execute
+the following lines before doing anything else, just to keep people
+honest:
+
+ $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need
+ $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'};
+ $ENV{'IFS'} = '' if defined $ENV{'IFS'};
+
projects / p5sagit/p5-mst-13.2.git / blobdiff