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 format of headers. The information
993 usually includes the MIME content type. To retrieve this information,
994 call 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 If you are using a machine that recognizes "text" and "binary" data
1011 modes, be sure to understand when and how to use them (see the Camel
1012 book). Otherwise you may find that binary files are corrupted during
1013 file uploads.
1014 Accessing the temp files directly
1016 When processing an uploaded file, CGI.pm creates a temporary file on
1018 your hard disk and passes you a file handle to that file. After you are
1019 finished with the file handle, CGI.pm unlinks (deletes) the temporary
1020 file. If you need to you can access the temporary file directly. You
1021 can access the temp file for a file upload by passing the file name to
1022 the tmpFileName() method:
1023 my $filehandle = $q->upload( 'uploaded_file' );
1025 my $tmpfilename = $q->tmpFileName( $filehandle );
1026 As with ->uploadInfo, using the reference returned by ->upload or
1028 ->param is preferred, although unlike ->uploadInfo, plain filenames
1029 also work if possible for backwards compatibility.
1030 The temporary file will be deleted automatically when your program
1032 exits unless you manually rename it or set $CGI::UNLINK_TMP_FILES to 0.
1033 On some operating systems (such as Windows NT), you will need to close
1034 the temporary file's filehandle before your program exits. Otherwise
1035 the attempt to delete the temporary file will fail.
1036 Changes in temporary file handling (v4.05+)
1038 CGI.pm had its temporary file handling significantly refactored, this
1040 logic is now all deferred to File::Temp (which is wrapped in a
1041 compatibility object, CGI::File::Temp - DO NOT USE THIS PACKAGE
1042 DIRECTLY). As a consequence the PRIVATE_TEMPFILES variable has been
1043 removed along with deprecation of the private_tempfiles routine and
1044 complete removal of the CGITempFile package. The
1045 $CGITempFile::TMPDIRECTORY is no longer used to set the temp directory,
1046 refer to the perldoc for File::Temp if you want to override the default
1047 settings in that package (the TMPDIR env variable is still available on
1048 some platforms). For Windows platforms the temporary directory order
1049 remains as before: TEMP > TMP > WINDIR ( > TMPDIR ) so if you have any
1050 of these in use in existing scripts they should still work.
1051 The Fh package still exists but does nothing, the CGI::File::Temp class
1053 is a subclass of both File::Temp and the empty Fh package, so if you
1054 have any code that checks that the filehandle isa Fh this should still
1055 work.
1056 When you get the internal file handle you will receive a File::Temp
1058 object, this should be transparent as File::Temp isa IO::Handle and isa
1059 IO::Seekable meaning it behaves as previously. If you are doing
1060 anything out of the ordinary with regards to temp files you should test
1061 your code before deploying this update and refer to the File::Temp
1062 documentation for more information.
1063 Handling interrupted file uploads
1065 There are occasionally problems involving parsing the uploaded file.
1067 This usually happens when the user presses "Stop" before the upload is
1068 finished. In this case, CGI.pm will return undef for the name of the
1069 uploaded file and set cgi_error() to the string "400 Bad request
1070 (malformed multipart POST)". This error message is designed so that you
1071 can incorporate it into a status code to be sent to the browser.
1072 Example:
1073 my $file = $q->upload( 'uploaded_file' );
1075 if ( !$file && $q->cgi_error ) {
1076 print $q->header( -status => $q->cgi_error );
1077 exit 0;
1078 }
1079 Progress bars for file uploads and avoiding temp files
1081 CGI.pm gives you low-level access to file upload management through a
1083 file upload hook. You can use this feature to completely turn off the
1084 temp file storage of file uploads, or potentially write your own file
1085 upload progress meter.
1086 This is much like the UPLOAD_HOOK facility available in
1088 Apache::Request, with the exception that the first argument to the
1089 callback is an Apache::Upload object, here it's the remote filename.
1090 my $q = CGI->new( \&hook [,$data [,$use_tempfile]] );
1092 sub hook {
1094 my ( $filename, $buffer, $bytes_read, $data ) = @_;
1095 print "Read $bytes_read bytes of $filename\n";
1096 }
1097 The $data field is optional; it lets you pass configuration information
1099 (e.g. a database handle) to your hook callback.
1100 The $use_tempfile field is a flag that lets you turn on and off
1102 CGI.pm's use of a temporary disk-based file during file upload. If you
1103 set this to a FALSE value (default true) then
1104 $q->param('uploaded_file') will no longer work, and the only way to get
1105 at the uploaded data is via the hook you provide.
1106 If using the function-oriented interface, call the CGI::upload_hook()
1108 method before calling param() or any other CGI functions:
1109 CGI::upload_hook( \&hook [,$data [,$use_tempfile]] );
1111 This method is not exported by default. You will have to import it
1113 explicitly if you wish to use it without the CGI:: prefix.
1114 Troubleshooting file uploads on Windows
1116 If you are using CGI.pm on a Windows platform and find that binary
1118 files get slightly larger when uploaded but that text files remain the
1119 same, then you have forgotten to activate binary mode on the output
1120 filehandle. Be sure to call binmode() on any handle that you create to
1121 write the uploaded file to disk.
1122 Older ways to process file uploads
1124 This section is here for completeness. if you are building a new
1126 application with CGI.pm, you can skip it.
1127 The original way to process file uploads with CGI.pm was to use
1129 param(). The value it returns has a dual nature as both a file name and
1130 a lightweight filehandle. This dual nature is problematic if you
1131 following the recommended practice of having "use strict" in your code.
1132 perl will complain when you try to use a string as a filehandle. More
1133 seriously, it is possible for the remote user to type garbage into the
1134 upload field, in which case what you get from param() is not a
1135 filehandle at all, but a string.
1136 To solve this problem the upload() method was added, which always
1138 returns a lightweight filehandle. This generally works well, but will
1139 have trouble interoperating with some other modules because the file
1140 handle is not derived from IO::File. So that brings us to current
1141 recommendation given above, which is to call the handle() method on the
1142 file handle returned by upload(). That upgrades the handle to an
1143 IO::File. It's a big win for compatibility for a small penalty of
1144 loading IO::File the first time you call it.
1145
1147 CGI.pm has several methods that support cookies.
1148 A cookie is a name=value pair much like the named parameters in a CGI
1150 query string. CGI scripts create one or more cookies and send them to
1151 the browser in the HTTP header. The browser maintains a list of cookies
1152 that belong to a particular Web server, and returns them to the CGI
1153 script during subsequent interactions.
1154 In addition to the required name=value pair, each cookie has several
1156 optional attributes:
1157 1. an expiration time
1159 This is a time/date string (in a special GMT format) that indicates
1160 when a cookie expires. The cookie will be saved and returned to
1161 your script until this expiration date is reached if the user exits
1162 the browser and restarts it. If an expiration date isn't specified,
1163 the cookie will remain active until the user quits the browser.
1164 2. a domain
1166 This is a partial or complete domain name for which the cookie is
1167 valid. The browser will return the cookie to any host that matches
1168 the partial domain name. For example, if you specify a domain name
1169 of ".capricorn.com", then the browser will return the cookie to Web
1170 servers running on any of the machines "www.capricorn.com",
1171 "www2.capricorn.com", "feckless.capricorn.com", etc. Domain names
1172 must contain at least two periods to prevent attempts to match on
1173 top level domains like ".edu". If no domain is specified, then the
1174 browser will only return the cookie to servers on the host the
1175 cookie originated from.
1176 3. a path
1178 If you provide a cookie path attribute, the browser will check it
1179 against your script's URL before returning the cookie. For example,
1180 if you specify the path "/cgi-bin", then the cookie will be
1181 returned to each of the scripts "/cgi-bin/tally.pl",
1182 "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl",
1183 but not to the script "/cgi-private/site_admin.pl". By default,
1184 path is set to "/", which causes the cookie to be sent to any CGI
1185 script on your site.
1186 4. a "secure" flag
1188 If the "secure" attribute is set, the cookie will only be sent to
1189 your script if the CGI request is occurring on a secure channel,
1190 such as SSL.
1191 The interface to HTTP cookies is the cookie() method:
1193 my $cookie = $q->cookie(
1195 -name => 'sessionID',
1196 -value => 'xyzzy',
1197 -expires => '+1h',
1198 -path => '/cgi-bin/database',
1199 -domain => '.capricorn.org',
1200 -secure => 1
1201 );
1202 print $q->header( -cookie => $cookie );
1204 cookie() creates a new cookie. Its parameters include:
1206 -name
1208 The name of the cookie (required). This can be any string at all.
1209 Although browsers limit their cookie names to non-whitespace
1210 alphanumeric characters, CGI.pm removes this restriction by
1211 escaping and unescaping cookies behind the scenes.
1212 -value
1214 The value of the cookie. This can be any scalar value, array
1215 reference, or even hash reference. For example, you can store an
1216 entire hash into a cookie this way:
1217 my $cookie = $q->cookie(
1219 -name => 'family information',
1220 -value => \%childrens_ages
1221 );
1222 -path
1224 The optional partial path for which this cookie will be valid, as
1225 described above.
1226 -domain
1228 The optional partial domain for which this cookie will be valid, as
1229 described above.
1230 -expires
1232 The optional expiration date for this cookie. The format is as
1233 described in the section on the header() method:
1234 "+1h" one hour from now
1236 -secure
1238 If set to true, this cookie will only be used within a secure SSL
1239 session.
1240 The cookie created by cookie() must be incorporated into the HTTP
1242 header within the string returned by the header() method:
1243 use strict;
1245 use warnings;
1246 use CGI;
1248 my $q = CGI->new;
1250 my $cookie = ...
1251 print $q->header( -cookie => $cookie );
1252 To create multiple cookies, give header() an array reference:
1254 my $cookie1 = $q->cookie(
1256 -name => 'riddle_name',
1257 -value => "The Sphynx's Question"
1258 );
1259 my $cookie2 = $q->cookie(
1261 -name => 'answers',
1262 -value => \%answers
1263 );
1264 print $q->header( -cookie => [ $cookie1,$cookie2 ] );
1266 To retrieve a cookie, request it by name by calling cookie() method
1268 without the -value parameter. This example uses the object-oriented
1269 form:
1270 my $riddle = $q->cookie('riddle_name');
1272 my %answers = $q->cookie('answers');
1273 Cookies created with a single scalar value, such as the "riddle_name"
1275 cookie, will be returned in that form. Cookies with array and hash
1276 values can also be retrieved.
1277 The cookie and CGI namespaces are separate. If you have a parameter
1279 named 'answers' and a cookie named 'answers', the values retrieved by
1280 param() and cookie() are independent of each other. However, it's
1281 simple to turn a CGI parameter into a cookie, and vice-versa:
1282 # turn a CGI parameter into a cookie
1284 my $c = cookie( -name => 'answers',-value => [$q->param('answers')] );
1285 # vice-versa
1286 $q->param( -name => 'answers',-value => [ $q->cookie('answers')] );
1287 If you call cookie() without any parameters, it will return a list of
1289 the names of all cookies passed to your script:
1290 my @cookies = $q->cookie();
1292 See the cookie.cgi example script for some ideas on how to use cookies
1294 effectively.
1295 $CGI::COOKIE_CACHE
1297 If set to a non-negative integer, this variable will cause CGI.pm
1298 to use the cached cookie details from the previous call to
1299 cookie(). By default this cache is off to retain backwards
1300 compatibility.
1301
1303 If you are running the script from the command line or in the perl
1304 debugger, you can pass the script a list of keywords or parameter=value
1305 pairs on the command line or from standard input (you don't have to
1306 worry about tricking your script into reading from environment
1307 variables). You can pass keywords like this:
1308 your_script.pl keyword1 keyword2 keyword3
1310 or this:
1312 your_script.pl keyword1+keyword2+keyword3
1314 or this:
1316 your_script.pl name1=value1 name2=value2
1318 or this:
1320 your_script.pl name1=value1&name2=value2
1322 To turn off this feature, use the -no_debug pragma.
1324 To test the POST method, you may enable full debugging with the -debug
1326 pragma. This will allow you to feed newline-delimited name=value pairs
1327 to the script on standard input.
1328 When debugging, you can use quotes and backslashes to escape characters
1330 in the familiar shell manner, letting you place spaces and other funny
1331 characters in your parameter=value pairs:
1332 your_script.pl "name1='I am a long value'" "name2=two\ words"
1334 Finally, you can set the path info for the script by prefixing the
1336 first name/value parameter with the path followed by a question mark
1337 (?):
1338 your_script.pl /your/path/here?name1=value1&name2=value2
1340
1342 Some of the more useful environment variables can be fetched through
1343 this interface. The methods are as follows:
1344 Accept()
1346 Return a list of MIME types that the remote browser accepts. If you
1347 give this method a single argument corresponding to a MIME type, as
1348 in Accept('text/html'), it will return a floating point value
1349 corresponding to the browser's preference for this type from 0.0
1350 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's
1351 accept list are handled correctly.
1352 Note that the capitalization changed between version 2.43 and 2.44
1354 in order to avoid conflict with perl's accept() function.
1355 raw_cookie()
1357 Returns the HTTP_COOKIE variable. Cookies have a special format,
1358 and this method call just returns the raw form (?cookie dough). See
1359 cookie() for ways of setting and retrieving cooked cookies.
1360 Called with no parameters, raw_cookie() returns the packed cookie
1362 structure. You can separate it into individual cookies by
1363 splitting on the character sequence "; ". Called with the name of a
1364 cookie, retrieves the unescaped form of the cookie. You can use the
1365 regular cookie() method to get the names, or use the raw_fetch()
1366 method from the CGI::Cookie module.
1367 env_query_string()
1369 Returns the QUERY_STRING variable, note that this is the original
1370 value as set in the environment by the webserver and (possibly) not
1371 the same value as returned by query_string(), which represents the
1372 object state
1373 user_agent()
1375 Returns the HTTP_USER_AGENT variable. If you give this method a
1376 single argument, it will attempt to pattern match on it, allowing
1377 you to do something like user_agent(Mozilla);
1378 path_info()
1380 Returns additional path information from the script URL. E.G.
1381 fetching /cgi-bin/your_script/additional/stuff will result in
1382 path_info() returning "/additional/stuff".
1383 NOTE: The Microsoft Internet Information Server is broken with
1385 respect to additional path information. If you use the perl DLL
1386 library, the IIS server will attempt to execute the additional path
1387 information as a perl script. If you use the ordinary file
1388 associations mapping, the path information will be present in the
1389 environment, but incorrect. The best thing to do is to avoid using
1390 additional path information in CGI scripts destined for use with
1391 IIS. A best attempt has been made to make CGI.pm do the right
1392 thing.
1393 path_translated()
1395 As per path_info() but returns the additional path information
1396 translated into a physical path, e.g.
1397 "/usr/local/etc/httpd/htdocs/additional/stuff".
1398 The Microsoft IIS is broken with respect to the translated path as
1400 well.
1401 remote_host()
1403 Returns either the remote host name or IP address if the former is
1404 unavailable.
1405 remote_ident()
1407 Returns the name of the remote user (as returned by identd) or
1408 undef if not set
1409 remote_addr()
1411 Returns the remote host IP address, or 127.0.0.1 if the address is
1412 unavailable.
1413 request_uri()
1415 Returns the interpreted pathname of the requested document or CGI
1416 (relative to the document root). Or undef if not set.
1417 script_name()
1419 Return the script name as a partial URL, for self-referring
1420 scripts.
1421 referer()
1423 Return the URL of the page the browser was viewing prior to
1424 fetching your script.
1425 auth_type()
1427 Return the authorization/verification method in use for this
1428 script, if any.
1429 server_name()
1431 Returns the name of the server, usually the machine's host name.
1432 virtual_host()
1434 When using virtual hosts, returns the name of the host that the
1435 browser attempted to contact
1436 server_port()
1438 Return the port that the server is listening on.
1439 server_protocol()
1441 Returns the protocol and revision of the incoming request, or
1442 defaults to HTTP/1.0 if this is not set
1443 virtual_port()
1445 Like server_port() except that it takes virtual hosts into account.
1446 Use this when running with virtual hosts.
1447 server_software()
1449 Returns the server software and version number.
1450 remote_user()
1452 Return the authorization/verification name used for user
1453 verification, if this script is protected.
1454 user_name()
1456 Attempt to obtain the remote user's name, using a variety of
1457 different techniques. May not work in all browsers.
1458 request_method()
1460 Returns the method used to access your script, usually one of
1461 'POST', 'GET' or 'HEAD'. If running from the command line it will
1462 be undef.
1463 content_type()
1465 Returns the content_type of data submitted in a POST, generally
1466 multipart/form-data or application/x-www-form-urlencoded
1467 http()
1469 Called with no arguments returns the list of HTTP environment
1470 variables, including such things as HTTP_USER_AGENT,
1471 HTTP_ACCEPT_LANGUAGE, and HTTP_ACCEPT_CHARSET, corresponding to the
1472 like-named HTTP header fields in the request. Called with the name
1473 of an HTTP header field, returns its value. Capitalization and the
1474 use of hyphens versus underscores are not significant.
1475 For example, all three of these examples are equivalent:
1477 my $requested_language = $q->http('Accept-language');
1479 my $requested_language = $q->http('Accept_language');
1481 my $requested_language = $q->http('HTTP_ACCEPT_LANGUAGE');
1483 https()
1485 The same as http(), but operates on the HTTPS environment variables
1486 present when the SSL protocol is in effect. Can be used to
1487 determine whether SSL is turned on.
1488
1490 NPH, or "no-parsed-header", scripts bypass the server completely by
1491 sending the complete HTTP header directly to the browser. This has
1492 slight performance benefits, but is of most use for taking advantage of
1493 HTTP extensions that are not directly supported by your server, such as
1494 server push and PICS headers.
1495 Servers use a variety of conventions for designating CGI scripts as
1497 NPH. Many Unix servers look at the beginning of the script's name for
1498 the prefix "nph-". The Macintosh WebSTAR server and Microsoft's
1499 Internet Information Server, in contrast, try to decide whether a
1500 program is an NPH script by examining the first line of script output.
1501 CGI.pm supports NPH scripts with a special NPH mode. When in this mode,
1503 CGI.pm will output the necessary extra header information when the
1504 header() and redirect() methods are called.
1505 The Microsoft Internet Information Server requires NPH mode. As of
1507 version 2.30, CGI.pm will automatically detect when the script is
1508 running under IIS and put itself into this mode. You do not need to do
1509 this manually, although it won't hurt anything if you do.
1510 In the use statement
1512 Simply add the "-nph" pragma to the list of symbols to be imported
1513 into your script:
1514 use CGI qw(:standard -nph)
1516 By calling the nph() method:
1518 Call nph() with a non-zero parameter at any point after using
1519 CGI.pm in your program.
1520 CGI->nph(1)
1522 By using -nph parameters
1524 in the header() and redirect() statements:
1525 print header(-nph=>1);
1527
1529 CGI.pm provides four simple functions for producing multipart documents
1530 of the type needed to implement server push. These functions were
1531 graciously provided by Ed Jordan <ed@fidalgo.net>. To import these into
1532 your namespace, you must import the ":push" set. You are also advised
1533 to put the script into NPH mode and to set $| to 1 to avoid buffering
1534 problems.
1535 Here is a simple script that demonstrates server push:
1537 #!/usr/bin/env perl
1539 use strict;
1541 use warnings;
1542 use CGI qw/:push -nph/;
1544 $| = 1;
1546 print multipart_init( -boundary=>'----here we go!' );
1547 for (0 .. 4) {
1548 print multipart_start( -type=>'text/plain' ),
1549 "The current time is ",scalar( localtime ),"\n";
1550 if ($_ < 4) {
1551 print multipart_end();
1552 } else {
1553 print multipart_final();
1554 }
1555 sleep 1;
1556 }
1557 This script initializes server push by calling multipart_init(). It
1559 then enters a loop in which it begins a new multipart section by
1560 calling multipart_start(), prints the current local time, and ends a
1561 multipart section with multipart_end(). It then sleeps a second, and
1562 begins again. On the final iteration, it ends the multipart section
1563 with multipart_final() rather than with multipart_end().
1564 multipart_init()
1566 multipart_init( -boundary => $boundary, -charset => $charset );
1567 Initialize the multipart system. The -boundary argument specifies
1569 what MIME boundary string to use to separate parts of the document.
1570 If not provided, CGI.pm chooses a reasonable boundary for you.
1571 The -charset provides the character set, if not provided this will
1573 default to ISO-8859-1
1574 multipart_start()
1576 multipart_start( -type => $type, -charset => $charset );
1577 Start a new part of the multipart document using the specified MIME
1579 type and charset. If not specified, text/html ISO-8859-1 is
1580 assumed.
1581 multipart_end()
1583 multipart_end()
1584 End a part. You must remember to call multipart_end() once for each
1586 multipart_start(), except at the end of the last part of the
1587 multipart document when multipart_final() should be called instead
1588 of multipart_end().
1589 multipart_final()
1591 multipart_final()
1592 End all parts. You should call multipart_final() rather than
1594 multipart_end() at the end of the last part of the multipart
1595 document.
1596 Users interested in server push applications should also have a look at
1598 the CGI::Push module.
1599
1601 A potential problem with CGI.pm is that, by default, it attempts to
1602 process form POSTings no matter how large they are. A wily hacker could
1603 attack your site by sending a CGI script a huge POST of many gigabytes.
1604 CGI.pm will attempt to read the entire POST into a variable, growing
1605 hugely in size until it runs out of memory. While the script attempts
1606 to allocate the memory the system may slow down dramatically. This is a
1607 form of denial of service attack.
1608 Another possible attack is for the remote user to force CGI.pm to
1610 accept a huge file upload. CGI.pm will accept the upload and store it
1611 in a temporary directory even if your script doesn't expect to receive
1612 an uploaded file. CGI.pm will delete the file automatically when it
1613 terminates, but in the meantime the remote user may have filled up the
1614 server's disk space, causing problems for other programs.
1615 The best way to avoid denial of service attacks is to limit the amount
1617 of memory, CPU time and disk space that CGI scripts can use. Some Web
1618 servers come with built-in facilities to accomplish this. In other
1619 cases, you can use the shell limit or ulimit commands to put ceilings
1620 on CGI resource usage.
1621 CGI.pm also has some simple built-in protections against denial of
1623 service attacks, but you must activate them before you can use them.
1624 These take the form of two global variables in the CGI name space:
1625 $CGI::POST_MAX
1627 If set to a non-negative integer, this variable puts a ceiling on
1628 the size of POSTings, in bytes. If CGI.pm detects a POST that is
1629 greater than the ceiling, it will immediately exit with an error
1630 message. This value will affect both ordinary POSTs and multipart
1631 POSTs, meaning that it limits the maximum size of file uploads as
1632 well. You should set this to a reasonably high value, such as 10
1633 megabytes.
1634 $CGI::DISABLE_UPLOADS
1636 If set to a non-zero value, this will disable file uploads
1637 completely. Other fill-out form values will work as usual.
1638 To use these variables, set the variable at the top of the script,
1640 right after the "use" statement:
1641 #!/usr/bin/env perl
1643 use strict;
1645 use warnings;
1646 use CGI;
1648 $CGI::POST_MAX = 1024 * 1024 * 10; # max 10MB posts
1650 $CGI::DISABLE_UPLOADS = 1; # no uploads
1651 An attempt to send a POST larger than $POST_MAX bytes will cause
1653 param() to return an empty CGI parameter list. You can test for this
1654 event by checking cgi_error(), either after you create the CGI object
1655 or, if you are using the function-oriented interface, call <param()>
1656 for the first time. If the POST was intercepted, then cgi_error() will
1657 return the message "413 POST too large".
1658 This error message is actually defined by the HTTP protocol, and is
1660 designed to be returned to the browser as the CGI script's status code.
1661 For example:
1662 my $uploaded_file = $q->param('upload');
1664 if ( !$uploaded_file && $q->cgi_error() ) {
1665 print $q->header( -status => $q->cgi_error() );
1666 exit 0;
1667 }
1668 However it isn't clear that any browser currently knows what to do with
1670 this status code. It might be better just to create a page that warns
1671 the user of the problem.
1672
1674 There are a number of global module flags which affect how CGI.pm
1675 operates.
1676 $CGI::APPEND_QUERY_STRING
1678 If set to a non-zero value, this will add query string parameters
1679 to a POST forms parameters hence allowing param() to return values
1680 from the query string as well as from the decoded POST request
1681 instead of having to use url_param instead. This makes it easier to
1682 get the value of a parameter when you don't know the source.
1683
1685 To make it easier to port existing programs that use cgi-lib.pl the
1686 compatibility routine "ReadParse" is provided. Porting is simple:
1687 OLD VERSION
1689 require "cgi-lib.pl";
1691 &ReadParse;
1692 print "The value of the antique is $in{antique}.\n";
1693 NEW VERSION
1695 use CGI;
1697 CGI::ReadParse();
1698 print "The value of the antique is $in{antique}.\n";
1699 CGI.pm's ReadParse() routine creates a tied variable named %in, which
1701 can be accessed to obtain the query variables. Like ReadParse, you can
1702 also provide your own variable. Infrequently used features of
1703 ReadParse, such as the creation of @in and $in variables, are not
1704 supported.
1705 Once you use ReadParse, you can retrieve the query object itself this
1707 way:
1708 my $q = $in{CGI};
1710 This allows you to start using the more interesting features of CGI.pm
1712 without rewriting your old scripts from scratch.
1713 An even simpler way to mix cgi-lib calls with CGI.pm calls is to import
1715 both the ":cgi-lib" and ":standard" method:
1716 use CGI qw(:cgi-lib :standard);
1718 &ReadParse;
1719 print "The price of your purchase is $in{price}.\n";
1720 print textfield(-name=>'price', -default=>'$1.99');
1721 Cgi-lib functions that are available in CGI.pm
1723 In compatibility mode, the following cgi-lib.pl functions are available
1724 for your use:
1725 ReadParse()
1727 PrintHeader()
1728 SplitParam()
1729 MethGet()
1730 MethPost()
1731
1733 The CGI.pm distribution is copyright 1995-2007, Lincoln D. Stein. It is
1734 distributed under the Artistic License 2.0. It is currently maintained
1735 by Lee Johnson (LEEJO) with help from many contributors.
1736
1738 Thanks very much to:
1739 Mark Stosberg (mark@stosberg.com)
1741 Matt Heffron (heffron@falstaff.css.beckman.com)
1742 James Taylor (james.taylor@srs.gov)
1743 Scott Anguish (sanguish@digifix.com)
1744 Mike Jewell (mlj3u@virginia.edu)
1745 Timothy Shimmin (tes@kbs.citri.edu.au)
1746 Joergen Haegg (jh@axis.se)
1747 Laurent Delfosse (delfosse@delfosse.com)
1748 Richard Resnick (applepi1@aol.com)
1749 Craig Bishop (csb@barwonwater.vic.gov.au)
1750 Tony Curtis (tc@vcpc.univie.ac.at)
1751 Tim Bunce (Tim.Bunce@ig.co.uk)
1752 Tom Christiansen (tchrist@convex.com)
1753 Andreas Koenig (k@franz.ww.TU-Berlin.DE)
1754 Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)
1755 Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)
1756 Stephen Dahmen (joyfire@inxpress.net)
1757 Ed Jordan (ed@fidalgo.net)
1758 David Alan Pisoni (david@cnation.com)
1759 Doug MacEachern (dougm@opengroup.org)
1760 Robin Houston (robin@oneworld.org)
1761 ...and many many more...
1762 for suggestions and bug fixes.
1763
1765 Address bug reports and comments to:
1766 <https://github.com/leejo/CGI.pm/issues>
1767 See the <https://github.com/leejo/CGI.pm/blob/master/CONTRIBUTING.md>
1769 file for information on raising issues and contributing
1770 The original bug tracker can be found at:
1772 <https://rt.cpan.org/Public/Dist/Display.html?Queue=CGI.pm>
1773
1775 CGI::Carp - provides Carp implementation tailored to the CGI
1776 environment.
1777 CGI::Fast - supports running CGI applications under FastCGI
1779perl v5.36.0 2022-07-22 CGI(3)