home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / u_man / cat1 / perlrun.z / perlrun
Encoding:
Text File  |  2002-10-03  |  34.2 KB  |  859 lines

  1.  
  2.  
  3.  
  4. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      perlrun - how to execute the Perl interpreter
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ppppeeeerrrrllll [ ----ssssTTTTuuuuUUUU ]      [ ----hhhhvvvv ] [ ----VVVV[:_c_o_n_f_i_g_v_a_r] ]
  13.           [ ----ccccwwww ] [ ----dddd[:_d_e_b_u_g_g_e_r] ] [ ----DDDD[_n_u_m_b_e_r/_l_i_s_t] ]
  14.           [ ----ppppnnnnaaaa ] [ ----FFFF_p_a_t_t_e_r_n ] [ ----llll[_o_c_t_a_l] ] [ ----0000[_o_c_t_a_l] ]
  15.           [ ----IIII_d_i_r ] [ ----mmmm[----]_m_o_d_u_l_e ] [ ----MMMM[----]'_m_o_d_u_l_e...' ]      [ ----PPPP ]
  16.           [ ----SSSS ]      [ ----xxxx[_d_i_r] ]      [ ----iiii[_e_x_t_e_n_s_i_o_n] ]
  17.           [ ----eeee '_c_o_m_m_a_n_d' ] [ -------- ] [ _p_r_o_g_r_a_m_f_i_l_e ] [ _a_r_g_u_m_e_n_t ]...
  18.  
  19. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  20.      Upon startup, Perl looks for your script in one of the following places:
  21.  
  22.      1.  Specified line by line via ----eeee switches on the command line.
  23.  
  24.      2.  Contained in the file specified by the first filename on the command
  25.          line.  (Note that systems supporting the #! notation invoke
  26.          interpreters this way. See the section on _L_o_c_a_t_i_o_n _o_f _P_e_r_l.)
  27.  
  28.      3.  Passed in implicitly via standard input.  This works only if there
  29.          are no filename arguments--to pass arguments to a STDIN script you
  30.          must explicitly specify a "-" for the script name.
  31.  
  32.      With methods 2 and 3, Perl starts parsing the input file from the
  33.      beginning, unless you've specified a ----xxxx switch, in which case it scans
  34.      for the first line starting with #! and containing the word "perl", and
  35.      starts there instead.  This is useful for running a script embedded in a
  36.      larger message.  (In this case you would indicate the end of the script
  37.      using the __END__ token.)
  38.  
  39.      The #! line is always examined for switches as the line is being parsed.
  40.      Thus, if you're on a machine that allows only one argument with the #!
  41.      line, or worse, doesn't even recognize the #! line, you still can get
  42.      consistent switch behavior regardless of how Perl was invoked, even if ----xxxx
  43.      was used to find the beginning of the script.
  44.  
  45.      Because many operating systems silently chop off kernel interpretation of
  46.      the #! line after 32 characters, some switches may be passed in on the
  47.      command line, and some may not; you could even get a "-" without its
  48.      letter, if you're not careful.  You probably want to make sure that all
  49.      your switches fall either before or after that 32 character boundary.
  50.      Most switches don't actually care if they're processed redundantly, but
  51.      getting a - instead of a complete switch could cause Perl to try to
  52.      execute standard input instead of your script.  And a partial ----IIII switch
  53.      could also cause odd results.
  54.  
  55.      Some switches do care if they are processed twice, for instance
  56.      combinations of ----llll and ----0000.  Either put all the switches after the 32
  57.      character boundary (if applicable), or replace the use of ----0000_d_i_g_i_t_s by
  58.      BEGIN{ $/ = "\0digits"; }.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  71.  
  72.  
  73.  
  74.      Parsing of the #! switches starts wherever "perl" is mentioned in the
  75.      line.  The sequences "-*" and "- " are specifically ignored so that you
  76.      could, if you were so inclined, say
  77.  
  78.          #!/bin/sh -- # -*- perl -*- -p
  79.          eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
  80.              if $running_under_some_shell;
  81.  
  82.      to let Perl see the ----pppp switch.
  83.  
  84.      If the #! line does not contain the word "perl", the program named after
  85.      the #! is executed instead of the Perl interpreter.  This is slightly
  86.      bizarre, but it helps people on machines that don't do #!, because they
  87.      can tell a program that their SHELL is /usr/bin/perl, and Perl will then
  88.      dispatch the program to the correct interpreter for them.
  89.  
  90.      After locating your script, Perl compiles the entire script to an
  91.      internal form.  If there are any compilation errors, execution of the
  92.      script is not attempted.  (This is unlike the typical shell script, which
  93.      might run part-way through before finding a syntax error.)
  94.  
  95.      If the script is syntactically correct, it is executed.  If the script
  96.      runs off the end without hitting an _e_x_i_t() or _d_i_e() operator, an implicit
  97.      exit(0) is provided to indicate successful completion.
  98.  
  99.      ####!!!! aaaannnndddd qqqquuuuoooottttiiiinnnngggg oooonnnn nnnnoooonnnn----UUUUnnnniiiixxxx ssssyyyysssstttteeeemmmmssss
  100.  
  101.      Unix's #! technique can be simulated on other systems:
  102.  
  103.      OS/2
  104.          Put
  105.  
  106.              extproc perl -S -your_switches
  107.  
  108.          as the first line in *.cmd file (-S due to a bug in cmd.exe's
  109.          `extproc' handling).
  110.  
  111.      MS-DOS
  112.          Create a batch file to run your script, and codify it in
  113.          ALTERNATIVE_SHEBANG (see the _d_o_s_i_s_h._h file in the source distribution
  114.          for more information).
  115.  
  116.      Win95/NT
  117.          The Win95/NT installation, when using the Activeware port of Perl,
  118.          will modify the Registry to associate the .pl extension with the perl
  119.          interpreter.  If you install another port of Perl, including the one
  120.          in the Win32 directory of the Perl distribution, then you'll have to
  121.          modify the Registry yourself.
  122.  
  123.      Macintosh
  124.          Macintosh perl scripts will have the appropriate Creator and Type, so
  125.          that double-clicking them will invoke the perl application.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  137.  
  138.  
  139.  
  140.      Command-interpreters on non-Unix systems have rather different ideas on
  141.      quoting than Unix shells.  You'll need to learn the special characters in
  142.      your command-interpreter (*, \ and " are common) and how to protect
  143.      whitespace and these characters to run one-liners (see -e below).
  144.  
  145.      On some systems, you may have to change single-quotes to double ones,
  146.      which you must _N_O_T do on Unix or Plan9 systems.  You might also have to
  147.      change a single % to a %%.
  148.  
  149.      For example:
  150.  
  151.          # Unix
  152.          perl -e 'print "Hello world\n"'
  153.  
  154.          # MS-DOS, etc.
  155.          perl -e "print \"Hello world\n\""
  156.  
  157.          # Macintosh
  158.          print "Hello world\n"
  159.           (then Run "Myscript" or Shift-Command-R)
  160.  
  161.          # VMS
  162.          perl -e "print ""Hello world\n"""
  163.  
  164.      The problem is that none of this is reliable: it depends on the command
  165.      and it is entirely possible neither works.  If 4DOS was the command
  166.      shell, this would probably work better:
  167.  
  168.          perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
  169.  
  170.      CMD.EXE in Windows NT slipped a lot of standard Unix functionality in
  171.      when nobody was looking, but just try to find documentation for its
  172.      quoting rules.
  173.  
  174.      Under the Macintosh, it depends which environment you are using.  The
  175.      MacPerl shell, or MPW, is much like Unix shells in its support for
  176.      several quoting variants, except that it makes free use of the
  177.      Macintosh's non-ASCII characters as control characters.
  178.  
  179.      There is no general solution to all of this.  It's just a mess.
  180.  
  181.      LLLLooooccccaaaattttiiiioooonnnn ooooffff PPPPeeeerrrrllll
  182.  
  183.      It may seem obvious to say, but Perl is useful only when users can easily
  184.      find it. When possible, it's good for both ////uuuussssrrrr////bbbbiiiinnnn////ppppeeeerrrrllll and
  185.      ////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn////ppppeeeerrrrllll to be symlinks to the actual binary. If that can't be
  186.      done, system administrators are strongly encouraged to put (symlinks to)
  187.      perl and its accompanying utilities, such as perldoc, into a directory
  188.      typically found along a user's PATH, or in another obvious and convenient
  189.      place.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  203.  
  204.  
  205.  
  206.      In this documentation, #!/usr/bin/perl on the first line of the script
  207.      will stand in for whatever method works on your system.
  208.  
  209.      SSSSwwwwiiiittttcccchhhheeeessss
  210.  
  211.      A single-character switch may be combined with the following switch, if
  212.      any.
  213.  
  214.          #!/usr/bin/perl -spi.bak    # same as -s -p -i.bak
  215.  
  216.      Switches include:
  217.  
  218.      ----0000[_d_i_g_i_t_s]
  219.           specifies the input record separator ($/) as an octal number.  If
  220.           there are no digits, the null character is the separator.  Other
  221.           switches may precede or follow the digits.  For example, if you have
  222.           a version of ffffiiiinnnndddd which can print filenames terminated by the null
  223.           character, you can say this:
  224.  
  225.               find . -name '*.bak' -print0 | perl -n0e unlink
  226.  
  227.           The special value 00 will cause Perl to slurp files in paragraph
  228.           mode.  The value 0777 will cause Perl to slurp files whole because
  229.           there is no legal character with that value.
  230.  
  231.      ----aaaa   turns on autosplit mode when used with a ----nnnn or ----pppp.  An implicit
  232.           split command to the @F array is done as the first thing inside the
  233.           implicit while loop produced by the ----nnnn or ----pppp.
  234.  
  235.               perl -ane 'print pop(@F), "\n";'
  236.  
  237.           is equivalent to
  238.  
  239.               while (<>) {
  240.                   @F = split(' ');
  241.                   print pop(@F), "\n";
  242.               }
  243.  
  244.           An alternate delimiter may be specified using ----FFFF.
  245.  
  246.      ----cccc   causes Perl to check the syntax of the script and then exit without
  247.           executing it.  Actually, it _w_i_l_l execute BEGIN, END, and use blocks,
  248.           because these are considered as occurring outside the execution of
  249.           your program.
  250.  
  251.      ----dddd   runs the script under the Perl debugger.  See the _p_e_r_l_d_e_b_u_g manpage.
  252.  
  253.      ----dddd::::_f_o_o
  254.           runs the script under the control of a debugging or tracing module
  255.           installed as Devel::foo. E.g., ----dddd::::DDDDPPPPrrrrooooffff executes the script using
  256.           the Devel::DProf profiler.  See the _p_e_r_l_d_e_b_u_g manpage.
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  269.  
  270.  
  271.  
  272.      ----DDDD_l_e_t_t_e_r_s
  273.  
  274.      ----DDDD_n_u_m_b_e_r
  275.           sets debugging flags.  To watch how it executes your script, use
  276.           ----DDDDttttllllssss.  (This works only if debugging is compiled into your Perl.)
  277.           Another nice value is ----DDDDxxxx, which lists your compiled syntax tree.
  278.           And ----DDDDrrrr displays compiled regular expressions. As an alternative,
  279.           specify a number instead of list of letters (e.g., ----DDDD11114444 is
  280.           equivalent to ----DDDDttttllllssss):
  281.  
  282.                   1  p  Tokenizing and parsing
  283.                   2  s  Stack snapshots
  284.                   4  l  Context (loop) stack processing
  285.                   8  t  Trace execution
  286.                  16  o  Method and overloading resolution
  287.                  32  c  String/numeric conversions
  288.                  64  P  Print preprocessor command for -P
  289.                 128  m  Memory allocation
  290.                 256  f  Format processing
  291.                 512  r  Regular expression parsing and execution
  292.                1024  x  Syntax tree dump
  293.                2048  u  Tainting checks
  294.                4096  L  Memory leaks (needs C<-DLEAKTEST> when compiling Perl)
  295.                8192  H  Hash dump -- usurps values()
  296.               16384  X  Scratchpad allocation
  297.               32768  D  Cleaning up
  298.  
  299.           All these flags require -DDEBUGGING when you compile the Perl
  300.           executable.  This flag is automatically set if you include -g option
  301.           when Configure asks you about optimizer/debugger flags.
  302.  
  303.      ----eeee _c_o_m_m_a_n_d_l_i_n_e
  304.           may be used to enter one line of script.  If ----eeee is given, Perl will
  305.           not look for a script filename in the argument list.  Multiple ----eeee
  306.           commands may be given to build up a multi-line script.  Make sure to
  307.           use semicolons where you would in a normal program.
  308.  
  309.      ----FFFF_p_a_t_t_e_r_n
  310.           specifies the pattern to split on if ----aaaa is also in effect.  The
  311.           pattern may be surrounded by //, "", or '', otherwise it will be put
  312.           in single quotes.
  313.  
  314.      ----hhhh   prints a summary of the options.
  315.  
  316.      ----iiii[_e_x_t_e_n_s_i_o_n]
  317.           specifies that files processed by the <> construct are to be edited
  318.           in-place.  It does this by renaming the input file, opening the
  319.           output file by the original name, and selecting that output file as
  320.           the default for _p_r_i_n_t() statements.  The extension, if supplied, is
  321.           added to the name of the old file to make a backup copy.  If no
  322.           extension is supplied, no backup is made.  From the shell, saying
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  335.  
  336.  
  337.  
  338.               $ perl -p -i.bak -e "s/foo/bar/; ... "
  339.  
  340.           is the same as using the script:
  341.  
  342.               #!/usr/bin/perl -pi.bak
  343.               s/foo/bar/;
  344.  
  345.           which is equivalent to
  346.  
  347.               #!/usr/bin/perl
  348.               while (<>) {
  349.                   if ($ARGV ne $oldargv) {
  350.                       rename($ARGV, $ARGV . '.bak');
  351.                       open(ARGVOUT, ">$ARGV");
  352.                       select(ARGVOUT);
  353.                       $oldargv = $ARGV;
  354.                   }
  355.                   s/foo/bar/;
  356.               }
  357.               continue {
  358.                   print;  # this prints to original filename
  359.               }
  360.               select(STDOUT);
  361.  
  362.           except that the ----iiii form doesn't need to compare $ARGV to $oldargv to
  363.           know when the filename has changed.  It does, however, use ARGVOUT
  364.           for the selected filehandle.  Note that STDOUT is restored as the
  365.           default output filehandle after the loop.
  366.  
  367.           You can use eof without parentheses to locate the end of each input
  368.           file, in case you want to append to each file, or reset line
  369.           numbering (see example in the eof entry in the _p_e_r_l_f_u_n_c manpage).
  370.  
  371.           Finally, note that the ----iiii switch does not impede execution when no
  372.           files are given on the command line.  In this case, no backup is
  373.           made (the original file cannot, of course, be determined) and
  374.           processing proceeds from STDIN to STDOUT as might be expected.
  375.  
  376.      ----IIII_d_i_r_e_c_t_o_r_y
  377.           Directories specified by ----IIII are prepended to the search path for
  378.           modules (@INC), and also tells the C preprocessor where to search
  379.           for include files.  The C preprocessor is invoked with ----PPPP; by
  380.           default it searches /usr/include and /usr/lib/perl.
  381.  
  382.      ----llll[_o_c_t_n_u_m]
  383.           enables automatic line-ending processing.  It has two effects:
  384.           first, it automatically chomps "$/" (the input record separator)
  385.           when used with ----nnnn or ----pppp, and second, it assigns "$\" (the output
  386.           record separator) to have the value of _o_c_t_n_u_m so that any print
  387.           statements will have that separator added back on.  If _o_c_t_n_u_m is
  388.           omitted, sets "$\" to the current value of "$/".  For instance, to
  389.           trim lines to 80 columns:
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  401.  
  402.  
  403.  
  404.               perl -lpe 'substr($_, 80) = ""'
  405.  
  406.           Note that the assignment $\ = $/ is done when the switch is
  407.           processed, so the input record separator can be different than the
  408.           output record separator if the ----llll switch is followed by a ----0000 switch:
  409.  
  410.               gnufind / -print0 | perl -ln0e 'print "found $_" if -p'
  411.  
  412.           This sets $\ to newline and then sets $/ to the null character.
  413.  
  414.      ----mmmm[----]_m_o_d_u_l_e
  415.  
  416.      ----MMMM[----]_m_o_d_u_l_e
  417.  
  418.      ----MMMM[----]'_m_o_d_u_l_e ...'
  419.  
  420.      ----[[[[mmmmMMMM]]]][----]_m_o_d_u_l_e=_a_r_g[,_a_r_g]...
  421.           -m_m_o_d_u_l_e executes use _m_o_d_u_l_e (); before executing your script.
  422.  
  423.           -M_m_o_d_u_l_e executes use _m_o_d_u_l_e ; before executing your script.  You
  424.           can use quotes to add extra code after the module name, e.g.,
  425.           -M'module qw(foo bar)'.
  426.  
  427.           If the first character after the -M or -m is a dash (-) then the
  428.           'use' is replaced with 'no'.
  429.  
  430.           A little builtin syntactic sugar means you can also say
  431.           -mmodule=foo,bar or -Mmodule=foo,bar as a shortcut for -M'module
  432.           qw(foo bar)'.  This avoids the need to use quotes when importing
  433.           symbols.  The actual code generated by -Mmodule=foo,bar is use
  434.           module split(/,/,q{foo,bar}).  Note that the = form removes the
  435.           distinction between -m and -M.
  436.  
  437.      ----nnnn   causes Perl to assume the following loop around your script, which
  438.           makes it iterate over filename arguments somewhat like sssseeeedddd ----nnnn or
  439.           aaaawwwwkkkk:
  440.  
  441.               while (<>) {
  442.                   ...             # your script goes here
  443.               }
  444.  
  445.           Note that the lines are not printed by default.  See ----pppp to have
  446.           lines printed.  If a file named by an argument cannot be opened for
  447.           some reason, Perl warns you about it, and moves on to the next file.
  448.  
  449.           Here is an efficient way to delete all files older than a week:
  450.  
  451.               find . -mtime +7 -print | perl -nle 'unlink;'
  452.  
  453.           This is faster than using the -exec switch of ffffiiiinnnndddd because you don't
  454.           have to start a process on every filename found.
  455.  
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  467.  
  468.  
  469.  
  470.           BEGIN and END blocks may be used to capture control before or after
  471.           the implicit loop, just as in aaaawwwwkkkk.
  472.  
  473.      ----pppp   causes Perl to assume the following loop around your script, which
  474.           makes it iterate over filename arguments somewhat like sssseeeedddd:
  475.  
  476.               while (<>) {
  477.                   ...             # your script goes here
  478.               } continue {
  479.                   print or die "-p destination: $!\n";
  480.               }
  481.  
  482.           If a file named by an argument cannot be opened for some reason,
  483.           Perl warns you about it, and moves on to the next file.  Note that
  484.           the lines are printed automatically.  An error occuring during
  485.           printing is treated as fatal.  To suppress printing use the ----nnnn
  486.           switch.  A ----pppp overrides a ----nnnn switch.
  487.  
  488.           BEGIN and END blocks may be used to capture control before or after
  489.           the implicit loop, just as in awk.
  490.  
  491.      ----PPPP   causes your script to be run through the C preprocessor before
  492.           compilation by Perl.  (Because both comments and cpp directives
  493.           begin with the # character, you should avoid starting comments with
  494.           any words recognized by the C preprocessor such as "if", "else", or
  495.           "define".)
  496.  
  497.      ----ssss   enables some rudimentary switch parsing for switches on the command
  498.           line after the script name but before any filename arguments (or
  499.           before a --------).  Any switch found there is removed from @ARGV and sets
  500.           the corresponding variable in the Perl script.  The following script
  501.           prints "true" if and only if the script is invoked with a ----xxxxyyyyzzzz
  502.           switch.
  503.  
  504.               #!/usr/bin/perl -s
  505.               if ($xyz) { print "true\n"; }
  506.  
  507.  
  508.      ----SSSS   makes Perl use the PATH environment variable to search for the
  509.           script (unless the name of the script contains directory
  510.           separators).  On some platforms, this also makes Perl append
  511.           suffixes to the filename while searching for it.  For example, on
  512.           Win32 platforms, the ".bat" and ".cmd" suffixes are appended if a
  513.           lookup for the original name fails, and if the name does not already
  514.           end in one of those suffixes.  If your Perl was compiled with
  515.           DEBUGGING turned on, using the -Dp switch to Perl shows how the
  516.           search progresses.
  517.  
  518.           If the filename supplied contains directory separators (i.e. it is
  519.           an absolute or relative pathname), and if the file is not found,
  520.           platforms that append file extensions will do so and try to look for
  521.           the file with those extensions added, one by one.
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  533.  
  534.  
  535.  
  536.           On DOS-like platforms, if the script does not contain directory
  537.           separators, it will first be searched for in the current directory
  538.           before being searched for on the PATH.  On Unix platforms, the
  539.           script will be searched for strictly on the PATH.
  540.  
  541.           Typically this is used to emulate #! startup on platforms that don't
  542.           support #!.  This example works on many platforms that have a shell
  543.           compatible with Bourne shell:
  544.  
  545.               #!/usr/bin/perl
  546.               eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
  547.                       if $running_under_some_shell;
  548.  
  549.           The system ignores the first line and feeds the script to /bin/sh,
  550.           which proceeds to try to execute the Perl script as a shell script.
  551.           The shell executes the second line as a normal shell command, and
  552.           thus starts up the Perl interpreter.  On some systems $0 doesn't
  553.           always contain the full pathname, so the ----SSSS tells Perl to search for
  554.           the script if necessary.  After Perl locates the script, it parses
  555.           the lines and ignores them because the variable
  556.           $running_under_some_shell is never true. If the script will be
  557.           interpreted by csh, you will need to replace ${1+"$@"} with $*, even
  558.           though that doesn't understand embedded spaces (and such) in the
  559.           argument list.  To start up sh rather than csh, some systems may
  560.           have to replace the #! line with a line containing just a colon,
  561.           which will be politely ignored by Perl.  Other systems can't control
  562.           that, and need a totally devious construct that will work under any
  563.           of csh, sh, or Perl, such as the following:
  564.  
  565.                   eval '(exit $?0)' && eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
  566.                   & eval 'exec /usr/bin/perl -wS $0 $argv:q'
  567.                           if $running_under_some_shell;
  568.  
  569.  
  570.      ----TTTT   forces "taint" checks to be turned on so you can test them.
  571.           Ordinarily these checks are done only when running setuid or setgid.
  572.           It's a good idea to turn them on explicitly for programs run on
  573.           another's behalf, such as CGI programs.  See the _p_e_r_l_s_e_c manpage.
  574.           Note that (for security reasons) this option must be seen by Perl
  575.           quite early; usually this means it must appear early on the command
  576.           line or in the #! line (for systems which support that).
  577.  
  578.      ----uuuu   causes Perl to dump core after compiling your script.  You can then
  579.           in theory take this core dump and turn it into an executable file by
  580.           using the uuuunnnndddduuuummmmpppp program (not supplied).  This speeds startup at the
  581.           expense of some disk space (which you can minimize by stripping the
  582.           executable).  (Still, a "hello world" executable comes out to about
  583.           200K on my machine.)  If you want to execute a portion of your
  584.           script before dumping, use the _d_u_m_p() operator instead.  Note:
  585.           availability of uuuunnnndddduuuummmmpppp is platform specific and may not be available
  586.           for a specific port of Perl.  It has been superseded by the new
  587.           perl-to-C compiler, which is more portable, even though it's still
  588.  
  589.  
  590.  
  591.                                                                         PPPPaaaaggggeeee 9999
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  599.  
  600.  
  601.  
  602.           only considered beta.
  603.  
  604.      ----UUUU   allows Perl to do unsafe operations.  Currently the only "unsafe"
  605.           operations are the unlinking of directories while running as
  606.           superuser, and running setuid programs with fatal taint checks
  607.           turned into warnings. Note that the ----wwww switch (or the $^W variable)
  608.           must be used along with this option to actually ggggeeeennnneeeerrrraaaatttteeee the taint-
  609.           check warnings.
  610.  
  611.      ----vvvv   prints the version and patchlevel of your Perl executable.
  612.  
  613.      ----VVVV   prints summary of the major perl configuration values and the
  614.           current value of @INC.
  615.  
  616.      ----VVVV::::_n_a_m_e
  617.           Prints to STDOUT the value of the named configuration variable.
  618.  
  619.      ----wwww   prints warnings about variable names that are mentioned only once,
  620.           and scalar variables that are used before being set.  Also warns
  621.           about redefined subroutines, and references to undefined filehandles
  622.           or filehandles opened read-only that you are attempting to write on.
  623.           Also warns you if you use values as a number that doesn't look like
  624.           numbers, using an array as though it were a scalar, if your
  625.           subroutines recurse more than 100 deep, and innumerable other
  626.           things.
  627.  
  628.           You can disable specific warnings using __WARN__ hooks, as described
  629.           in the _p_e_r_l_v_a_r manpage and the warn entry in the _p_e_r_l_f_u_n_c manpage.
  630.           See also the _p_e_r_l_d_i_a_g manpage and the _p_e_r_l_t_r_a_p manpage.
  631.  
  632.      ----xxxx _d_i_r_e_c_t_o_r_y
  633.           tells Perl that the script is embedded in a message.  Leading
  634.           garbage will be discarded until the first line that starts with #!
  635.           and contains the string "perl".  Any meaningful switches on that
  636.           line will be applied.  If a directory name is specified, Perl will
  637.           switch to that directory before running the script.  The ----xxxx switch
  638.           controls only the disposal of leading garbage.  The script must be
  639.           terminated with __END__ if there is trailing garbage to be ignored
  640.           (the script can process any or all of the trailing garbage via the
  641.           DATA filehandle if desired).
  642.  
  643. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
  644.      HOME        Used if chdir has no argument.
  645.  
  646.      LOGDIR      Used if chdir has no argument and HOME is not set.
  647.  
  648.      PATH        Used in executing subprocesses, and in finding the script if
  649.                  ----SSSS is used.
  650.  
  651.      PERL5LIB    A colon-separated list of directories in which to look for
  652.                  Perl library files before looking in the standard library and
  653.                  the current directory.  If PERL5LIB is not defined, PERLLIB
  654.  
  655.  
  656.  
  657.                                                                        PPPPaaaaggggeeee 11110000
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  665.  
  666.  
  667.  
  668.                  is used.  When running taint checks (because the script was
  669.                  running setuid or setgid, or the ----TTTT switch was used), neither
  670.                  variable is used.  The script should instead say
  671.  
  672.                      use lib "/my/directory";
  673.  
  674.  
  675.      PERL5OPT    Command-line options (switches).  Switches in this variable
  676.                  are taken as if they were on every Perl command line.  Only
  677.                  the ----[[[[DDDDIIIIMMMMUUUUddddmmmmwwww]]]] switches are allowed.  When running taint
  678.                  checks (because the script was running setuid or setgid, or
  679.                  the ----TTTT switch was used), this variable is ignored.
  680.  
  681.      PERLLIB     A colon-separated list of directories in which to look for
  682.                  Perl library files before looking in the standard library and
  683.                  the current directory.  If PERL5LIB is defined, PERLLIB is
  684.                  not used.
  685.  
  686.      PERL5DB     The command used to load the debugger code.  The default is:
  687.  
  688.                          BEGIN { require 'perl5db.pl' }
  689.  
  690.  
  691.      PERL5SHELL (specific to WIN32 port)
  692.                  May be set to an alternative shell that perl must use
  693.                  internally for executing "backtick" commands or _s_y_s_t_e_m().
  694.                  Default is cmd.exe /x/c on WindowsNT and command.com /c on
  695.                  Windows95.  The value is considered to be space delimited.
  696.                  Precede any character that needs to be protected (like a
  697.                  space or backslash) with a backslash.
  698.  
  699.                  Note that Perl doesn't use COMSPEC for this purpose because
  700.                  COMSPEC has a high degree of variability among users, leading
  701.                  to portability concerns.  Besides, perl can use a shell that
  702.                  may not be fit for interactive use, and setting COMSPEC to
  703.                  such a shell may interfere with the proper functioning of
  704.                  other programs (which usually look in COMSPEC to find a shell
  705.                  fit for interactive use).
  706.  
  707.      PERL_DEBUG_MSTATS
  708.                  Relevant only if perl is compiled with the malloc included
  709.                  with the perl distribution (that is, if perl -V:d_mymalloc is
  710.                  'define').  If set, this causes memory statistics to be
  711.                  dumped after execution.  If set to an integer greater than
  712.                  one, also causes memory statistics to be dumped after
  713.                  compilation.
  714.  
  715.      PERL_DESTRUCT_LEVEL
  716.                  Relevant only if your perl executable was built with
  717.                  ----DDDDDDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG, this controls the behavior of global destruction
  718.                  of objects and other references.
  719.  
  720.  
  721.  
  722.  
  723.                                                                        PPPPaaaaggggeeee 11111111
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  731.  
  732.  
  733.  
  734.      Perl also has environment variables that control how Perl handles data
  735.      specific to particular natural languages.  See the _p_e_r_l_l_o_c_a_l_e manpage.
  736.  
  737.      Apart from these, Perl uses no other environment variables, except to
  738.      make them available to the script being executed, and to child processes.
  739.      However, scripts running setuid would do well to execute the following
  740.      lines before doing anything else, just to keep people honest:
  741.  
  742.          $ENV{PATH} = '/bin:/usr/bin';    # or whatever you need
  743.          $ENV{SHELL} = '/bin/sh' if exists $ENV{SHELL};
  744.          delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.                                                                        PPPPaaaaggggeeee 11112222
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))                                                          PPPPEEEERRRRLLLLRRRRUUUUNNNN((((1111))))
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.                                                                        PPPPaaaaggggeeee 11113333
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.