Perl-CGI

DOCUMENTATION

• NAME
• DESCRIPTION
• Functions by Category
• ESCAPING FROM HTML
• MULTILINE COMMENTS
• PREDEFINED VARIABLES
• CONTROL FUNCTIONS
• VARIABLE HANDLING FUNCTIONS
• HTTP FUNCTIONS
• DATE AND TIME FUNCTIONS
• STRING FUNCTIONS
• FILESYSTEM FUNCTIONS
• HANDLING FILE UPLOADS
• File Upload Functions
• File Upload Error Codes
• SESSION HANDLING
• Passing the Session ID
• Session Handling Functions
• DESCRIPTION OF CONFIG DIRECTIVES
• Resource Limits
• File Uploads
• Sessions
• RESTRICTIONS
• AUTHORS
• COPYRIGHT
• SEE ALSO

NAME

DESCRIPTION

• Access to GET, POST variables, cookies and uploaded files in an easy manner
• Embedding Perl into HTML and other documents
• Providing script based locale and time functionality
• Use sessions to hold client data easily
• Implements multiline comments

Functions by Category

cfg_get, error_reporting, gateway, include, include_once, register_cleanup, require, require_once, require_pl

dump_var, is_array, is_double, is_float, is_hash, is_int, is_integer, is_long, is_numeric, is_object, is_string, is_unicode, is_unsigned, print_var, show_var, typeof

header, setcookie, decode_uri, decode_uri_component, encode_uri, encode_uri_component

gmmktime, gmstrftime, localtime, microtime, mktime, set_timezone, strftime

number_format, set_locale, set_user_locale, str_ireplace, str_replace, strfmon

copy_file, file_exists, file_get, file_put, file_stat, file_touch, fullpath, tmpfile

is_uploaded_file, move_uploaded_file

session_cache_expire, session_cache_limiter, session_destroy, session_id, session_name, session_regenerate_id, session_save_path, session_set_handler, session_start

ESCAPING FROM HTML

  <p>This is going to be ignored.</p>
  <?perl print 'While this is going to be parsed.'; ?>
  <p>This will also be ignored.</p>

  <?perl
  if( $expression ) { 
      ?>
      <strong>This is true.</strong>
      <?
  } else { 
      ?>
      <strong>This is false.</strong>
      <?
  }
  ?> 

  1.  <?perl print 'If you want to serve XML documents, do like this'; ?>
  
  2.  <script language="perl">
          print "Also suitable to server XML or XHTML documents";
      </script>
  
  3.  <? print 'This is a SGML processing instruction' ?>
      <?= expression ?> This is a shortcut for "<? print expression ?>"
  
  4.  <* print 'Or, you can use Perl-CGI style tags' *>
      <*= $variable *> This is a shortcut for "<* print $variable *>"

MULTILINE COMMENTS

  <?perl
  
  =#
  perl-cgi multi
  line comment
  #=
  
  print =# comment #= "not commented\n";
  
  #(
  this is a multi
  line comment
  )
  
  my $var = #{ foo bar } 32;
  
  ?>

PREDEFINED VARIABLES

%App::GET

A hash of variables passed to the current script via the HTTP GET method.

%App::POST

A hash of variables passed to the current script via the HTTP POST method.

%App::REQUEST

A hash consisting of the contents of %App::GET and %App::POST.

%App::COOKIE

A hash of variables passed to the current script via HTTP cookies.

%App::FILES

A hash of items uploaded to the current script via the HTTP POST method.

%App::SESSION

A hash containing session variables available to the current script. See the Session handling documentation for more information on how this is used.

CONTROL FUNCTIONS

App::include ( $filename )

The include() function includes and evaluates the specified Perl-CGI file.

include() is identical to require() except how they handle failure. They both produce a Warning, but require() results in a Fatal Error.

Files for including are first looked in the directory of current script, and then in the include paths defined in @INC.

When a file is included, the code it contains is global to current package.

Basic include example

vars.plc

  <?perl
  
  $color = 'green';
  $fruit = 'apple';
  
  ?>

test.plc

  <?perl
  
  print "A $color $fruit"; # A
  
  App::include( 'vars.plc' );
  
  print "A $color $fruit"; # A green apple
  
  ?>

App::include_once ( $filename )

The include_once() function includes and evaluates the specified file during the execution of the script. This is a behavior similar to the include() function, with the only difference being that if the code from a file has already been included, it will not be included again. As the name suggests, it will be included just once.

App::require ( $filename )

The require() function includes and evaluates the specific file.

Detailed information on how this inclusion works is described in the documentation for include().

App::require_once ( $filename )

The require_once() function includes and evaluates the specified file during the execution of the script. This is a behavior similar to the require() function, with the only difference being that if the code from a file has already been included, it will not be included again.

App::require_pl ( $filename )

The require_pl() function includes and evaluates a specified perl file.

require_pl() arbeitet ähnlich wie das Perl require statement, mit dem Unterschied, wenn das eingefügte Skript ohne eigenen Namensraum arbeitet, werden alle dort definierten Variablen und Funktionen im unshared mode gelöscht. Durch require_pl wird sichergestellt, daß beim erneuten Aufruf das Skript auch wieder geladen wird, was mit dem Perl Statement so nicht funktioniert.

Das require statement von Perl sollte nur im Zusammenhang mit Modulen verwendet werden, die ihren eigenen Namensraum benutzen und auch im unshared mode resistent im Arbeitsspeicher gehalten werden sollen.

App::register_cleanup ( $cleanup [, $arg] )

Register a cleanup function which is called just before the request is destroyed.

  <?perl
  
  App::register_cleanup( \&my_cleanup );
  
  sub my_cleanup {
      warn "registered cleanup called";
  }
  
  ?>

Within objects

  <?perl
  
  $obj = My->new();
  
  App::register_cleanup( 'cleanup', $obj );
  
  package My;
  
  sub new {
      bless( {}, shift );
  }
  
  sub cleanup {
      my $this = shift;
      warn "registered cleanup called";
  }
  
  1;
  
  ?>

App::error_reporting ( [$display [, $full [, $log]]] )

error_reporting returns the current error reporting settings and/or sets it to a new value.

Parameters

display

Enable or disable printing error messages to the screen.

Enable or disable printing error message with filename and line number included. It considers only the last error.

Enable or disable sending error messages to STDERR.

  <?perl
  
  # disable printing errors to the screen
  @erep = App::error_reporting( 0 );
  
  warn "this message will not be print";
  
  # restore previous settings
  App::error_reporting( @erep );
  
  ?>

  <?perl
  
  if( App::cfg_get( 'file_uploads' ) ) {
      print "file uploads are enabled\n";
  }
  else {
      print "file uploads are not available\n";
  }
  
  ?>

VARIABLE HANDLING FUNCTIONS

App::show_var ( $var )

show_var returns information about a variable in a way that's readable by humans.

App::print_var ( $var )

print_var prints information about a variable in a way that's readable by humans.

App::dump_var ( $var [, $name] )

dump_var() gets structured information about the given variable. It is similar to show_var() with one exception: the returned representation is valid Perl code.

Parameters

var

The variable you want to dump

The name of the variable. It may start with '*', '$', '%' or '@'.

  <?perl
  
  $a = [ 1, 2, { 'a' => 1, 'b' => 2 } ];
  
  print App::dump_var( $a, 'a' );
  
  # will output:
  $a = [
          1,
          2,
          {
                  'a' => 1,
                  'b' => 2,
          },
  ];
  
  print App::dump_var( $a, '*a' );
  
  # will output:
  @a = (
          1,
          2,
          {
                  'a' => 1,
                  'b' => 2,
          },
  );
  
  ?>

• "integer"
• "double"
• "string"
• "array"
• "hash"
• "object"
• "glob"
• "code"
• "undef"
• "unknown type"

HTTP FUNCTIONS

App::header ( $string [, $replace] )

header() is used to send a raw HTTP header. See the http://www.faqs.org/rfcs/rfc2616 specification for more information on HTTP headers.

Remember that header() must be called before any actual output is sent.

Parameters

string

There are two special-case header calls. The first is a header that starts with the string "HTTP/" (case is not significant), which will be used to figure out the HTTP status code to send. For example, if you have configured Apache to use a Perl-CGI script to handle requests for missing files (using the ErrorDocument directive), you may want to make sure that your script generates the proper status code.

  <?perl
  App::header( 'HTTP/1.0 404 Not Found' );
  ?>

The second special case is the "Location:" header. Not only does it send this header back to the browser, but it also returns a REDIRECT (302) status code to the browser unless some 3xx status code has already been set.

  <?perl
  # Redirect browser
  App::header( 'Location: http://www.example.com/' );
  # Make sure that code below does not get executed when we redirect.
  exit;
  ?>

The optional replace parameter indicates whether the header should replace a previous similar header, or add a second header of the same type. By default it will replace, but if you pass in FALSE as the second argument you can force multiple headers of the same type. For example:

  <?perl
  App::header( 'WWW-Authenticate: Negotiate' );
  App::header( 'WWW-Authenticate: NTLM', 0 );
  ?>

The value of the cookie. This value is stored on the clients computer; do not store sensitive information. Assuming the name is 'cookiename', this value is retrieved through $App::COOKIE{'cookiename'}

The time the cookie expires. This is a Unix timestamp so is in number of seconds since the epoch. In other words, you'll most likely set this with the time function plus the number of seconds before you want it to expire. time+60*60*24*30 will set the cookie to expire in 30 days. If set to 0, or omitted, the cookie will expire at the end of the session (when the browser closes).

The path on the server in which the cookie will be available on. If set to '/', the cookie will be available within the entire domain. If set to '/foo/', the cookie will only be available within the /foo/ directory and all sub-directories such as /foo/bar/ of domain. The default value is the current directory that the cookie is being set in.

The domain that the cookie is available. To make the cookie available on all subdomains of example.com then you'd set it to '.example.com'. The . is not required but makes it compatible with more browsers. Setting it to www.example.com will make the cookie only available in the www subdomain.

Indicates that the cookie should only be transmitted over a secure HTTPS connection from the client. When set to TRUE, the cookie will only be set if a secure connection exists. The default is FALSE.

When TRUE the cookie will be made accessible only through the HTTP protocol. This means that the cookie won't be accessible by scripting languages, such as JavaScript. This setting can effectly help to reduce identity theft through XSS attacks (although it is not supported by all browsers).

  0 to 9
  A to Z
  a to z
  - _ . ! ~ * ' ( )
  , / ? : @ & = + $

  0 to 9
  A to Z
  a to z
  - _ . ! ~ * ' ( )

DATE AND TIME FUNCTIONS

App::microtime ()

Returns the current unix timestamp in microseconds as a floating point number.

Example

  <?perl
  
  $time_start = App::microtime();
  
  sleep( 1 );
  
  $time_end = App::microtime();
  $time_elapsed = $time_end - $time_start;
  print "Slept for $time_elapsed seconds\n;
  
  ?>

App::set_timezone ( $zone )

Sets the time zone.

Parameters

zone

The timezone identifier, like 'UTC' or 'Europe/Lisabon'. A list of identifiers can be found here: http://php.net/manual/timezones.php.

  <?perl
  
  #  0    1    2     3     4    5     6     7     8
  ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = App::localtime;
  
  ?>

     %A    is replaced by the locale's full weekday name.
     
     %a    is replaced by the locale's abbreviated weekday name.
     
     %B    is replaced by the locale's full month name.
     
     %b or %h
           is replaced by the locale's abbreviated month name.
     
     %C    is replaced by the century (a year divided by 100 and
           truncated to an integer) as a decimal number [00,99].
     
     %c or %+
           is replaced by the locale's appropriate date and time
           representation.
     
     %D    is replaced by the date in the format ``%m/%d/%y''.
     
     %d    is replaced by the day of the month as a decimal number
           [01,31].
     
     %e    is replaced by the day of month as a decimal number [1,31];
           single digits are preceded by a blank.
     
     %F    is replaced by the date in the format ``%Y-%m-%d''
           (the ISO 8601 date format).
     
     %G    is replaced by the ISO 8601 year with century as a decimal
           number.
     
     %g    is replaced by the ISO 8601 year without century as a
           decimal number (00-99).  This is the year that includes the
           greater part of the week. (Monday as the first day of a
           week). See also the '%V' conversion specification.
     
     %H    is replaced by the hour (24-hour clock) as a decimal
           number [00,23].
     
     %I    is replaced by the hour (12-hour clock) as a decimal
           number [01,12].
     
     %j    is replaced by the day of the year as a decimal number
           [001,366].
     
     %k    is replaced by the hour (24-hour clock) as a decimal
           number [0,23]; single digits are preceded by a blank.
     
     %l    is replaced by the hour (12-hour clock) as a decimal
           number [1,12]; single digits are preceded by a blank.
     
     %M    is replaced by the minute as a decimal number [00,59].
     
     %m    is replaced by the month as a decimal number [01,12].
     
     %n    is replaced by a newline.
     
     %o or %O
           is replaced by the offset from UTC in seconds.
     
     %p    is replaced by the locale's equivalent of either
           "AM" or "PM".
     
     %P    is replaced by the locale's equivalent of either
           "AM" or "PM" represented in lower case format.
     
     %R    is replaced by the time in the format "%H:%M".
     
     %r    is replaced by the locale's representation of 12-hour
           clock time using AM/PM notation.
     
     %S    is replaced by the second as a decimal number [00,61].
           The range of seconds is (00-61) instead of (00-59) to
           allow for the periodic occurrence of leap seconds and
           double leap seconds.
     
     %s    is replaced by the number of seconds since the Epoch,
           UTC.
     
     %T    is replaced by the time in the format ``%H:%M:%S''.
     
     %t    is replaced by a tab.
     
     %U    is replaced by the week number of the year (Sunday as the
           first day of the week) as a decimal number [00,53].
     
     %u    is replaced by the weekday (Monday as the first day of
           the week) as a decimal number [1,7].
     
     %V    is replaced by the week number of the year (Monday as the
           first day of the week) as a decimal number [01,53].
           According to ISO 8601 the week containing January 1 is
           week 1 if it has four or more days in the new year,
           otherwise it is week 53 of the previous year, and the next
           week is week 1.  The year is given by the `%G' conversion
           specification.
     
     %v    is replaced by the date in the format "%e-%b-%Y".
     
     %W    is replaced by the week number of the year (Monday as the
           first day of the week) as a decimal number [00,53].
     
     %w    is replaced by the weekday (Sunday as the first day of the
           week) as a decimal number [0,6].
     
     %X    is replaced by the locale's appropriate time representation.
     
     %x    is replaced by the locale's appropriate date representation.
     
     %Y    is replaced by the year with century as a decimal number.
     
     %y    is replaced by the year without century as a decimal number
           [00,99].
     
     %Z    is replaced by the time zone name.
     
     %z    is replaced by the offset from ITC in the ISO 8601 format
           "[-]hhmm".
     
     %%    is replaced by '%'.

The optional timestamp parameter is a unix timestamp. It defaults to the value of time().

  <?perl
  App::set_timezone( 'America/New_York' );
  $timestamp = App::mktime( 20, 0, 0, 12, 31, 1998 );
  print App::strftime( '%b %d %Y %H:%M:%S', $timstamp ) . "\n";
  print App::gmstrftime( '%b %d %Y %H:%M:%S', $timestamp ) . "\n";
  ?>

The number of the minute.

The number of seconds past the minute.

The number of the month. (1-12)

The number of the day.

The number of the year, may be a two or four digit value, with values between 0-69 mapping to 2000-2069 and 70-100 to 1970-2000.

  <?perl
  $datetime = '1998-12-31 00:00:00';
  if( $datetime =~ /(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})/ ) {
      $timestamp = App::mktime( $4, $5, $6, $2, $1, $3 );
  }
  ?> 

STRING FUNCTIONS

App::set_locale ( $locale [, $...] )

Set locale information independed of system locale settings.

Perl-CGI uses its own locale settings in plain ascii format, which are installed in Perl-CGI/locale in the Perl archlib dir.

Parameters

locale

One or more locale strings. Each parameter is tried to be set as new locale until success.

For example:

  <?perl
  
  $locale = App::set_locale( 'en', 'en_EN', 'en_US' );
  if( $locale ) {
      print "Set locale to $locale\n";
  }
  else {
      print "Locale could not set\n";
  }
  
  ?>

  'dp'  or 'decimal_point'         => decimal point character
  'ts'  or 'thousands_sep'         => thousands separator
  'grp' or 'grouping'              => numeric grouping, default is 3
  'cs'  or 'currency_symbol'       => local currency symbol (i.e. $)
  'ics' or 'int_curr_symbol'       => international currency symbol
                                      (i.e. USD)
  'csa' or 'curr_symb_align'       => local currency symbol alignment
                                      'l' for left or 'r' for right
  'ica' or 'int_curr_symb_align'   => international currency symbol
                                      alignment
                                      'l' for left or 'r' for right
  'fd'  or 'frac_digits'           => local fractional digits
  'ifd' or 'int_frac_digits'       => international fractional digits
  'ns'  or 'negative_sign'         => sign for negative values
  'ps'  or 'positive_sign'         => sign for positive values
  'ams' or 'am_string'             => A.M. string (i.e. AM)
  'pms' or 'pm_string'             => P.M. string (i.e. PM)
  'sdf' or 'short_date_format'     => short date format
                                      (i.e. %m/%d/%Y)
  'ldf' or 'long_date_format'      => long date format
                                      (i.e. %a %b %d %Y)
  'stf' or 'short_time_format'     => short time format
                                      (i.e. %H:%M)
  'ltf' or 'long_time_format'      => long time format
                                      (i.e. %H:%M:%S)
  'sdn' or 'short_day_names'       => array with short day names
  'ldn' or 'long_day_names'        => array with long day names
  'smn' or 'short_month_names'     => array with short month names
  'lmn' or 'long_month_names'      => array with long month names

  <?perl
  
  my %locale = (
      'dp'  => '.',
      'ts'  => ',',
      'grp' => 3,
      'cs'  => '$',
      'ics' => 'USD',
      'csa' => 'l',
      'ica' => 'l',
      'fd'  => 2,
      'ifd' => 2,
      'ns'  => '-',
      'ps'  => '+',
      'ams' => 'am',
      'pms' => 'pm',
      'sdf' => '%m/%d/%Y',
      'ldf' => '%a %b %d %Y',
      'stf' => '%H.%M',
      'ltf' => '%H.%M.%S',
      'sdn' => [ 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat' ],
      'ldn' => [
          'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday',
          'Friday', 'Saturday'
      ],
      'smn' => [
          'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug',
          'Sep', 'Oct', 'Nov', 'Dec'
      ],
      'lmn' => [
          'January', 'February', 'March', 'April', 'May', 'June',
          'July', 'August', 'September', 'October', 'November',
          'December'
      ],
  );
  
  App::set_user_locale( \%locale );
  
  print App::strftime( '%c' ), "\n";
  
  ?>

  -  A '%' character
  -  Optional flags
  -  Optional field width
  -  Optional left precision
  -  Optional right precision
  -  A required conversion specifier character that determines the
     conversion to be performed

  =f  An '=' followed by a single character f which is used as the
      numeric fill character. In order to work with precision or width
      counts, the fill character shall be a single byte character; if
      not, the behavior is undefined. The default numeric fill
      character is the . This flag does not affect field width
      filling which always uses the . This flag is ignored
      unless a left precision (see below) is specified. 
  
  ^   Do not format the currency amount with grouping characters.
      The default is to insert the grouping characters if defined for
      the current locale. 
  
  + or ( 
      Specify the style of representing positive and negative currency
      amounts. Only one of '+' or '(' may be specified. If '+' is
      specified, the locale's equivalent of '+' and '-' are used
      (for example, in the U.S., the empty string if positive and '-'
      if negative). If '(' is specified, negative amounts are enclosed
      within parentheses. If neither flag is specified, the '+' style
      is used. 
  
  !   Suppress the currency symbol from the output conversion. 
  
  -   Specify the alignment. If this flag is present the result of the
      conversion is left-justified (padded to the right) rather than
      right-justified. This flag shall be ignored unless a field
      width (see below) is specified. 

  w   A decimal digit string w specifying a minimum field width in
      bytes in which the result of the conversion is right-justified
      (or left-justified if the flag '-' is specified). The default
      value is 0. 

  #n  A '#' followed by a decimal digit string n specifying a maximum
      number of digits expected to be formatted to the left of the
      radix character. This option can be used to keep the formatted
      output from multiple calls to the strfmon() function aligned in
      the same columns. It can also be used to fill unused positions
      with a special character as in "$***123.45". This option causes
      an amount to be formatted as if it has the number of digits
      specified by n. If more than n digit positions are required,
      this conversion specification is ignored. Digit positions in
      excess of those actually required are filled with the numeric
      fill character (see the =f flag above). 
     
      If grouping has not been suppressed with the '^' flag, and it
      is defined for the current locale, grouping separators are
      inserted before the fill characters (if any) are added. Grouping
      separators are not applied to fill characters even if the fill
      character is a digit.
     
      To ensure alignment, any characters appearing before or after
      the number in the formatted output such as currency or sign
      symbols are padded as necessary with s to make their
      positive and negative formats an equal length.

  .p  A period followed by a decimal digit string p specifying the
      number of digits after the radix character. If the value of the
      right precision p is 0, no radix character appears. If a right
      precision is not included, a default specified by the current
      locale is used. The amount being formatted is rounded to the
      specified number of digits prior to formatting. 

  i   The double argument is formatted according to the locale's
      international currency format (for example,
      in the U.S.: USD 1,234.56).
  
  n   The double argument is formatted according to the locale's
      national currency format (for example, in the U.S.: $1,234.56).
  
  %   Convert to a '%' ; no argument is converted. The entire
      conversion specification shall be %%. 

Specifies the double data to be converted according to the format parameter.

  <?perl
  
  print App::strfmon( '%n', 123.45 ), "\n";
  
  ?>

  %n         [$123.45]         Default formatting 
             [-$123.45]
             [$3,456.78]
  
  %11n       [    $123.45]     Right align within an 11-character field 
             [   -$123.45]
             [  $3,456.78]
  
  %#5n       [ $   123.45]     Aligned columns for values up to 99999 
             [-$   123.45]
             [ $ 3,456.78]
  
  %=*#5n     [ $***123.45]     Specify a fill character 
             [-$***123.45]
             [ $*3,456.78]
  
  %=0#5n     [ $000123.45]     Fill characters do not use grouping 
             [-$000123.45]     even if the fill character is a digit 
             [ $03,456.78]
  
  %^#5n      [ $  123.45]      Disable the grouping separator 
             [-$  123.45]
             [ $ 3456.78]
  
  %^#5.0n    [ $  123]         Round off to whole units 
             [-$  123]
             [ $ 3457]
  
  %^#5.4n    [ $  123.4500]    Increase the precision 
             [-$  123.4500]
             [ $ 3456.7810]
  
  %(#5n      [ $   123.45 ]    Use an alternative pos/neg style 
             [($   123.45)]
             [ $ 3,456.78 ]
  
  %!(#5n     [    123.45 ]     Disable the currency symbol 
             [(   123.45)]
             [  3,456.78 ]
  
  %-14#5.4n  [ $   123.4500 ]  Left-justify the output 
             [-$   123.4500 ]
             [ $ 3,456.7810 ]
  
  %14#5.4n   [  $   123.4500]  Corresponding right-justified output 
             [ -$   123.4500]
             [  $ 3,456.7810]

Specifying the number of digits after the radix character. Defaults to 0.

Decimal point character. The default value is used from current locale.

Thousands separator (1 character). The default value is used from current locale.

Sign for negative values. The default value is used from current locale.

Sign for positive values. The default value is used from current locale.

Specifying a maximum number of digits expected to be formatted to the left of the radix character. Default is 0.

A single character which is used as the fill character. Defaults to space.

  <?perl
  
  $number = 1234.56;
  
  # english notation (default locale)
  print App::number_format( $number ), "\n";
  # output: 1,235
  
  # french notation
  print App::number_format( $number, 2, ',', ' ' ), "\n";
  # output: 1 234,56
  
  # financial notation
  print App::number_format( $number, 2, '.', ',', '-', '+', 7, '0' ), "\n";
  # output: +00001,234.56
  
  ?>

  <?
  use Benchmark;
  
  $str1 = "AAAAAAAAAAAAAAAAAAAAAAAA";
  
  Benchmark::timethese( 1000000,
      {
          's0_tr//' => \&s0,
          's1_s//g' => \&s1,
          's2_repl' => \&s2,
      }
  );
  
  sub s0 {
      my $x = $str1;
      $x =~ tr/A/B/;
      #print "$x\n";
  }
  
  sub s1 {
      my $x = $str1;
      $x =~ s/A/B/g;
      #print "$x\n";
  }
  
  sub s2 {
      my $x = App::str_replace( $str1, 'A', 'B' );
      #print "$x\n";
  }
  ?>
  
  Benchmark: timing 1000000 iterations of s0_tr//, s1_s//g, s2_repl...
     s0_tr//:  1 wallclock secs ( 1.12 usr +  0.00 sys =  1.12 CPU)
                                                @ 892857.14/s (n=1000000)
     s1_s//g: 37 wallclock secs (37.49 usr +  0.08 sys = 37.57 CPU)
                                                @ 26616.98/s (n=1000000)
     s2_repl:  7 wallclock secs ( 6.67 usr +  0.00 sys =  6.67 CPU)
                                                @ 149925.04/s (n=1000000)

FILESYSTEM FUNCTIONS

App::copy_file ( $source, $destination )

Makes a copy of the file source to destination .

Parameters

source

Path to the source file.

The destination path.

When TRUE, the file is read in text mode. Disabled by default.

The data to write as scalar value.

When TRUE, data is written in text mode. Disabled by default.

When TRUE returns a hash with names. Default is FALSE.

  Numeric   Name        Description
  ----------------------------------------------------------------
  0         dev         device number
  1         ino         inode number
  2         mode        inode protection mode
  3         nlink       number of links
  4         uid         userid of owner
  5         gid         groupid of owner
  6         rdev        device type, if inode device *
  7         size        size in bytes
  8         atime       time of last access (Unix timestamp) 
  9         mtime       time of last modification (Unix timestamp)
  10        ctime       time of last inode change (Unix timestamp)
  11        blksize     blocksize of filesystem IO *
  12        blocks      number of blocks allocated *

The modify time. If mtime is not supplied, the current system time is used.

If present, the access time of the given filename is set to the value of atime.

  <?perl
  if( App::file_touch( $FileName ) ) {
      print "$FileName time has been changed to present time\n";
  }
  else {
      print "Sorry, could not change time of $FileName\n";
  }
  ?>

  <?perl
  
  # get a lib path relative to the current script
  $lib_path = App::fullpath( 'lib' );
  # returns /path/to/your/script/lib
  
  $path = '/var/www/';
  print App::fullpath( $path . './../../etc/passwd' );
  # will output /etc/passwd
  
  ?>

HANDLING FILE UPLOADS

  <!-- The data encoding type, enctype, MUST be specified as below -->
  <form enctype="multipart/form-data" action="__URL__" method="POST">
      <!-- MAX_FILE_SIZE must precede the file input field -->
      <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
      <!-- Name of input element determines name in %App::FILES hash -->
      Send this file: <input name="userfile" type="file" />
      <input type="submit" value="Send File" />
  </form>

$App::FILES{'userfile'}{'name'}

The original name of the file on the client machine.

$App::FILES{'userfile'}{'type'}

The mime type of the file, if the browser provided this information. An example would be "image/gif". This mime type is however not checked on the Perl side and therefore don't take its value for granted.

$App::FILES{'userfile'}{'size'}

The size, in bytes, of the uploaded file.

$App::FILES{'userfile'}{'tmp_name'}

The temporary filename of the file in which the uploaded file was stored on the server.

$App::FILES{'userfile'}{'error'}

The error code associated with this file upload.

File Upload Functions

App::is_uploaded_file ( $filename )

Returns TRUE if the file named by filename was uploaded via HTTP POST. This is useful to help ensure that a malicious user hasn't tried to trick the script into working on files upon which it should not be working for instance, /etc/passwd.

This sort of check is especially important if there is any chance that anything done with uploaded files could reveal their contents to the user, or even to other users on the same system.

For proper working, the function is_uploaded_file() needs an argument like $App::FILES{'userfile'}{'tmp_name'}, - the name of the uploaded file on the clients machine $App::FILES{'userfile'}{'name'} does not work.

Example

  <?perl
  
  $file = $App::FILES{'userfile'};
  print "File ", $file->{'name'}, "\n";
  
  if( App::is_uploaded_file( $file->{'tmp_name'} ) ) {
      print "Upload ok\n";
      print "Displaying contents\n";
      print App::file_get( $file->{'tmp_name'} );
  }
  else {
      print "Upload failed\n";
      print "Error code ", $file->{'error'}, "\n";
  }
  
  ?>

App::move_uploaded_file ( $filename, $destination )

This function checks to ensure that the file designated by filename is a valid upload file (meaning that it was uploaded via Perl-CGI's HTTP POST upload mechanism). If the file is valid, it will be moved to the filename given by destination.

This sort of check is especially important if there is any chance that anything done with uploaded files could reveal their contents to the user, or even to other users on the same system.

File Upload Error Codes

UPLOAD_ERR_OK

Value: 0; There is no error, the file uploaded with success.

UPLOAD_ERR_CFG_SIZE

Value: 1; The uploaded file exceeds the upload_max_filesize directive in the config.

UPLOAD_ERR_FORM_SIZE

Value: 2; The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.

UPLOAD_ERR_NO_FILE

Value: 4; No file was uploaded.

UPLOAD_ERR_CANT_WRITE

Value: 7; Failed to write file to disk.

SESSION HANDLING

Passing the Session ID

• Cookies
• URL parameter

  <?perl
  
  App::session_start();
  
  $App::SESSION{'count'} ||= 0;
  $App::SESSION{'count'} ++;
  
  ?>
  
  <p>
  Hello visitor, you have called this page for
  <? print $App::SESSION{'count'} ?>
  times.
  </p>
  
  <p>
  To continue, <a href="nextpage.plc?<?= App::SID ?>">click here</a>.
  </p> 

Session Handling Functions

App::session_start ()

session_start() creates a session or resumes the current one based on the current session id that's being passed via a request, such as GET, POST, or a cookie.

App::session_destroy ()

session_destroy() destroys all of the data associated with the current session. It does not unset any of the global variables associated with the session, or unset the session cookie.

Returns TRUE on success or FALSE on failure.

App::session_regenerate_id ( [$delete_old_session] )

session_regenerate_id() will replace the current session id with a new one, and keep the current session information.

Parameters

delete_old_session

Whether to delete the old associated session file or not. Defaults to FALSE.

  <?perl
  
  App::session_set_handler(
      'open', 'close', 'read', 'write', 'destroy', 'gc',
      MySessionHandler->new()
  );
  App::session_start();
  
  package MySessionHandler;
  
  sub new {
      my $class = shift;
      my $this = {};
      bless $this, $class;
      return $this;
  }
  
  sub open {
      my( $this, $save_path, $session_name ) = @_;
      $this->{'save_path'} = $save_path;
      return 1;
  }
  
  sub close {
      my( $this ) = @_;
      return 1;
  }
  
  sub read {
      my( $this, $id ) = @_;
      my $sess_file = $this->{'save_path'} . '/' . $id . '.pcs';
      return App::file_get( $sess_file );
  }
  
  sub write {
      my( $this, $id, $sess_data ) = @_;
      my $sess_file = $this->{'save_path'} . '/' . $id . '.pcs';
      return App::file_put( $sess_file, $sess_data );
  }
  
  sub destroy {
      my( $this, $id ) = @_;
      my( $sess_file );
      $sess_file = $this->{'save_path'} . '/' . $id . '.pcs';
      unlink $sess_file;
      return 1;
  }
  
  sub gc {
      my( $this, $maxlifetime ) = @_;
      my( $dh, @files, $file, $now );
      $now = time;
      opendir $dh, $this->{'save_path'}
          or return 0;
      @files = grep { /\.pcs$/ } readdir $dh;
      closedir $dh;
      foreach( @files ) {
          $file = $this->{'save_path'} . '/' . $_;
          if( (stat( $file ))[9] + $maxlifetime < $now ) {
              unlink $file;
          }
      }
      return 1;
  }
  
  1;
  
  ?>

DESCRIPTION OF CONFIG DIRECTIVES

shared_mode = {none|host|perl}

Run scripts in shared mode over FastCGI or ModPerl. Available modes are:

none - remove all scripts after request (default)

host - share all scripts within the same host name (recommended)

perl - share all scripts within the same perl interpreter

Resource Limits

enable_limits = {boolean}

Enable resource limits. Limits are enabled by default, except when running ModPerl.

memory_limit = {integer}

Sets the maximum size of the process's virtual memory in bytes. Default is 64M.

cpu_limit = {integer}

Sets CPU time limit in seconds. Default is 360.

file_limit = {integer}

Sets the maximum size of files that the process may create. Default is infinity.

File Uploads

file_uploads = {boolean}

Enable or disable HTTP file uploads.

upload_tmp_dir = {string}

The temporary directory used for storing files when doing file upload. Must be writable by whatever user Perl-CGI is running as. If not specified Perl-CGI will use the temporary path specified in tmp_dir.

upload_max_filesize = {integer}

The maximum size of an uploaded file. You may also use shorthand notation like 10M for 10 megabytes.

Sessions

session.save_path = {string}

session.save_path defines the argument which is passed to the save handler. If you choose the default session handler, this is the path where the files are created.

session.name = {string}

session.name specifies the name of the session which is used as cookie name. It should only contain alphanumeric characters. Defaults to PERLCGISESSID.

session.gc_probability = {integer}

session.gc_probability in conjunction with session.gc_divisor is used to manage probability that the gc (garbage collection) routine is started. Defaults to 1.

session.gc_divisor = {integer}

session.gc_divisor coupled with session.gc_probability defines the probability that the gc (garbage collection) process is started on every session initialization. The probability is calculated by using gc_probability/gc_divisor, e.g. 1/100 means there is a 1% chance that the GC process starts on each request. session.gc_divisor defaults to 100.

session.gc_maxlifetime = {integer}

session.gc_maxlifetime specifies the number of seconds after which data will be seen as 'garbage' and cleaned up. Garbage collection occurs during session start.

Note: If different scripts have different values of session.gc_maxlifetime but share the same place for storing the session data then the script with the minimum value will be cleaning the data. In this case, use this directive together with session.save_path.

session.use_cookies = {boolean}

session.use_cookies specifies whether the module will use cookies to store the session id on the client side. Defaults to True.

session.use_only_cookies = {boolean}

session.use_only_cookies specifies whether the module will only use cookies to store the session id on the client side. Enabling this setting prevents attacks involved passing session ids in URLs. Defaults to Yes.

session.cookie_lifetime = {integer}

session.cookie_lifetime specifies the lifetime of the cookie in seconds which is sent to the browser. The value 0 means "until the browser is closed." Defaults to 0.

session.cookie_path = {string}

session.cookie_path specifies path to set in session_cookie. Defaults value is empty.

session.cookie_domain = {string}

session.cookie_domain specifies the domain to set in session_cookie. Default is none at all meaning the host name of the server which generated the cookie according to cookies specification.

session.cookie_secure = {boolean}

session.cookie_secure specifies whether cookies should only be sent over secure connections. Defaults to off.

session.cookie_httponly = {boolean}

Marks the cookie as accessible only through the HTTP protocol. This means that the cookie won't be accessible by scripting languages, such as JavaScript. This setting can effectively help to reduce identity theft through XSS attacks (although it is not supported by all browsers).

session.cache_limiter = {string}

session.cache_limiter specifies cache control method to use for session pages (none/nocache/private/private_no_expire/public). Defaults to nocache. See also session_cache_limiter().

session.cache_expire = {integer}

session.cache_expire specifies time-to-live for cached session pages in minutes, this has no effect for nocache limiter. Defaults to 180. See also session_cache_expire().

RESTRICTIONS

  <? $var = q/thali's meat/; ?>
  # Perl-CGI parses the ' as the begin of a string and ignores the closing
  # tag ?> which will cause a syntax error
  
  # since Perl-CGI breaks strings at the end of line the following works
  <?
  $var = q/thali's meat/;
  ?>

AUTHORS

COPYRIGHT

SEE ALSO