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 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.
+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
=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
+pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
put in single quotes.
=item B<-h>
causes your script to be run through the C preprocessor before
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,
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>
scalar variables that are used before being set. Also warns about
redefined subroutines, and references to undefined filehandles or
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.
-See L<perldiag> and L<perltrap>.
+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
+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