distrib/lib/CGI.pm

1 package CGI;
19 #   http://stein.cshl.org/WWW/software/CGI/
21 $CGI::revision = '$Id: CGI.pm,v 1.241 2007/12/27 18:37:43 lstein Exp $';
22 $CGI::VERSION='3.33';
27 use CGI::Util qw(rearrange make_attributes unescape escape expires ebcdic2ascii ascii2ebcdic);
59     #    1) use CGI qw(-nosticky)
60     #    2) $CGI::nosticky(1)
65     #    1) use CGI qw(-nph)
66     #    2) CGI::nph(1)
77     #    1) use CGI qw(:private_tempfiles)
78     #    2) CGI::private_tempfiles(1);
87     #    1) use CGI qw(:close_upload_files)
88     #    2) $CGI::close_upload_files(1);
111     # use CGI qw(-no_undef_params);
168 # This is the default class for the CGI object to use when all else fails.
169 $DefaultClass = 'CGI' unless defined $CGI::DefaultClass;
172 $AutoloadClass = $DefaultClass unless defined $CGI::AutoloadClass;
188   # mod_perl handlers may run system() on scripts using CGI.pm;
204 $PERLEX++ if defined($ENV{'GATEWAY_INTERFACE'}) && $ENV{'GATEWAY_INTERFACE'} =~ /^CGI-PerlEx/;
222     $CGI::DefaultClass->binmode(\*main::STDOUT);
223     $CGI::DefaultClass->binmode(\*main::STDIN);
224     $CGI::DefaultClass->binmode(\*main::STDERR);
357       $r->register_cleanup(\&CGI::_reset_globals);
365       $r->pool->cleanup_register(\&CGI::_reset_globals);
401     $CGI::Q = $self = $CGI::DefaultClass->new(@_);
462     return @_ if defined($_[0]) && (!ref($_[0])) &&($_[0] eq 'CGI');
464 	    (ref($_[0]) eq 'CGI' || UNIVERSAL::isa($_[0],'CGI')) # slightly optimized for common case
466 	$Q = $CGI::DefaultClass->new unless defined($Q);
475 	(substr(ref($_[0]),0,3) eq 'CGI'
476 	 || UNIVERSAL::isa($_[0],'CGI'))) {
601 	  if (UNIVERSAL::isa($initializer,'CGI')) {
830     print STDERR "CGI::AUTOLOAD for $AUTOLOAD\n" if $CGI::AUTOLOAD_DEBUG;
843 	$pack = ${"$pack\:\:AutoloadClass"} || $CGI::DefaultClass
864 	       $code = $CGI::DefaultClass->_make_tag_func($func_name);
925 		$routine =~ s/^.*::/CGI::/;
1072     tie(%in,CGI,$q);
1089     tie(%in,CGI);
1139     if (ref($arg) && UNIVERSAL::isa($arg,'CGI')) {
1158     return $_[0] if $_[1] eq 'CGI';
1365 # A way to restore CGI parameters from an initializer.
1370     $Q = $CGI::DefaultClass->new(@_);
1510             my $cs = UNIVERSAL::isa($_,'CGI::Cookie') ? $_->as_string : $_;
2173     return $XHTML ? CGI::label($labelattributes,
2185          push @_,$_[0] if @_==1 && $_[0] eq 'CGI';
2186          my ($self,$toencode,$newlinestoo) = CGI::self_or_default(@_);
2220     push @_,$_[0] if @_==1 && $_[0] eq 'CGI';
2221     my ($self,$string) = CGI::self_or_default(@_);
2403               CGI::label($labelattributes,
2758     require CGI::Cookie;
2764 	$self->{'.cookies'} = CGI::Cookie->fetch
2786     return new CGI::Cookie(@param);
2999     require CGI::Cookie;
3002 	$self->{'.raw_cookies'} = CGI::Cookie->raw_fetch
3234     $CGI::NOSTICKY = $param if defined($param);
3235     return $CGI::NOSTICKY;
3245     $CGI::NPH = $param if defined($param);
3246     return $CGI::NPH;
3256     $CGI::PRIVATE_TEMPFILES = $param if defined($param);
3257     return $CGI::PRIVATE_TEMPFILES;
3266     $CGI::CLOSE_UPLOAD_FILES = $param if defined($param);
3267     return $CGI::CLOSE_UPLOAD_FILES;
3279         $CGI::DEFAULT_DTD = [ $param, $param2 ];
3281         $CGI::DEFAULT_DTD = $param;
3283     return $CGI::DEFAULT_DTD;
3317     return $self->CGI::hidden('-name'=>'.cgifields',
3426           die "CGI open of tmpfile: $!\n" unless defined $filehandle;
3427 	  $CGI::DefaultClass->binmode($filehandle) if $CGI::needs_binmode
3460 	  $CGI::DefaultClass->binmode($filehandle) if $CGI::needs_binmode;
3538           die "CGI open of tmpfile: $!\n" unless defined $filehandle;
3539 	  $CGI::DefaultClass->binmode($filehandle) if $CGI::needs_binmode
3562 	  $CGI::DefaultClass->binmode($filehandle) if $CGI::needs_binmode;
3640 	$AUTOLOAD = "CGI::$_";
3663 *Fh::AUTOLOAD = \&CGI::AUTOLOAD;
3679     return $i.$CGI::TAINTED;
3729 $CRLF=$CGI::CRLF;
3732 *MultipartBuffer::AUTOLOAD = \&CGI::AUTOLOAD;
3748     $CGI::DefaultClass->binmode($IN); # if $CGI::needs_binmode;  # just do it always
3766 	$boundary = "--$boundary" unless CGI::user_agent('MSIE\s+3\.0[12];\s*Mac|DreamPassport');
3807     local($CRLF) = "\015\012" if $CGI::OS eq 'VMS' || $CGI::EBCDIC;
3825     if ($CGI::EBCDIC) {
3827       $header = CGI::Util::ascii2ebcdic($header);
3860     if ($CGI::EBCDIC) {
3862       $returnval = CGI::Util::ascii2ebcdic($returnval);
3883     my $boundary_start = $CGI::EBCDIC ? CGI::Util::ebcdic2ascii($self->{BOUNDARY})      : $self->{BOUNDARY};
3884     my $boundary_end   = $CGI::EBCDIC ? CGI::Util::ebcdic2ascii($self->{BOUNDARY}.'--') : $self->{BOUNDARY}.'--';
3958 	die  "CGI.pm: Server closed socket during multipart read (client aborted?).\n"
3988   $SL = $CGI::SL;
3989   $MAC = $CGI::OS eq 'MACINTOSH';
4001     #    unshift(@TEMP,(getpwuid($<))[7].'/tmp') if $CGI::OS eq 'UNIX';
4006     # unshift(@TEMP,(eval {(getpwuid($>))[7]}).'/tmp') if $CGI::OS eq 'UNIX' and $> != 0;
4021 *CGITempFile::AUTOLOAD = \&CGI::AUTOLOAD;
4063 package CGI;
4069     $CGI::CGI = '';
4070     $CGI::CGI=<<EOF;
4071     $CGI::VERSION;
4086 CGI - Simple Common Gateway Interface Class
4090   # CGI script that creates a fill-out form
4093   use CGI qw/:standard/;
4123 fill-out forms and parse their contents.  This package defines CGI
4125 and other state variables.  Using a CGI object's methods, you can
4131 CGI scripting, including support for file uploads, cookies, cascading
4134 CGI.pm also provides a simple function-oriented programming style for
4137 The current version of CGI.pm is available at
4146 There are two styles of programming with CGI.pm, an object-oriented
4148 create one or more CGI objects and then use object methods to create
4149 the various elements of the page.  Each CGI object starts out with the
4150 list of named parameters that were passed to your CGI script by the
4153 the CGI script, and because each object's parameter list is
4161    use CGI;                             # load CGI routines
4162    $q = new CGI;                        # create new CGI object
4168 In the function-oriented style, there is one default CGI object that
4170 retrieve CGI parameters, create HTML tags, manage cookies, and so
4172 limits you to using one CGI object at a time.  The following example
4176 need to create the CGI object.
4179    use CGI qw/:standard/;           # load standard CGI routines
4187 function-oriented programming in CGI.pm
4189 =head2 CALLING CGI.PM ROUTINES
4191 Most CGI.pm routines accept several arguments, sometimes as many as 20
4200 dash.  If a dash is present in the first argument, CGI.pm assumes
4215 For example, the param() routine is used to set a CGI parameter to a
4221 A large number of routines in CGI.pm actually aren't specifically
4227 attributes and contents, CGI.pm uses the convention of passing HTML
4241 Many newcomers to CGI.pm are puzzled by the difference between the
4252 If you use the B<-w> switch, you will be warned that some CGI.pm argument
4301      $query = new CGI;
4311      $query = new CGI(INPUTFILE);
4324     $query = new CGI(\*STDIN);
4326 You can also initialize the CGI object with a FileHandle or IO::File
4330 initialize CGI state from a file handle, the way to do this is with
4332 default CGI object from the indicated file handle.
4341     $query = new CGI( {'dinosaur'=>'barney',
4348     $query = new CGI('dinosaur=barney&color=purple');
4350 or from a previously existing CGI object (currently this clones the
4354     $old_query = new CGI;
4355     $new_query = new CGI($old_query);
4359    $empty_query = new CGI("");
4363    $empty_query = new CGI({});
4452 the param() method instead to access CGI variables by name.
4473 This clears the CGI object completely.  It might be useful to ensure
4493 only affects people trying to use CGI for XML processing and other
4517     use CGI ':cgi-lib';
4521 the keys are the names of the CGI parameters, and the values are the
4525 CGI parameter list.  Called in a list context, it returns the
4529 When using this, the thing you must watch out for are multivalued CGI
4538 function calls (also see the section on CGI-LIB compatibility).
4557 Both name and value are URL escaped.  Multi-valued CGI parameters are
4565    use CGI;
4570        my $q = new CGI;
4579        my $q = new CGI(\*IN);
4594 =head2 RETRIEVING CGI ERRORS
4597 processing uploaded files.  When these errors occur, CGI will stop
4619 To use the function-oriented interface, you must specify which CGI.pm
4624    use CGI <list of methods>;
4627 call them directly without creating a CGI object first.  This example
4631    use CGI 'param','header';
4645 Import all CGI-handling methods, such as B<param()>, B<path_info()>
4681 Import all the available methods.  For the full list, see the CGI.pm
4686 If you import a function name that is not part of CGI.pm, the module
4692 machine reboots).  You don't need to wait for a new version of CGI.pm
4695    use CGI qw/:standard :html3 gradient/;
4698 Note that in the interests of execution speed CGI.pm does B<not> use
4702 If you import any of the state-maintaining CGI or form-generating
4703 methods, a default CGI object will be created and initialized
4706 B<submit()> and the like.  (If you need direct access to the CGI
4707 object, you can find it in the global variable B<$CGI::Q>).  By
4708 importing CGI.pm methods, you can create visually elegant scripts:
4710    use CGI qw/:standard/;
4740 change the way that CGI.pm functions in various ways.  Pragmas,
4746    use CGI qw/:standard -debug/;
4754 When you I<use CGI -any>, then any method that the query object
4759    use CGI qw(-any);
4760    $q=new CGI;
4775    use CGI qw(-compile :standard :html3);
4779    use CGI qw(-compile :all);
4786    use CGI();
4787    CGI->compile();
4790 might want to precompile all CGI routines in a startup script, and
4795 By default the CGI module implements a state-preserving behavior
4814 This keeps CGI.pm from including undef params in the parameter list.
4818 By default, CGI.pm versions 2.69 and higher emit XHTML
4829 This makes CGI.pm treat all parameters as UTF-8 strings. Use this with
4839 This makes CGI.pm produce a header appropriate for an NPH (no
4846 Separate the name=value pairs in CGI parameter query strings with
4859 Separate the name=value pairs in CGI parameter query strings with
4865 that is not recognized is referred to CGI.pm for possible evaluation.
4866 This allows you to use all the CGI.pm functions without adding them to
4877 run a CGI.pm script from the command line to produce HTML, and you
4878 don't want it to read CGI parameters from the command line or STDIN,
4881    use CGI qw(-no_debug :standard);
4885 This turns on full debugging.  In addition to reading CGI arguments
4886 from the command-line processing, CGI.pm will pause and try to read
4894 CGI.pm can process uploaded file. Ordinarily it spools the uploaded
4897 upload section.  Another CGI script author could peek at this data
4906 To ensure that the temporary file cannot be read by other CGI scripts,
4907 use suEXEC or a CGI wrapper program to run your script.  The temporary
4946 I<use CGI>.  However, you can specify the tags you want to generate
4953   use CGI qw/:standard *table start_ul/;
4972 Most of CGI.pm's functions deal with creating documents on the fly.
4974 document itself.  CGI.pm provides functions for generating HTTP
4984 Normally the first thing you will do in any CGI script is print out an
5019 to the CGI methods using named parameters.  Recognized parameters are
5027 Most browsers will not cache the output from CGI scripts.  Every time
5124 After creating the HTTP header, most CGI scripts will start writing
5220 completely.  CGI.pm attempts to format the script in such a way that
5230       $query = new CGI;
5257 JavaScript code in a file or CGI script rather than cluttering up each
5424 It is possible for a script to receive CGI parameters in the URL as
5435 interfere with similarly-named CGI parameters in POSTed forms.  If you
5441 CGI.pm defines general HTML shortcut methods for most, if not all of
5472    use CGI ':standard';
5514 Prior to CGI.pm version 2.41, providing an empty ('') string as an
5569 CGI.pm puts the extra space there using array interpolation, which is
5630 be replaced by their numeric entities, since CGI.pm has no lookup
5656 pretty-printed output, please use L<CGI::Pretty>, a subclass
5691 autoEscape() method with a false value immediately after creating the CGI object:
5693    $query = new CGI;
5758 Netscape 2.0.  It is compatible with many CGI scripts and is
5760 convenience, CGI.pm stores the name of this encoding
5761 type in B<&CGI::URL_ENCODED>.
5769 your convenience, CGI.pm stores the name of this encoding type
5770 in B<&CGI::MULTIPART>
5773 by CGI scripts unless they use CGI.pm or another library designed
5941 by calling B<start_form()> with an encoding type of B<&CGI::MULTIPART>,
5986 that CGI.pm creates during upload spooling (see below).
6051 finished.  In this case, CGI.pm will return undef for the name of the
6072  $q = CGI->new(\&hook [,$data [,$use_tempfile]]);
6084 CGI.pm's use of a temporary disk-based file during file upload. If you
6089 If using the function-oriented interface, call the CGI::upload_hook()
6090 method before calling param() or any other CGI functions:
6092   CGI::upload_hook(\&hook [,$data [,$use_tempfile]]);
6095 explicitly if you wish to use it without the CGI:: prefix.
6097 If you are using CGI.pm on a Windows platform and find that binary
6748 maintain state within a browser session.  CGI.pm has several methods
6751 A cookie is a name=value pair much like the named parameters in a CGI
6752 query string.  CGI scripts create one or more cookies and send
6755 to the CGI script during subsequent interactions.
6791 causes the cookie to be sent to any CGI script on your site.
6796 script if the CGI request is occurring on a secure channel, such as SSL.
6818 alphanumeric characters, CGI.pm removes this restriction by escaping
6857         use CGI ':standard';
6872 	use CGI;
6873 	$query = new CGI;
6881 The cookie and CGI namespaces are separate.  If you have a parameter
6884 simple to turn a CGI parameter into a cookie, and vice-versa:
6886    # turn a CGI parameter into a cookie
6901 It's possible for CGI.pm scripts to write into several browser panels
6915 in CGI.pm, but the HTML is very simple to write.  See the frame
6936 CGI.pm it looks like this:
6958 Netscape itself. From the point of view of CGI scripting, JavaScript
7080 CGI method. For example, to have your validateAge() JavaScript code
7087 function by incorporating it into a <SCRIPT> block. The CGI.pm
7101 CGI.pm has limited support for HTML3's cascading style sheets (css).
7138     use CGI qw/:standard :html3/;
7156     print start_html( -title=>'CGI with Style',
7160     print h1('CGI with Style'),
7279 As a shortcut, you can interpolate the entire CGI object into a string
7282     $query=new CGI;
7317 method from the CGI::Cookie module.
7339 path information in CGI scripts destined for use with IIS.
7445 Servers use a variety of conventions for designating CGI scripts as
7452 CGI.pm supports NPH scripts with a special NPH mode.  When in this
7453 mode, CGI.pm will output the necessary extra header information when
7458 version 2.30, CGI.pm will automatically detect when the script is
7466 Non-Parsed Headers Stripped From CGI Applications That Have nph-
7476       use CGI qw(:standard -nph)
7480 Call B<nph()> with a non-zero parameter at any point after using CGI.pm in your program.
7482       CGI->nph(1)
7494 CGI.pm provides four simple functions for producing multipart
7504   use CGI qw/:push -nph/;
7534 If not provided, CGI.pm chooses a reasonable boundary for you.
7561 at the CGI::Push module.
7568 A potential problem with CGI.pm is that, by default, it attempts to
7570 could attack your site by sending a CGI script a huge POST of many
7571 megabytes.  CGI.pm will attempt to read the entire POST into a
7576 Another possible attack is for the remote user to force CGI.pm to
7577 accept a huge file upload.  CGI.pm will accept the upload and store it
7579 an uploaded file.  CGI.pm will delete the file automatically when it
7584 of memory, CPU time and disk space that CGI scripts can use.  Some Web
7587 commands to put ceilings on CGI resource usage.
7590 CGI.pm also has some simple built-in protections against denial of
7592 These take the form of two global variables in the CGI name space:
7596 =item B<$CGI::POST_MAX>
7599 on the size of POSTings, in bytes.  If CGI.pm detects a POST
7606 =item B<$CGI::DISABLE_UPLOADS>
7621     use CGI qw/:standard/;
7622     use CGI::Carp 'fatalsToBrowser';
7623     $CGI::POST_MAX=1024 * 100;  # max 100K posts
7624     $CGI::DISABLE_UPLOADS = 1;  # no uploads
7628 Open up CGI.pm, find the definitions for $POST_MAX and
7636 I<param()> to return an empty CGI parameter list.  You can test for
7637 this event by checking I<cgi_error()>, either after you create the CGI
7643 designed to be returned to the browser as the CGI script's status
7656 =head1 COMPATIBILITY WITH CGI-LIB.PL
7667     use CGI;
7668     CGI::ReadParse();
7671 CGI.pm's ReadParse() routine creates a tied variable named %in,
7680     $q = $in{CGI};
7685 of CGI.pm without rewriting your old scripts from scratch.
7695 bug reports, please provide the version of CGI.pm, the version of
7758 	use CGI ':standard';
7761 	print start_html("Example CGI.pm Form");
7762 	print "<h1> Example CGI.pm Form</h1>\n";
7840 L<CGI::Carp>, L<CGI::Fast>, L<CGI::Pretty>