1CGI(3) User Contributed Perl Documentation CGI(3)
2
6 CGI - Handle Common Gateway Interface requests and responses
7
9 use strict;
10 use warnings;
11 use CGI;
13 # create a CGI object (query) for use
15 my $q = CGI->new;
16 # Process an HTTP request
18 my @values = $q->multi_param('form_field');
19 my $value = $q->param('param_name');
20 my $fh = $q->upload('file_field');
22 my $riddle = $q->cookie('riddle_name');
24 my %answers = $q->cookie('answers');
25 # Prepare various HTTP responses
27 print $q->header();
28 print $q->header('application/json');
29 my $cookie1 = $q->cookie(
31 -name => 'riddle_name',
32 -value => "The Sphynx's Question"
33 );
34 my $cookie2 = $q->cookie(
36 -name => 'answers',
37 -value => \%answers
38 );
39 print $q->header(
41 -type => 'image/gif',
42 -expires => '+3d',
43 -cookie => [ $cookie1,$cookie2 ]
44 );
45 print $q->redirect('http://somewhere.else/in/movie/land');
47
49 CGI.pm is a stable, complete and mature solution for processing and
50 preparing HTTP requests and responses. Major features including
51 processing form submissions, file uploads, reading and writing cookies,
52 query string generation and manipulation, and processing and preparing
53 HTTP headers.
54 CGI.pm performs very well in a vanilla CGI.pm environment and also
56 comes with built-in support for mod_perl and mod_perl2 as well as
57 FastCGI.
58 It has the benefit of having developed and refined over 20 years with
60 input from dozens of contributors and being deployed on thousands of
61 websites. CGI.pm was included in the perl distribution from perl v5.4
62 to v5.20, however is has now been removed from the perl core...
63
65 <http://perl5.git.perl.org/perl.git/commitdiff/e9fa5a80>
66 If you upgrade to a new version of perl or if you rely on a system or
68 vendor perl and get an updated version of perl through a system update,
69 then you will have to install CGI.pm yourself with cpan/cpanm/a vendor
70 package/manually. To make this a little easier the CGI::Fast module has
71 been split into its own distribution, meaning you do not need access to
72 a compiler to install CGI.pm
73 The rationale for this decision is that CGI.pm is no longer considered
75 good practice for developing web applications, including quick
76 prototyping and small web scripts. There are far better, cleaner,
77 quicker, easier, safer, more scalable, more extensible, more modern
78 alternatives available at this point in time. These will be documented
79 with CGI::Alternatives.
80 For more discussion on the removal of CGI.pm from core please see:
82 <http://www.nntp.perl.org/group/perl.perl5.porters/2013/05/msg202130.html>
84 Note that the v4 releases of CGI.pm will retain back compatibility as
86 much as possible, however you may need to make some minor changes to
87 your code if you are using deprecated methods or some of the more
88 obscure features of the module. If you plan to upgrade to v4.00 and
89 beyond you should read the Changes file for more information and test
90 your code against CGI.pm before deploying it.
91
93 All HTML generation functions within CGI.pm are no longer being
94 maintained. Any issues, bugs, or patches will be rejected unless they
95 relate to fundamentally broken page rendering.
96 The rationale for this is that the HTML generation functions of CGI.pm
98 are an obfuscation at best and a maintenance nightmare at worst. You
99 should be using a template engine for better separation of concerns.
100 See CGI::Alternatives for an example of using CGI.pm with the
101 Template::Toolkit module.
102 These functions, and perldoc for them, are considered deprecated, they
104 are no longer being maintained and no fixes or features for them will
105 be accepted. They will, however, continue to exist in CGI.pm without
106 any deprecation warnings ("soft" deprecation) so you can continue to
107 use them if you really want to. All documentation for these functions
108 has been moved to CGI::HTML::Functions.
109
111 There are two styles of programming with CGI.pm, an object-oriented
112 (OO) style and a function-oriented style. You are recommended to use
113 the OO style as CGI.pm will create an internal default object when the
114 functions are called procedurally and you will not have to worry about
115 method names clashing with perl builtins.
116 In the object-oriented style you create one or more CGI objects and
118 then use object methods to create the various elements of the page.
119 Each CGI object starts out with the list of named parameters that were
120 passed to your CGI script by the server. You can modify the objects,
121 save them to a file or database and recreate them. Because each object
122 corresponds to the "state" of the CGI script, and because each object's
123 parameter list is independent of the others, this allows you to save
124 the state of the script and restore it later.
125 For example, using the object oriented style:
127 #!/usr/bin/env perl
129 use strict;
131 use warnings;
132 use CGI; # load CGI routines
134 my $q = CGI->new; # create new CGI object
136 print $q->header; # create the HTTP header
137 In the function-oriented style, there is one default CGI object that
139 you rarely deal with directly. Instead you just call functions to
140 retrieve CGI parameters, manage cookies, and so on. The following
141 example is identical to above, in terms of output, but uses the
142 function-oriented interface. The main differences are that we now need
143 to import a set of functions into our name space (usually the
144 "standard" functions), and we don't need to create the CGI object.
145 #!/usr/bin/env perl
147 use strict;
149 use warnings;
150 use CGI qw/:standard/; # load standard CGI routines
152 print header(); # create the HTTP header
153 The examples in this document mainly use the object-oriented style. See
155 HOW TO IMPORT FUNCTIONS for important information on function-oriented
156 programming in CGI.pm
157 Calling CGI.pm routines
159 Most CGI.pm routines accept several arguments, sometimes as many as 20
160 optional ones! To simplify this interface, all routines use a named
161 argument calling style that looks like this:
162 print $q->header(
164 -type => 'image/gif',
165 -expires => '+3d',
166 );
167 Each argument name is preceded by a dash. Neither case nor order
169 matters in the argument list: -type, -Type, and -TYPE are all
170 acceptable. In fact, only the first argument needs to begin with a
171 dash. If a dash is present in the first argument CGI.pm assumes dashes
172 for the subsequent ones.
173 Several routines are commonly called with just one argument. In the
175 case of these routines you can provide the single argument without an
176 argument name. header() happens to be one of these routines. In this
177 case, the single argument is the document type.
178 print $q->header('text/html');
180 Other such routines are documented below.
182 Sometimes named arguments expect a scalar, sometimes a reference to an
184 array, and sometimes a reference to a hash. Often, you can pass any
185 type of argument and the routine will do whatever is most appropriate.
186 For example, the param() routine is used to set a CGI parameter to a
187 single or a multi-valued value. The two cases are shown below:
188 $q->param(
190 -name => 'veggie',
191 -value => 'tomato',
192 );
193 $q->param(
195 -name => 'veggie',
196 -value => [ qw/tomato tomahto potato potahto/ ],
197 );
198 Many routines will do something useful with a named argument that it
200 doesn't recognize. For example, you can produce non-standard HTTP
201 header fields by providing them as named arguments:
202 print $q->header(
204 -type => 'text/html',
205 -cost => 'Three smackers',
206 -annoyance_level => 'high',
207 -complaints_to => 'bit bucket',
208 );
209 This will produce the following nonstandard HTTP header:
211 HTTP/1.0 200 OK
213 Cost: Three smackers
214 Annoyance-level: high
215 Complaints-to: bit bucket
216 Content-type: text/html
217 Notice the way that underscores are translated automatically into
219 hyphens.
220 Creating a new query object (object-oriented style)
222 my $q = CGI->new;
223 This will parse the input (from POST, GET and DELETE methods) and store
225 it into a perl5 object called $q. Note that because the input parsing
226 happens at object instantiation you have to set any CGI package
227 variables that control parsing before you call CGI->new.
228 Any filehandles from file uploads will have their position reset to the
230 beginning of the file.
231 Creating a new query object from an input file
233 my $q = CGI->new( $input_filehandle );
234 If you provide a file handle to the new() method, it will read
236 parameters from the file (or STDIN, or whatever). The file can be in
237 any of the forms describing below under debugging (i.e. a series of
238 newline delimited TAG=VALUE pairs will work). Conveniently, this type
239 of file is created by the save() method (see below). Multiple records
240 can be saved and restored.
241 Perl purists will be pleased to know that this syntax accepts
243 references to file handles, or even references to filehandle globs,
244 which is the "official" way to pass a filehandle. You can also
245 initialize the CGI object with a FileHandle or IO::File object.
246 If you are using the function-oriented interface and want to initialize
248 CGI state from a file handle, the way to do this is with
249 restore_parameters(). This will (re)initialize the default CGI object
250 from the indicated file handle.
251 open( my $in_fh,'<',"test.in") || die "Couldn't open test.in for read: $!";
253 restore_parameters( $in_fh );
254 close( $in_fh );
255 You can also initialize the query object from a hash reference:
257 my $q = CGI->new( {
259 'dinosaur' => 'barney',
260 'song' => 'I love you',
261 'friends' => [ qw/ Jessica George Nancy / ]
262 } );
263 or from a properly formatted, URL-escaped query string:
265 my $q = CGI->new('dinosaur=barney&color=purple');
267 or from a previously existing CGI object (currently this clones the
269 parameter list, but none of the other object-specific fields, such as
270 autoescaping):
271 my $old_query = CGI->new;
273 my $new_query = CGI->new($old_query);
274 To create an empty query, initialize it from an empty string or hash:
276 my $empty_query = CGI->new("");
278 -or-
280 my $empty_query = CGI->new({});
282 Fetching a list of keywords from the query
284 my @keywords = $q->keywords
285 If the script was invoked as the result of an ISINDEX search, the
287 parsed keywords can be obtained as an array using the keywords()
288 method.
289 Fetching the names of all the parameters passed to your script
291 my @names = $q->multi_param
292 my @names = $q->param
294 If the script was invoked with a parameter list (e.g.
296 "name1=value1&name2=value2&name3=value3"), the param() / multi_param()
297 methods will return the parameter names as a list. If the script was
298 invoked as an ISINDEX script and contains a string without ampersands
299 (e.g. "value1+value2+value3"), there will be a single parameter named
300 "keywords" containing the "+"-delimited keywords.
301 The array of parameter names returned will be in the same order as they
303 were submitted by the browser. Usually this order is the same as the
304 order in which the parameters are defined in the form (however, this
305 isn't part of the spec, and so isn't guaranteed).
306 Fetching the value or values of a single named parameter
308 my @values = $q->multi_param('foo');
309 -or-
311 my $value = $q->param('foo');
313 -or-
315 my @values = $q->param('foo'); # list context, discouraged and will raise
317 # a warning (use ->multi_param instead)
318 Pass the param() / multi_param() method a single argument to fetch the
320 value of the named parameter. When calling param() If the parameter is
321 multivalued (e.g. from multiple selections in a scrolling list), you
322 can ask to receive an array. Otherwise the method will return the first
323 value.
324 Warning - calling param() in list context can lead to vulnerabilities
326 if you do not sanitise user input as it is possible to inject other
327 param keys and values into your code. This is why the multi_param()
328 method exists, to make it clear that a list is being returned, note
329 that param() can still be called in list context and will return a list
330 for back compatibility.
331 The following code is an example of a vulnerability as the call to
333 param will be evaluated in list context and thus possibly inject extra
334 keys and values into the hash:
335 my %user_info = (
337 id => 1,
338 name => $q->param('name'),
339 );
340 The fix for the above is to force scalar context on the call to ->param
342 by prefixing it with "scalar"
343 name => scalar $q->param('name'),
345 If you call param() in list context with an argument a warning will be
347 raised by CGI.pm, you can disable this warning by setting
348 $CGI::LIST_CONTEXT_WARN to 0 or by using the multi_param() method
349 instead
350 If a value is not given in the query string, as in the queries
352 "name1=&name2=", it will be returned as an empty string.
353 If the parameter does not exist at all, then param() will return undef
355 in scalar context, and the empty list in a list context.
356 Setting the value(s) of a named parameter
358 $q->param('foo','an','array','of','values');
359 This sets the value for the named parameter 'foo' to an array of
361 values. This is one way to change the value of a field AFTER the script
362 has been invoked once before.
363 param() also recognizes a named parameter style of calling described in
365 more detail later:
366 $q->param(
368 -name => 'foo',
369 -values => ['an','array','of','values'],
370 );
371 -or-
373 $q->param(
375 -name => 'foo',
376 -value => 'the value',
377 );
378 Appending additional values to a named parameter
380 $q->append(
381 -name =>'foo',
382 -values =>['yet','more','values'],
383 );
384 This adds a value or list of values to the named parameter. The values
386 are appended to the end of the parameter if it already exists.
387 Otherwise the parameter is created. Note that this method only
388 recognizes the named argument calling syntax.
389 Importing all parameters into a namespace
391 $q->import_names('R');
392 This creates a series of variables in the 'R' namespace. For example,
394 $R::foo, @R:foo. For keyword lists, a variable @R::keywords will
395 appear. If no namespace is given, this method will assume 'Q'. WARNING:
396 don't import anything into 'main'; this is a major security risk!
397 NOTE 1: Variable names are transformed as necessary into legal perl
399 variable names. All non-legal characters are transformed into
400 underscores. If you need to keep the original names, you should use the
401 param() method instead to access CGI variables by name.
402 In fact, you should probably not use this method at all given the above
404 caveats and security risks.
405 Deleting a parameter completely
407 $q->delete('foo','bar','baz');
408 This completely clears a list of parameters. It sometimes useful for
410 resetting parameters that you don't want passed down between script
411 invocations.
412 If you are using the function call interface, use "Delete()" instead to
414 avoid conflicts with perl's built-in delete operator.
415 Deleting all parameters
417 $q->delete_all();
418 This clears the CGI object completely. It might be useful to ensure
420 that all the defaults are taken when you create a fill-out form.
421 Use Delete_all() instead if you are using the function call interface.
423 Handling non-urlencoded arguments
425 If POSTed data is not of type application/x-www-form-urlencoded or
426 multipart/form-data, then the POSTed data will not be processed, but
427 instead be returned as-is in a parameter named POSTDATA. To retrieve
428 it, use code like this:
429 my $data = $q->param('POSTDATA');
431 Likewise if PUTed and PATCHed data can be retrieved with code like
433 this:
434 my $data = $q->param('PUTDATA');
436 my $data = $q->param('PATCHDATA');
438 (If you don't know what the preceding means, worry not. It only affects
440 people trying to use CGI for XML processing and other specialized
441 tasks)
442 PUTDATA/POSTDATA/PATCHDATA are also available via upload_hook, and as
444 file uploads via "-putdata_upload" option.
445 Direct access to the parameter list
447 $q->param_fetch('address')->[1] = '1313 Mockingbird Lane';
448 unshift @{$q->param_fetch(-name=>'address')},'George Munster';
449 If you need access to the parameter list in a way that isn't covered by
451 the methods given in the previous sections, you can obtain a direct
452 reference to it by calling the param_fetch() method with the name of
453 the parameter. This will return an array reference to the named
454 parameter, which you then can manipulate in any way you like.
455 You can also use a named argument style using the -name argument.
457 Fetching the parameter list as a hash
459 my $params = $q->Vars;
460 print $params->{'address'};
461 my @foo = split("\0",$params->{'foo'});
462 my %params = $q->Vars;
463 use CGI ':cgi-lib';
465 my $params = Vars();
466 Many people want to fetch the entire parameter list as a hash in which
468 the keys are the names of the CGI parameters, and the values are the
469 parameters' values. The Vars() method does this. Called in a scalar
470 context, it returns the parameter list as a tied hash reference.
471 Changing a key changes the value of the parameter in the underlying CGI
472 parameter list. Called in a list context, it returns the parameter list
473 as an ordinary hash. This allows you to read the contents of the
474 parameter list, but not to change it.
475 When using this, the thing you must watch out for are multivalued CGI
477 parameters. Because a hash cannot distinguish between scalar and list
478 context, multivalued parameters will be returned as a packed string,
479 separated by the "\0" (null) character. You must split this packed
480 string in order to get at the individual values. This is the convention
481 introduced long ago by Steve Brenner in his cgi-lib.pl module for perl
482 version 4, and may be replaced in future versions with array
483 references.
484 If you wish to use Vars() as a function, import the :cgi-lib set of
486 function calls (also see the section on CGI-LIB compatibility).
487 Saving the state of the script to a file
489 $q->save(\*FILEHANDLE)
490 This will write the current state of the form to the provided
492 filehandle. You can read it back in by providing a filehandle to the
493 new() method. Note that the filehandle can be a file, a pipe, or
494 whatever.
495 The format of the saved file is:
497 NAME1=VALUE1
499 NAME1=VALUE1'
500 NAME2=VALUE2
501 NAME3=VALUE3
502 =
503 Both name and value are URL escaped. Multi-valued CGI parameters are
505 represented as repeated names. A session record is delimited by a
506 single = symbol. You can write out multiple records and read them back
507 in with several calls to new. You can do this across several sessions
508 by opening the file in append mode, allowing you to create primitive
509 guest books, or to keep a history of users' queries. Here's a short
510 example of creating multiple session records:
511 use strict;
513 use warnings;
514 use CGI;
515 open (my $out_fh,'>>','test.out') || die "Can't open test.out: $!";
517 my $records = 5;
518 for ( 0 .. $records ) {
519 my $q = CGI->new;
520 $q->param( -name => 'counter',-value => $_ );
521 $q->save( $out_fh );
522 }
523 close( $out_fh );
524 # reopen for reading
526 open (my $in_fh,'<','test.out') || die "Can't open test.out: $!";
527 while (!eof($in_fh)) {
528 my $q = CGI->new($in_fh);
529 print $q->param('counter'),"\n";
530 }
531 The file format used for save/restore is identical to that used by the
533 Whitehead Genome Center's data exchange format "Boulderio", and can be
534 manipulated and even databased using Boulderio utilities. See Boulder
535 for further details.
536 If you wish to use this method from the function-oriented (non-OO)
538 interface, the exported name for this method is save_parameters().
539 Retrieving cgi errors
541 Errors can occur while processing user input, particularly when
542 processing uploaded files. When these errors occur, CGI will stop
543 processing and return an empty parameter list. You can test for the
544 existence and nature of errors using the cgi_error() function. The
545 error messages are formatted as HTTP status codes. You can either
546 incorporate the error text into a page, or use it as the value of the
547 HTTP status:
548 if ( my $error = $q->cgi_error ) {
550 print $q->header( -status => $error );
551 print "Error: $error";
552 exit 0;
553 }
554 When using the function-oriented interface (see the next section),
556 errors may only occur the first time you call param(). Be ready for
557 this!
558 Using the function-oriented interface
560 To use the function-oriented interface, you must specify which CGI.pm
561 routines or sets of routines to import into your script's namespace.
562 There is a small overhead associated with this importation, but it
563 isn't much.
564 use strict;
566 use warnings;
567 use CGI qw/ list of methods /;
569 The listed methods will be imported into the current package; you can
571 call them directly without creating a CGI object first. This example
572 shows how to import the param() and header() methods, and then use them
573 directly:
574 use strict;
576 use warnings;
577 use CGI qw/ param header /;
579 print header('text/plain');
580 my $zipcode = param('zipcode');
581 More frequently, you'll import common sets of functions by referring to
583 the groups by name. All function sets are preceded with a ":" character
584 as in ":cgi" (for CGI protocol handling methods).
585 Here is a list of the function sets you can import:
587 :cgi
589 Import all CGI-handling methods, such as param(), path_info() and
590 the like.
591 :all
593 Import all the available methods. For the full list, see the CGI.pm
594 code, where the variable %EXPORT_TAGS is defined. (N.B. the
595 :cgi-lib imports will not be included in the :all import, you will
596 have to import :cgi-lib to get those)
597 Note that in the interests of execution speed CGI.pm does not use the
599 standard Exporter syntax for specifying load symbols. This may change
600 in the future.
601 Pragmas
603 In addition to the function sets, there are a number of pragmas that
604 you can import. Pragmas, which are always preceded by a hyphen, change
605 the way that CGI.pm functions in various ways. Pragmas, function sets,
606 and individual functions can all be imported in the same use() line.
607 For example, the following use statement imports the cgi set of
608 functions and enables debugging mode (pragma -debug):
609 use strict;
611 use warninigs;
612 use CGI qw/ :cgi -debug /;
613 The current list of pragmas is as follows:
615 -no_undef_params
617 This keeps CGI.pm from including undef params in the parameter
618 list.
619 -utf8
621 This makes CGI.pm treat all parameters as text strings rather than
622 binary strings (see perlunitut for the distinction), assuming UTF-8
623 for the encoding.
624 CGI.pm does the decoding from the UTF-8 encoded input data,
626 restricting this decoding to input text as distinct from binary
627 upload data which are left untouched. Therefore, a ':utf8' layer
628 must not be used on STDIN.
629 If you do not use this option you can manually select which fields
631 are expected to return utf-8 strings and convert them using code
632 like this:
633 use strict;
635 use warnings;
636 use CGI;
638 use Encode qw/ decode /;
639 my $cgi = CGI->new;
641 my $param = $cgi->param('foo');
642 $param = decode( 'UTF-8',$param );
643 -putdata_upload / -postdata_upload / -patchdata_upload
645 Makes "$cgi->param('PUTDATA');", "$cgi->param('PATCHDATA');", and
646 "$cgi->param('POSTDATA');" act like file uploads named PUTDATA,
647 PATCHDATA, and POSTDATA. See "Handling non-urlencoded arguments"
648 and "Processing a file upload field" PUTDATA/POSTDATA/PATCHDATA are
649 also available via upload_hook.
650 -nph
652 This makes CGI.pm produce a header appropriate for an NPH (no
653 parsed header) script. You may need to do other things as well to
654 tell the server that the script is NPH. See the discussion of NPH
655 scripts below.
656 -newstyle_urls
658 Separate the name=value pairs in CGI parameter query strings with
659 semicolons rather than ampersands. For example:
660 ?name=fred;age=24;favorite_color=3
662 Semicolon-delimited query strings are always accepted, and will be
664 emitted by self_url() and query_string(). newstyle_urls became the
665 default in version 2.64.
666 -oldstyle_urls
668 Separate the name=value pairs in CGI parameter query strings with
669 ampersands rather than semicolons. This is no longer the default.
670 -no_debug
672 This turns off the command-line processing features. If you want to
673 run a CGI.pm script from the command line, and you don't want it to
674 read CGI parameters from the command line or STDIN, then use this
675 pragma:
676 use CGI qw/ -no_debug :standard /;
678 -debug
680 This turns on full debugging. In addition to reading CGI arguments
681 from the command-line processing, CGI.pm will pause and try to read
682 arguments from STDIN, producing the message "(offline mode: enter
683 name=value pairs on standard input)" features.
684 See the section on debugging for more details.
686
688 Most of CGI.pm's functions deal with creating documents on the fly.
689 Generally you will produce the HTTP header first, followed by the
690 document itself. CGI.pm provides functions for generating HTTP headers
691 of various types.
692 Each of these functions produces a fragment of HTTP which you can print
694 out directly so that it is processed by the browser, appended to a
695 string, or saved to a file for later use.
696 Creating a standard http header
698 Normally the first thing you will do in any CGI script is print out an
699 HTTP header. This tells the browser what type of document to expect,
700 and gives other optional information, such as the language, expiration
701 date, and whether to cache the document. The header can also be
702 manipulated for special purposes, such as server push and pay per view
703 pages.
704 use strict;
706 use warnings;
707 use CGI;
709 my $cgi = CGI->new;
711 print $cgi->header;
713 -or-
715 print $cgi->header('image/gif');
717 -or-
719 print $cgi->header('text/html','204 No response');
721 -or-
723 print $cgi->header(
725 -type => 'image/gif',
726 -nph => 1,
727 -status => '402 Payment required',
728 -expires => '+3d',
729 -cookie => $cookie,
730 -charset => 'utf-8',
731 -attachment => 'foo.gif',
732 -Cost => '$2.00'
733 );
734 header() returns the Content-type: header. You can provide your own
736 MIME type if you choose, otherwise it defaults to text/html. An
737 optional second parameter specifies the status code and a human-
738 readable message. For example, you can specify 204, "No response" to
739 create a script that tells the browser to do nothing at all. Note that
740 RFC 2616 expects the human-readable phase to be there as well as the
741 numeric status code.
742 The last example shows the named argument style for passing arguments
744 to the CGI methods using named parameters. Recognized parameters are
745 -type, -status, -expires, and -cookie. Any other named parameters will
746 be stripped of their initial hyphens and turned into header fields,
747 allowing you to specify any HTTP header you desire. Internal
748 underscores will be turned into hyphens:
749 print $cgi->header( -Content_length => 3002 );
751 Most browsers will not cache the output from CGI scripts. Every time
753 the browser reloads the page, the script is invoked anew. You can
754 change this behavior with the -expires parameter. When you specify an
755 absolute or relative expiration interval with this parameter, some
756 browsers and proxy servers will cache the script's output until the
757 indicated expiration date. The following forms are all valid for the
758 -expires field:
759 +30s 30 seconds from now
761 +10m ten minutes from now
762 +1h one hour from now
763 -1d yesterday (i.e. "ASAP!")
764 now immediately
765 +3M in three months
766 +10y in ten years time
767 Thursday, 25-Apr-2018 00:40:33 GMT at the indicated time & date
768 The -cookie parameter generates a header that tells the browser to
770 provide a "magic cookie" during all subsequent transactions with your
771 script. Some cookies have a special format that includes interesting
772 attributes such as expiration time. Use the cookie() method to create
773 and retrieve session cookies.
774 The -nph parameter, if set to a true value, will issue the correct
776 headers to work with a NPH (no-parse-header) script. This is important
777 to use with certain servers that expect all their scripts to be NPH.
778 The -charset parameter can be used to control the character set sent to
780 the browser. If not provided, defaults to ISO-8859-1. As a side effect,
781 this sets the charset() method as well. Note that the default being
782 ISO-8859-1 may not make sense for all content types, e.g.:
783 Content-Type: image/gif; charset=ISO-8859-1
785 In the above case you need to pass -charset => '' to prevent the
787 default being used.
788 The -attachment parameter can be used to turn the page into an
790 attachment. Instead of displaying the page, some browsers will prompt
791 the user to save it to disk. The value of the argument is the suggested
792 name for the saved file. In order for this to work, you may have to set
793 the -type to "application/octet-stream".
794 The -p3p parameter will add a P3P tag to the outgoing header. The
796 parameter can be an arrayref or a space-delimited string of P3P tags.
797 For example:
798 print $cgi->header( -p3p => [ qw/ CAO DSP LAW CURa / ] );
800 print $cgi->header( -p3p => 'CAO DSP LAW CURa' );
801 In either case, the outgoing header will be formatted as:
803 P3P: policyref="/w3c/p3p.xml" cp="CAO DSP LAW CURa"
805 CGI.pm will accept valid multi-line headers when each line is separated
807 with a CRLF value ("\r\n" on most platforms) followed by at least one
808 space. For example:
809 print $cgi->header( -ingredients => "ham\r\n\seggs\r\n\sbacon" );
811 Invalid multi-line header input will trigger in an exception. When
813 multi-line headers are received, CGI.pm will always output them back as
814 a single line, according to the folding rules of RFC 2616: the newlines
815 will be removed, while the white space remains.
816 Generating a redirection header
818 print $q->redirect( 'http://somewhere.else/in/movie/land' );
819 Sometimes you don't want to produce a document yourself, but simply
821 redirect the browser elsewhere, perhaps choosing a URL based on the
822 time of day or the identity of the user.
823 The redirect() method redirects the browser to a different URL. If you
825 use redirection like this, you should not print out a header as well.
826 You are advised to use full URLs (absolute with respect to current URL
828 or even including the http: or ftp: part) in redirection requests as
829 relative URLs are resolved by the user agent of the client so may not
830 do what you want or expect them to do.
831 You can also use named arguments:
833 print $q->redirect(
835 -uri => 'http://somewhere.else/in/movie/land',
836 -nph => 1,
837 -status => '301 Moved Permanently'
838 );
839 All names arguments recognized by header() are also recognized by
841 redirect(). However, most HTTP headers, including those generated by
842 -cookie and -target, are ignored by the browser.
843 The -nph parameter, if set to a true value, will issue the correct
845 headers to work with a NPH (no-parse-header) script. This is important
846 to use with certain servers, such as Microsoft IIS, which expect all
847 their scripts to be NPH.
848 The -status parameter will set the status of the redirect. HTTP defines
850 several different possible redirection status codes, and the default if
851 not specified is 302, which means "moved temporarily." You may change
852 the status to another status code if you wish.
853 Note that the human-readable phrase is also expected to be present to
855 conform with RFC 2616, section 6.1.
856 Creating a self-referencing url that preserves state information
858 my $myself = $q->self_url;
859 print qq(<a href="$myself">I'm talking to myself.</a>);
860 self_url() will return a URL, that, when selected, will re-invoke this
862 script with all its state information intact. This is most useful when
863 you want to jump around within the document using internal anchors but
864 you don't want to disrupt the current contents of the form(s).
865 Something like this will do the trick:
866 my $myself = $q->self_url;
868 print "<a href=\"$myself#table1\">See table 1</a>";
869 print "<a href=\"$myself#table2\">See table 2</a>";
870 print "<a href=\"$myself#yourself\">See for yourself</a>";
871 If you want more control over what's returned, using the url() method
873 instead.
874 You can also retrieve a query string representation of the current
876 object state with query_string():
877 my $the_string = $q->query_string();
879 The behavior of calling query_string is currently undefined when the
881 HTTP method is something other than GET.
882 If you want to retrieved the query string as set in the webserver,
884 namely the environment variable, you can call env_query_string()
885 Obtaining the script's url
887 my $full_url = url();
888 my $full_url = url( -full =>1 ); # alternative syntax
889 my $relative_url = url( -relative => 1 );
890 my $absolute_url = url( -absolute =>1 );
891 my $url_with_path = url( -path_info => 1 );
892 my $url_path_qry = url( -path_info => 1, -query =>1 );
893 my $netloc = url( -base => 1 );
894 url() returns the script's URL in a variety of formats. Called without
896 any arguments, it returns the full form of the URL, including host name
897 and port number
898 http://your.host.com/path/to/script.cgi
900 You can modify this format with the following named arguments:
902 -absolute
904 If true, produce an absolute URL, e.g.
905 /path/to/script.cgi
907 -relative
909 Produce a relative URL. This is useful if you want to re-invoke
910 your script with different parameters. For example:
911 script.cgi
913 -full
915 Produce the full URL, exactly as if called without any arguments.
916 This overrides the -relative and -absolute arguments.
917 -path (-path_info)
919 Append the additional path information to the URL. This can be
920 combined with -full, -absolute or -relative. -path_info is provided
921 as a synonym.
922 -query (-query_string)
924 Append the query string to the URL. This can be combined with
925 -full, -absolute or -relative. -query_string is provided as a
926 synonym.
927 -base
929 Generate just the protocol and net location, as in
930 http://www.foo.com:8000
931 -rewrite
933 If Apache's mod_rewrite is turned on, then the script name and path
934 info probably won't match the request that the user sent. Set
935 -rewrite => 1 (default) to return URLs that match what the user
936 sent (the original request URI). Set -rewrite => 0 to return URLs
937 that match the URL after the mod_rewrite rules have run.
938 Mixing post and url parameters
940 my $color = url_param('color');
941 It is possible for a script to receive CGI parameters in the URL as
943 well as in the fill-out form by creating a form that POSTs to a URL
944 containing a query string (a "?" mark followed by arguments). The
945 param() method will always return the contents of the POSTed fill-out
946 form, ignoring the URL's query string. To retrieve URL parameters, call
947 the url_param() method. Use it in the same way as param(). The main
948 difference is that it allows you to read the parameters, but not set
949 them.
950 Under no circumstances will the contents of the URL query string
952 interfere with similarly-named CGI parameters in POSTed forms. If you
953 try to mix a URL query string with a form submitted with the GET
954 method, the results will not be what you expect.
955 If running from the command line, "url_param" will not pick up any
957 parameters given on the command line.
958 Processing a file upload field
960 Basics
961 When the form is processed, you can retrieve an IO::File compatible
963 handle for a file upload field like this:
964 use autodie;
966 # undef may be returned if it's not a valid file handle
968 if ( my $io_handle = $q->upload('field_name') ) {
969 open ( my $out_file,'>>','/usr/local/web/users/feedback' );
970 while ( my $bytesread = $io_handle->read($buffer,1024) ) {
971 print $out_file $buffer;
972 }
973 }
974 In a list context, upload() will return an array of filehandles. This
976 makes it possible to process forms that use the same name for multiple
977 upload fields.
978 If you want the entered file name for the file, you can just call
980 param():
981 my $filename = $q->param('field_name');
983 Different browsers will return slightly different things for the name.
985 Some browsers return the filename only. Others return the full path to
986 the file, using the path conventions of the user's machine. Regardless,
987 the name returned is always the name of the file on the user's machine,
988 and is unrelated to the name of the temporary file that CGI.pm creates
989 during upload spooling (see below).
990 When a file is uploaded the browser usually sends along some
992 information along with it in the Content-Type (MIME type) and Content-
993 Disposition (filename) headers. To retrieve this information, call
994 uploadInfo(). It returns a reference to a hash containing all the
995 document headers.
996 my $filehandle = $q->upload( 'uploaded_file' );
998 my $type = $q->uploadInfo( $filehandle )->{'Content-Type'};
999 if ( $type ne 'text/html' ) {
1000 die "HTML FILES ONLY!";
1001 }
1002 Note that you must use ->upload or ->param to get the file-handle to
1004 pass into uploadInfo as internally this is represented as a File::Temp
1005 object (which is what will be returned by ->upload or ->param). When
1006 using ->Vars you will get the literal filename rather than the
1007 File::Temp object, which will not return anything when passed to
1008 uploadInfo. So don't use ->Vars.
1009 When uploading multiple files, call ->param() in list context to
1011 retrieve a list of filehandles that you can use when calling
1012 ->uploadInfo.
1013 my @filehandles = $q->param('uploaded_file');
1015 for my $fh (@filehandles) {
1017 my $info = $q->uploadInfo($fh);
1018 ...
1019 }
1020 If you are using a machine that recognizes "text" and "binary" data
1022 modes, be sure to understand when and how to use them (see the Camel
1023 book). Otherwise you may find that binary files are corrupted during
1024 file uploads.
1025 Accessing the temp files directly
1027 When processing an uploaded file, CGI.pm creates a temporary file on
1029 your hard disk and passes you a file handle to that file. After you are
1030 finished with the file handle, CGI.pm unlinks (deletes) the temporary
1031 file. If you need to you can access the temporary file directly. You
1032 can access the temp file for a file upload by passing the file name to
1033 the tmpFileName() method:
1034 my $filehandle = $q->upload( 'uploaded_file' );
1036 my $tmpfilename = $q->tmpFileName( $filehandle );
1037 As with ->uploadInfo, using the reference returned by ->upload or
1039 ->param is preferred, although unlike ->uploadInfo, plain filenames
1040 also work if possible for backwards compatibility.
1041 The temporary file will be deleted automatically when your program
1043 exits unless you manually rename it or set $CGI::UNLINK_TMP_FILES to 0.
1044 On some operating systems (such as Windows NT), you will need to close
1045 the temporary file's filehandle before your program exits. Otherwise
1046 the attempt to delete the temporary file will fail.
1047 Changes in temporary file handling (v4.05+)
1049 CGI.pm had its temporary file handling significantly refactored, this
1051 logic is now all deferred to File::Temp (which is wrapped in a
1052 compatibility object, CGI::File::Temp - DO NOT USE THIS PACKAGE
1053 DIRECTLY). As a consequence the PRIVATE_TEMPFILES variable has been
1054 removed along with deprecation of the private_tempfiles routine and
1055 complete removal of the CGITempFile package. The
1056 $CGITempFile::TMPDIRECTORY is no longer used to set the temp directory,
1057 refer to the perldoc for File::Temp if you want to override the default
1058 settings in that package (the TMPDIR env variable is still available on
1059 some platforms). For Windows platforms the temporary directory order
1060 remains as before: TEMP > TMP > WINDIR ( > TMPDIR ) so if you have any
1061 of these in use in existing scripts they should still work.
1062 The Fh package still exists but does nothing, the CGI::File::Temp class
1064 is a subclass of both File::Temp and the empty Fh package, so if you
1065 have any code that checks that the filehandle isa Fh this should still
1066 work.
1067 When you get the internal file handle you will receive a File::Temp
1069 object, this should be transparent as File::Temp isa IO::Handle and isa
1070 IO::Seekable meaning it behaves as previously. If you are doing
1071 anything out of the ordinary with regards to temp files you should test
1072 your code before deploying this update and refer to the File::Temp
1073 documentation for more information.
1074 Handling interrupted file uploads
1076 There are occasionally problems involving parsing the uploaded file.
1078 This usually happens when the user presses "Stop" before the upload is
1079 finished. In this case, CGI.pm will return undef for the name of the
1080 uploaded file and set cgi_error() to the string "400 Bad request
1081 (malformed multipart POST)". This error message is designed so that you
1082 can incorporate it into a status code to be sent to the browser.
1083 Example:
1084 my $file = $q->upload( 'uploaded_file' );
1086 if ( !$file && $q->cgi_error ) {
1087 print $q->header( -status => $q->cgi_error );
1088 exit 0;
1089 }
1090 Progress bars for file uploads and avoiding temp files
1092 CGI.pm gives you low-level access to file upload management through a
1094 file upload hook. You can use this feature to completely turn off the
1095 temp file storage of file uploads, or potentially write your own file
1096 upload progress meter.
1097 This is much like the UPLOAD_HOOK facility available in
1099 Apache::Request, with the exception that the first argument to the
1100 callback is an Apache::Upload object, here it's the remote filename.
1101 my $q = CGI->new( \&hook [,$data [,$use_tempfile]] );
1103 sub hook {
1105 my ( $filename, $buffer, $bytes_read, $data ) = @_;
1106 print "Read $bytes_read bytes of $filename\n";
1107 }
1108 The $data field is optional; it lets you pass configuration information
1110 (e.g. a database handle) to your hook callback.
1111 The $use_tempfile field is a flag that lets you turn on and off
1113 CGI.pm's use of a temporary disk-based file during file upload. If you
1114 set this to a FALSE value (default true) then
1115 "$q->param('uploaded_file')" will still return a typeglob that can be
1116 used to access a filehandle and the filename of the uploaded file,
1117 however the filehandle will be a handle to an empty file. Existence of
1118 your hook causes CGI.pm to bypass writing to that filehandle (which is
1119 probably what you intended when you set $use_tempfile off).
1120 The uploadInfo() method can be used on the typeglob returned to you
1122 when you called "$q->param('upload_file')" to return information about
1123 the uploaded file(s). For multiple file uploads, use the param()
1124 method in list context to retrieve all of the typeglobs.
1125 my (@filehandles) = $cgi->param('upfile');
1127 foreach my $fh (@filehandles) {
1129 my $info = $cgi->uploadInfo($fh);
1130 ...
1131 }
1132 If using the function-oriented interface, call the CGI::upload_hook()
1134 method before calling param() or any other CGI functions:
1135 CGI::upload_hook( \&hook [,$data [,$use_tempfile]] );
1137 This method is not exported by default. You will have to import it
1139 explicitly if you wish to use it without the CGI:: prefix.
1140 Troubleshooting file uploads on Windows
1142 If you are using CGI.pm on a Windows platform and find that binary
1144 files get slightly larger when uploaded but that text files remain the
1145 same, then you have forgotten to activate binary mode on the output
1146 filehandle. Be sure to call binmode() on any handle that you create to
1147 write the uploaded file to disk.
1148 Older ways to process file uploads
1150 This section is here for completeness. if you are building a new
1152 application with CGI.pm, you can skip it.
1153 The original way to process file uploads with CGI.pm was to use
1155 param(). The value it returns has a dual nature as both a file name and
1156 a lightweight filehandle. This dual nature is problematic if you
1157 following the recommended practice of having "use strict" in your code.
1158 perl will complain when you try to use a string as a filehandle. More
1159 seriously, it is possible for the remote user to type garbage into the
1160 upload field, in which case what you get from param() is not a
1161 filehandle at all, but a string.
1162 To solve this problem the upload() method was added, which always
1164 returns a lightweight filehandle. This generally works well, but will
1165 have trouble interoperating with some other modules because the file
1166 handle is not derived from IO::File. So that brings us to current
1167 recommendation given above, which is to call the handle() method on the
1168 file handle returned by upload(). That upgrades the handle to an
1169 IO::File. It's a big win for compatibility for a small penalty of
1170 loading IO::File the first time you call it.
1171
1173 CGI.pm has several methods that support cookies.
1174 A cookie is a name=value pair much like the named parameters in a CGI
1176 query string. CGI scripts create one or more cookies and send them to
1177 the browser in the HTTP header. The browser maintains a list of cookies
1178 that belong to a particular Web server, and returns them to the CGI
1179 script during subsequent interactions.
1180 In addition to the required name=value pair, each cookie has several
1182 optional attributes:
1183 1. an expiration time
1185 This is a time/date string (in a special GMT format) that indicates
1186 when a cookie expires. The cookie will be saved and returned to
1187 your script until this expiration date is reached if the user exits
1188 the browser and restarts it. If an expiration date isn't specified,
1189 the cookie will remain active until the user quits the browser.
1190 2. a domain
1192 This is a partial or complete domain name for which the cookie is
1193 valid. The browser will return the cookie to any host that matches
1194 the partial domain name. For example, if you specify a domain name
1195 of ".capricorn.com", then the browser will return the cookie to Web
1196 servers running on any of the machines "www.capricorn.com",
1197 "www2.capricorn.com", "feckless.capricorn.com", etc. Domain names
1198 must contain at least two periods to prevent attempts to match on
1199 top level domains like ".edu". If no domain is specified, then the
1200 browser will only return the cookie to servers on the host the
1201 cookie originated from.
1202 3. a path
1204 If you provide a cookie path attribute, the browser will check it
1205 against your script's URL before returning the cookie. For example,
1206 if you specify the path "/cgi-bin", then the cookie will be
1207 returned to each of the scripts "/cgi-bin/tally.pl",
1208 "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl",
1209 but not to the script "/cgi-private/site_admin.pl". By default,
1210 path is set to "/", which causes the cookie to be sent to any CGI
1211 script on your site.
1212 4. a "secure" flag
1214 If the "secure" attribute is set, the cookie will only be sent to
1215 your script if the CGI request is occurring on a secure channel,
1216 such as SSL.
1217 The interface to HTTP cookies is the cookie() method:
1219 my $cookie = $q->cookie(
1221 -name => 'sessionID',
1222 -value => 'xyzzy',
1223 -expires => '+1h',
1224 -path => '/cgi-bin/database',
1225 -domain => '.capricorn.org',
1226 -secure => 1
1227 );
1228 print $q->header( -cookie => $cookie );
1230 cookie() creates a new cookie. Its parameters include:
1232 -name
1234 The name of the cookie (required). This can be any string at all.
1235 Although browsers limit their cookie names to non-whitespace
1236 alphanumeric characters, CGI.pm removes this restriction by
1237 escaping and unescaping cookies behind the scenes.
1238 -value
1240 The value of the cookie. This can be any scalar value, array
1241 reference, or even hash reference. For example, you can store an
1242 entire hash into a cookie this way:
1243 my $cookie = $q->cookie(
1245 -name => 'family information',
1246 -value => \%childrens_ages
1247 );
1248 -path
1250 The optional partial path for which this cookie will be valid, as
1251 described above.
1252 -domain
1254 The optional partial domain for which this cookie will be valid, as
1255 described above.
1256 -expires
1258 The optional expiration date for this cookie. The format is as
1259 described in the section on the header() method:
1260 "+1h" one hour from now
1262 -secure
1264 If set to true, this cookie will only be used within a secure SSL
1265 session.
1266 The cookie created by cookie() must be incorporated into the HTTP
1268 header within the string returned by the header() method:
1269 use strict;
1271 use warnings;
1272 use CGI;
1274 my $q = CGI->new;
1276 my $cookie = ...
1277 print $q->header( -cookie => $cookie );
1278 To create multiple cookies, give header() an array reference:
1280 my $cookie1 = $q->cookie(
1282 -name => 'riddle_name',
1283 -value => "The Sphynx's Question"
1284 );
1285 my $cookie2 = $q->cookie(
1287 -name => 'answers',
1288 -value => \%answers
1289 );
1290 print $q->header( -cookie => [ $cookie1,$cookie2 ] );
1292 To retrieve a cookie, request it by name by calling cookie() method
1294 without the -value parameter. This example uses the object-oriented
1295 form:
1296 my $riddle = $q->cookie('riddle_name');
1298 my %answers = $q->cookie('answers');
1299 Cookies created with a single scalar value, such as the "riddle_name"
1301 cookie, will be returned in that form. Cookies with array and hash
1302 values can also be retrieved.
1303 The cookie and CGI namespaces are separate. If you have a parameter
1305 named 'answers' and a cookie named 'answers', the values retrieved by
1306 param() and cookie() are independent of each other. However, it's
1307 simple to turn a CGI parameter into a cookie, and vice-versa:
1308 # turn a CGI parameter into a cookie
1310 my $c = cookie( -name => 'answers',-value => [$q->param('answers')] );
1311 # vice-versa
1312 $q->param( -name => 'answers',-value => [ $q->cookie('answers')] );
1313 If you call cookie() without any parameters, it will return a list of
1315 the names of all cookies passed to your script:
1316 my @cookies = $q->cookie();
1318 See the cookie.cgi example script for some ideas on how to use cookies
1320 effectively.
1321 $CGI::COOKIE_CACHE
1323 If set to a non-negative integer, this variable will cause CGI.pm
1324 to use the cached cookie details from the previous call to
1325 cookie(). By default this cache is off to retain backwards
1326 compatibility.
1327
1329 If you are running the script from the command line or in the perl
1330 debugger, you can pass the script a list of keywords or parameter=value
1331 pairs on the command line or from standard input (you don't have to
1332 worry about tricking your script into reading from environment
1333 variables). You can pass keywords like this:
1334 your_script.pl keyword1 keyword2 keyword3
1336 or this:
1338 your_script.pl keyword1+keyword2+keyword3
1340 or this:
1342 your_script.pl name1=value1 name2=value2
1344 or this:
1346 your_script.pl name1=value1&name2=value2
1348 To turn off this feature, use the -no_debug pragma.
1350 To test the POST method, you may enable full debugging with the -debug
1352 pragma. This will allow you to feed newline-delimited name=value pairs
1353 to the script on standard input.
1354 When debugging, you can use quotes and backslashes to escape characters
1356 in the familiar shell manner, letting you place spaces and other funny
1357 characters in your parameter=value pairs:
1358 your_script.pl "name1='I am a long value'" "name2=two\ words"
1360 Finally, you can set the path info for the script by prefixing the
1362 first name/value parameter with the path followed by a question mark
1363 (?):
1364 your_script.pl /your/path/here?name1=value1&name2=value2
1366
1368 Some of the more useful environment variables can be fetched through
1369 this interface. The methods are as follows:
1370 Accept()
1372 Return a list of MIME types that the remote browser accepts. If you
1373 give this method a single argument corresponding to a MIME type, as
1374 in Accept('text/html'), it will return a floating point value
1375 corresponding to the browser's preference for this type from 0.0
1376 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's
1377 accept list are handled correctly.
1378 Note that the capitalization changed between version 2.43 and 2.44
1380 in order to avoid conflict with perl's accept() function.
1381 raw_cookie()
1383 Returns the HTTP_COOKIE variable. Cookies have a special format,
1384 and this method call just returns the raw form (?cookie dough). See
1385 cookie() for ways of setting and retrieving cooked cookies.
1386 Called with no parameters, raw_cookie() returns the packed cookie
1388 structure. You can separate it into individual cookies by
1389 splitting on the character sequence "; ". Called with the name of a
1390 cookie, retrieves the unescaped form of the cookie. You can use the
1391 regular cookie() method to get the names, or use the raw_fetch()
1392 method from the CGI::Cookie module.
1393 env_query_string()
1395 Returns the QUERY_STRING variable, note that this is the original
1396 value as set in the environment by the webserver and (possibly) not
1397 the same value as returned by query_string(), which represents the
1398 object state
1399 user_agent()
1401 Returns the HTTP_USER_AGENT variable. If you give this method a
1402 single argument, it will attempt to pattern match on it, allowing
1403 you to do something like user_agent(Mozilla);
1404 path_info()
1406 Returns additional path information from the script URL. E.G.
1407 fetching /cgi-bin/your_script/additional/stuff will result in
1408 path_info() returning "/additional/stuff".
1409 NOTE: The Microsoft Internet Information Server is broken with
1411 respect to additional path information. If you use the perl DLL
1412 library, the IIS server will attempt to execute the additional path
1413 information as a perl script. If you use the ordinary file
1414 associations mapping, the path information will be present in the
1415 environment, but incorrect. The best thing to do is to avoid using
1416 additional path information in CGI scripts destined for use with
1417 IIS. A best attempt has been made to make CGI.pm do the right
1418 thing.
1419 path_translated()
1421 As per path_info() but returns the additional path information
1422 translated into a physical path, e.g.
1423 "/usr/local/etc/httpd/htdocs/additional/stuff".
1424 The Microsoft IIS is broken with respect to the translated path as
1426 well.
1427 remote_host()
1429 Returns either the remote host name or IP address if the former is
1430 unavailable.
1431 remote_ident()
1433 Returns the name of the remote user (as returned by identd) or
1434 undef if not set
1435 remote_addr()
1437 Returns the remote host IP address, or 127.0.0.1 if the address is
1438 unavailable.
1439 request_uri()
1441 Returns the interpreted pathname of the requested document or CGI
1442 (relative to the document root). Or undef if not set.
1443 script_name()
1445 Return the script name as a partial URL, for self-referring
1446 scripts.
1447 referer()
1449 Return the URL of the page the browser was viewing prior to
1450 fetching your script.
1451 auth_type()
1453 Return the authorization/verification method in use for this
1454 script, if any.
1455 server_name()
1457 Returns the name of the server, usually the machine's host name.
1458 virtual_host()
1460 When using virtual hosts, returns the name of the host that the
1461 browser attempted to contact
1462 server_port()
1464 Return the port that the server is listening on.
1465 server_protocol()
1467 Returns the protocol and revision of the incoming request, or
1468 defaults to HTTP/1.0 if this is not set
1469 virtual_port()
1471 Like server_port() except that it takes virtual hosts into account.
1472 Use this when running with virtual hosts.
1473 server_software()
1475 Returns the server software and version number.
1476 remote_user()
1478 Return the authorization/verification name used for user
1479 verification, if this script is protected.
1480 user_name()
1482 Attempt to obtain the remote user's name, using a variety of
1483 different techniques. May not work in all browsers.
1484 request_method()
1486 Returns the method used to access your script, usually one of
1487 'POST', 'GET' or 'HEAD'. If running from the command line it will
1488 be undef.
1489 content_type()
1491 Returns the content_type of data submitted in a POST, generally
1492 multipart/form-data or application/x-www-form-urlencoded
1493 http()
1495 Called with no arguments returns the list of HTTP environment
1496 variables, including such things as HTTP_USER_AGENT,
1497 HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the
1498 like-named HTTP header fields in the request. Called with the name
1499 of an HTTP header field, returns its value. Capitalization and the
1500 use of hyphens versus underscores are not significant.
1501 For example, all three of these examples are equivalent:
1503 my $requested_language = $q->http('Accept-language');
1505 my $requested_language = $q->http('Accept_language');
1507 my $requested_language = $q->http('HTTP_ACCEPT_LANGUAGE');
1509 https()
1511 The same as http(), but operates on the HTTPS environment variables
1512 present when the SSL protocol is in effect. Can be used to
1513 determine whether SSL is turned on.
1514
1516 NPH, or "no-parsed-header", scripts bypass the server completely by
1517 sending the complete HTTP header directly to the browser. This has
1518 slight performance benefits, but is of most use for taking advantage of
1519 HTTP extensions that are not directly supported by your server, such as
1520 server push and PICS headers.
1521 Servers use a variety of conventions for designating CGI scripts as
1523 NPH. Many Unix servers look at the beginning of the script's name for
1524 the prefix "nph-". The Macintosh WebSTAR server and Microsoft's
1525 Internet Information Server, in contrast, try to decide whether a
1526 program is an NPH script by examining the first line of script output.
1527 CGI.pm supports NPH scripts with a special NPH mode. When in this mode,
1529 CGI.pm will output the necessary extra header information when the
1530 header() and redirect() methods are called.
1531 The Microsoft Internet Information Server requires NPH mode. As of
1533 version 2.30, CGI.pm will automatically detect when the script is
1534 running under IIS and put itself into this mode. You do not need to do
1535 this manually, although it won't hurt anything if you do.
1536 In the use statement
1538 Simply add the "-nph" pragma to the list of symbols to be imported
1539 into your script:
1540 use CGI qw(:standard -nph)
1542 By calling the nph() method:
1544 Call nph() with a non-zero parameter at any point after using
1545 CGI.pm in your program.
1546 CGI->nph(1)
1548 By using -nph parameters
1550 in the header() and redirect() statements:
1551 print header(-nph=>1);
1553
1555 CGI.pm provides four simple functions for producing multipart documents
1556 of the type needed to implement server push. These functions were
1557 graciously provided by Ed Jordan <ed@fidalgo.net>. To import these into
1558 your namespace, you must import the ":push" set. You are also advised
1559 to put the script into NPH mode and to set $| to 1 to avoid buffering
1560 problems.
1561 Here is a simple script that demonstrates server push:
1563 #!/usr/bin/env perl
1565 use strict;
1567 use warnings;
1568 use CGI qw/:push -nph/;
1570 $| = 1;
1572 print multipart_init( -boundary=>'----here we go!' );
1573 for (0 .. 4) {
1574 print multipart_start( -type=>'text/plain' ),
1575 "The current time is ",scalar( localtime ),"\n";
1576 if ($_ < 4) {
1577 print multipart_end();
1578 } else {
1579 print multipart_final();
1580 }
1581 sleep 1;
1582 }
1583 This script initializes server push by calling multipart_init(). It
1585 then enters a loop in which it begins a new multipart section by
1586 calling multipart_start(), prints the current local time, and ends a
1587 multipart section with multipart_end(). It then sleeps a second, and
1588 begins again. On the final iteration, it ends the multipart section
1589 with multipart_final() rather than with multipart_end().
1590 multipart_init()
1592 multipart_init( -boundary => $boundary, -charset => $charset );
1593 Initialize the multipart system. The -boundary argument specifies
1595 what MIME boundary string to use to separate parts of the document.
1596 If not provided, CGI.pm chooses a reasonable boundary for you.
1597 The -charset provides the character set, if not provided this will
1599 default to ISO-8859-1
1600 multipart_start()
1602 multipart_start( -type => $type, -charset => $charset );
1603 Start a new part of the multipart document using the specified MIME
1605 type and charset. If not specified, text/html ISO-8859-1 is
1606 assumed.
1607 multipart_end()
1609 multipart_end()
1610 End a part. You must remember to call multipart_end() once for each
1612 multipart_start(), except at the end of the last part of the
1613 multipart document when multipart_final() should be called instead
1614 of multipart_end().
1615 multipart_final()
1617 multipart_final()
1618 End all parts. You should call multipart_final() rather than
1620 multipart_end() at the end of the last part of the multipart
1621 document.
1622 Users interested in server push applications should also have a look at
1624 the CGI::Push module.
1625
1627 A potential problem with CGI.pm is that, by default, it attempts to
1628 process form POSTings no matter how large they are. A wily hacker could
1629 attack your site by sending a CGI script a huge POST of many gigabytes.
1630 CGI.pm will attempt to read the entire POST into a variable, growing
1631 hugely in size until it runs out of memory. While the script attempts
1632 to allocate the memory the system may slow down dramatically. This is a
1633 form of denial of service attack.
1634 Another possible attack is for the remote user to force CGI.pm to
1636 accept a huge file upload. CGI.pm will accept the upload and store it
1637 in a temporary directory even if your script doesn't expect to receive
1638 an uploaded file. CGI.pm will delete the file automatically when it
1639 terminates, but in the meantime the remote user may have filled up the
1640 server's disk space, causing problems for other programs.
1641 The best way to avoid denial of service attacks is to limit the amount
1643 of memory, CPU time and disk space that CGI scripts can use. Some Web
1644 servers come with built-in facilities to accomplish this. In other
1645 cases, you can use the shell limit or ulimit commands to put ceilings
1646 on CGI resource usage.
1647 CGI.pm also has some simple built-in protections against denial of
1649 service attacks, but you must activate them before you can use them.
1650 These take the form of two global variables in the CGI name space:
1651 $CGI::POST_MAX
1653 If set to a non-negative integer, this variable puts a ceiling on
1654 the size of POSTings, in bytes. If CGI.pm detects a POST that is
1655 greater than the ceiling, it will immediately exit with an error
1656 message. This value will affect both ordinary POSTs and multipart
1657 POSTs, meaning that it limits the maximum size of file uploads as
1658 well. You should set this to a reasonably high value, such as 10
1659 megabytes.
1660 $CGI::DISABLE_UPLOADS
1662 If set to a non-zero value, this will disable file uploads
1663 completely. Other fill-out form values will work as usual.
1664 To use these variables, set the variable at the top of the script,
1666 right after the "use" statement:
1667 #!/usr/bin/env perl
1669 use strict;
1671 use warnings;
1672 use CGI;
1674 $CGI::POST_MAX = 1024 * 1024 * 10; # max 10MB posts
1676 $CGI::DISABLE_UPLOADS = 1; # no uploads
1677 An attempt to send a POST larger than $POST_MAX bytes will cause
1679 param() to return an empty CGI parameter list. You can test for this
1680 event by checking cgi_error(), either after you create the CGI object
1681 or, if you are using the function-oriented interface, call <param()>
1682 for the first time. If the POST was intercepted, then cgi_error() will
1683 return the message "413 POST too large".
1684 This error message is actually defined by the HTTP protocol, and is
1686 designed to be returned to the browser as the CGI script's status code.
1687 For example:
1688 my $uploaded_file = $q->param('upload');
1690 if ( !$uploaded_file && $q->cgi_error() ) {
1691 print $q->header( -status => $q->cgi_error() );
1692 exit 0;
1693 }
1694 However it isn't clear that any browser currently knows what to do with
1696 this status code. It might be better just to create a page that warns
1697 the user of the problem.
1698
1700 There are a number of global module flags which affect how CGI.pm
1701 operates.
1702 $CGI::APPEND_QUERY_STRING
1704 If set to a non-zero value, this will add query string parameters
1705 to a POST forms parameters hence allowing param() to return values
1706 from the query string as well as from the decoded POST request
1707 instead of having to use url_param instead. This makes it easier to
1708 get the value of a parameter when you don't know the source.
1709
1711 To make it easier to port existing programs that use cgi-lib.pl the
1712 compatibility routine "ReadParse" is provided. Porting is simple:
1713 OLD VERSION
1715 require "cgi-lib.pl";
1717 &ReadParse;
1718 print "The value of the antique is $in{antique}.\n";
1719 NEW VERSION
1721 use CGI;
1723 CGI::ReadParse();
1724 print "The value of the antique is $in{antique}.\n";
1725 CGI.pm's ReadParse() routine creates a tied variable named %in, which
1727 can be accessed to obtain the query variables. Like ReadParse, you can
1728 also provide your own variable. Infrequently used features of
1729 ReadParse, such as the creation of @in and $in variables, are not
1730 supported.
1731 Once you use ReadParse, you can retrieve the query object itself this
1733 way:
1734 my $q = $in{CGI};
1736 This allows you to start using the more interesting features of CGI.pm
1738 without rewriting your old scripts from scratch.
1739 An even simpler way to mix cgi-lib calls with CGI.pm calls is to import
1741 both the ":cgi-lib" and ":standard" method:
1742 use CGI qw(:cgi-lib :standard);
1744 &ReadParse;
1745 print "The price of your purchase is $in{price}.\n";
1746 print textfield(-name=>'price', -default=>'$1.99');
1747 Cgi-lib functions that are available in CGI.pm
1749 In compatibility mode, the following cgi-lib.pl functions are available
1750 for your use:
1751 ReadParse()
1753 PrintHeader()
1754 SplitParam()
1755 MethGet()
1756 MethPost()
1757
1759 The CGI.pm distribution is copyright 1995-2007, Lincoln D. Stein. It is
1760 distributed under the Artistic License 2.0. It is currently maintained
1761 by Lee Johnson (LEEJO) with help from many contributors.
1762
1764 Thanks very much to:
1765 Mark Stosberg (mark@stosberg.com)
1767 Matt Heffron (heffron@falstaff.css.beckman.com)
1768 James Taylor (james.taylor@srs.gov)
1769 Scott Anguish (sanguish@digifix.com)
1770 Mike Jewell (mlj3u@virginia.edu)
1771 Timothy Shimmin (tes@kbs.citri.edu.au)
1772 Joergen Haegg (jh@axis.se)
1773 Laurent Delfosse (delfosse@delfosse.com)
1774 Richard Resnick (applepi1@aol.com)
1775 Craig Bishop (csb@barwonwater.vic.gov.au)
1776 Tony Curtis (tc@vcpc.univie.ac.at)
1777 Tim Bunce (Tim.Bunce@ig.co.uk)
1778 Tom Christiansen (tchrist@convex.com)
1779 Andreas Koenig (k@franz.ww.TU-Berlin.DE)
1780 Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)
1781 Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)
1782 Stephen Dahmen (joyfire@inxpress.net)
1783 Ed Jordan (ed@fidalgo.net)
1784 David Alan Pisoni (david@cnation.com)
1785 Doug MacEachern (dougm@opengroup.org)
1786 Robin Houston (robin@oneworld.org)
1787 ...and many many more...
1788 for suggestions and bug fixes.
1789
1791 Address bug reports and comments to:
1792 <https://github.com/leejo/CGI.pm/issues>
1793 See the <https://github.com/leejo/CGI.pm/blob/master/CONTRIBUTING.md>
1795 file for information on raising issues and contributing
1796 The original bug tracker can be found at:
1798 <https://rt.cpan.org/Public/Dist/Display.html?Queue=CGI.pm>
1799
1801 CGI::Carp - provides Carp implementation tailored to the CGI
1802 environment.
1803 CGI::Fast - supports running CGI applications under FastCGI
1805perl v5.36.1 2023-05-04 CGI(3)