CGI.pm - a Perl5 CGI Library

Abstract

Everything is done through a ``CGI'' object. When you create one of these objects it examines the environment for a query string, parses it, and stores the results. You can then ask the CGI object to return or modify the query values. CGI objects handle POST and GET methods correctly, and correctly distinguish between scripts called from <ISINDEX> documents and form-based documents. In fact you can debug your script from the command line without worrying about setting up environment variables.

A script to create a fill-out form that remembers its state each time it's invoked is very easy to write with CGI.pm:

use CGI;
$query = new CGI;
print $query->header;

print $query->startform;
print "What's your name? ",$query->textfield('name');

print "<P>What's the combination? ",
        $query->checkbox_group(-name=>'words',
                               -values=>['eenie','meenie','minie','moe']);

print "<P>What's your favorite color? ",
        $query->popup_menu(-name=>'color',
                           -values=>['red','green','blue','chartreuse']);

print "<P>",$query->submit;
print $query->endform;

print "<HR>\n";
if ($query->param) {
    print "Your name is <EM>",$query->param('name'),"</EM>\n";
    print "<P>The keywords are: <EM>",join(", ",$query->param('words')),"</EM>\n";
    print "<P>Your favorite color is <EM>",$query->param('color'),"</EM>\n";
}

To use this package, install it in your perl library path. On most systems this will be /usr/local/lib/perl5, but check with the administrator of your system to be sure.

Thanks to Andreas Koenig and his MakeMaker program, CGI.pm can now install itself in the right place if you're using a Unix system. Move to the directory containing CGI.pm and type the following commands:

   % perl Makefile.PL
   % make
   % make install

To use CGI.pm in your scripts, place the following statement at the top of your perl CGI programs:

use CGI;

BEGIN {
     unshift@INC,'/usr/local/etc/httpd/cgi-bin');
}
use CGI;

Notes on using CGI.pm on non-Unix platforms

    $query = new CGI

An alternative form of the new() method allows you to read the contents of the form from a previously-opened file handle:

    $query = new CGI(FILEHANDLE)

    @keywords = $query->keywords

    @names = $query->param

   @values = $query->param('foo');
             -or-
   $value = $query->param('foo');

As of version 1.50 of this library, the array of parameter names returned will be in the same order in which the browser sent them. Although this is not guaranteed to be identical to the order in which the parameters were defined in the fill-out form, this is usually the case.

Setting The Value(s) Of A Named Parameter

   $query->param('foo','an','array','of','values');

   $query->delete('foo');

   $query->import_names('R');
   print "Your name is $R::name\n"
   print "Your favorite colors are @R::colors\n";

If you don't specify a name space, this method assumes namespace "Q".

Warning: do not import into namespace 'main'. This represents a major security risk, as evil people could then use this feature to redefine central variables such as @INC. CGI.pm will exit with an error if you try to do this.

Note: this method used to be called import() (and CGI.pm still recognizes this method call). However the official method name has been changed to import_names() for compatability with the CGI:: modules.

Table of contents

   $query->save(FILEHANDLE)

Saving the State in a Self-Referencing URL

   $my_url=$query->self_url

Table of contents

Calling CGI Functions that Take Multiple Arguments

   $field = $query->radio_group(-name=>'OS',
                                -values=>[Unix,Windows,Macintosh],
                                -default=>'Unix');

   $field = $query->textfield(-name=>'State',
                              -default=>'gaseous',
                              -justification=>'RIGHT');

   <INPUT TYPE="textfield" NAME="State" VALUE="gaseous"
          JUSTIFICATION="RIGHT">

   $query = new CGI;
   $query->use_named_parameters(1);
   $field = $query->radio_group('name'=>'OS',
                                'values'=>['Unix','Windows','Macintosh'],
                                'default'=>'Unix');

Table of contents

Creating the HTTP Header

Creating the Standard Header for a Virtual Document

   print $query->header('image/gif');

An extended form of this method allows you to specify a status code and a message to pass back to the browser:

   print $query->header(-type=>'image/gif',
                        -status=>'204 No Response');

You can add any number of HTTP headers, including ones that aren't implemented, using named parameters:

   print $query->header(-type=>'image/gif',
                        -status=>'402 Payment Required',
                        -Cost=>'$0.02');

   print $query->redirect('http://somewhere.else/in/the/world');

You can add your own headers to this as in the header() method.

Table of contents

Creating an HTML Header

   named parameter style
   print $query->start_html(-title=>'Secrets of the Pyramids',
                            -author=>'fred@capricorn.org',
                            -base=>'true',
                            -BGCOLOR=>"#00A0A0"');

   old style
   print $query->start_html('Secrets of the Pyramids',
                            'fred@capricorn.org','true',
                            'BGCOLOR="#00A0A0"')

• The title (-title)
• The author's e-mail address (will create a <LINK REV="MADE"> tag if present (-author)
• A true flag if you want to include a <BASE> tag in the header (-base). This helps resolve relative addresses to absolute ones when the document is moved, but makes the document hierarchy non-portable. Use with care!
• Any additional attributes you want to incorporate into the <BODY> tag (as many as you like). This is a good way to incorporate Netscape specific extensions, such as background color and wallpaper pattern. (The example above sets the page background to a vibrant blue.)

Ending an HTML Document

  print $query->end_html

Table of contents

General note 2. The default values that you specify for the forms are only used the first time the script is invoked. If there are already values present in the query string, they are used, even if blank. If you want to change the value of a field from its previous value, call the param() method to set it. If you want to reset the fields to their defaults, you can:

1. Create a special defaults button using the defaults() method.
2. Create a hypertext link that calls your script without any parameters.

     $query = new CGI;
     $query->autoEscape(undef);

Form Elements

   print $query->isindex($action);

   print $query->startform($method,$action,$encoding);
     ...various form stuff...
   print $query->endform;

The form encoding is a new feature introduced in version 1.57 in order to support the "file upload" feature of Netscape 2.0. The form encoding tells the browser how to package up the contents of the form in order to transmit it across the Internet. There are two types of encoding that you can specify:

application/x-www-form-urlencoded

This is the type of encoding used by all browsers prior to Netscape 2.0. It is compatible with many CGI scripts and is suitable for short fields containing text data. For your convenience, CGI.pm stores the name of this encoding type in $CGI::URL_ENCODED.

multipart/form-data

This is the newer type of encoding introduced by Netscape 2.0. It is suitable for forms that contain very large fields or that are intended for transferring binary data. Most importantly, it enables the "file upload" feature of Netscape 2.0 forms. For your convenience, CGI.pm stores the name of this encoding type in $CGI::MULTIPART

Forms that use this type of encoding are not easily interpreted by CGI scripts unless they use CGI.pm or another library that knows how to handle them. Unless you are using the file upload feature, there's no particular reason to use this type of encoding.

   print $query->start_multipart_form($method,$action,$encoding);
     ...various form stuff...
   print $query->endform;

  Named parameter style
  print $query->textfield(-name=>'field_name',
	                    -default=>'starting value',
	                    -size=>50,
	                    -maxlength=>80);

   Old style
  print $query->textfield('foo','starting value',50,80);

• The first parameter (-name) is the required name for the field.
• The optional second parameter (-default) is the starting value for the field contents.
• The optional third parameter (-size) is the size of the field in characters.
• The optional fourth parameter (-maxlength) is the maximum number of characters the field will accomodate.

      $value = $query->param('foo');

   Named parameter style
   print $query->textarea(-name=>'foo',
	 		  -default=>'starting value',
	                  -rows=>10,
	                  -columns=>50);

   Old style
   print $query->textarea('foo','starting value',10,50);

   Named parameter style
   print $query->password_field(-name=>'secret',
				-value=>'starting value',
				-size=>50,
				-maxlength=>80);

   Old style
   print $query->password_field('secret','starting value',50,80);

    Named parameters style
    print $query->filefield(-name=>'uploaded_file',
	                    -default=>'starting value',
	                    -size=>50,
	 		    -maxlength=>80);

    Old style
    print $query->filefield('uploaded_file','starting value',50,80);

• The first parameter (-name) is the required name for the field.
• The optional second parameter (-default) is the starting value for the file name. This field is currently ignored by Netscape 2.0 beta, but there's always hope!
• The optional third parameter (-size) is the size of the field in characters.
• The optional fourth parameter (-maxlength) is the maximum number of characters the field will accomodate.

In order to take full advantage of the file upload facility you must use the new multipart form encoding scheme. You can do this either by calling startform() and specify an encoding type of $CGI::MULTIPART or by using the new start_multipart_form() method. If you don't use multipart encoding, then you'll be able to retreive the name of the file selected by the remote user, but you won't be able to access its contents.

When the form is processed, you can retrieve the entered filename by calling param().

       $filename = $query->param('uploaded_file');

	/path/to/the/file

	C:\PATH\TO\THE\FILE.MSW

	HD 40:Desktop Folder:Sort Through:Reminders

The filename returned is also a file handle. You can read the contents of the file using standard Perl file reading calls:

	# Read a text file and print it out
	while (<$filename>) {
	   print;
        }

        # Copy a binary file to somewhere safe
        open (OUTFILE,">>/usr/local/web/users/feedback");
	while ($bytesread=read($filename,$buffer,1024)) {
	   print OUTFILE $buffer;
        }

Caveats and potential problems in the file upload feature.

Creating A Popup Menu

  Named parameter style
  print $query->popup_menu(-name=>'menu_name',
			    -values=>['eenie','meenie','minie'],
	                    -default=>'meenie',
	                    -labels=>{'eenie'=>'one','meenie'=>'two',
                                      'minie'=>'three'});
  
  Old style
  print $query->popup_menu('menu_name',
                              ['eenie','meenie','minie'],'meenie',
                              {'eenie'=>'one','meenie'=>'two','minie'=>'three'});

• The required first argument (-name) is the menu's name.
• The required second argument (-values) is an array reference containing the list of menu items in the menu. You can pass the method an anonymous array, as shown in the example, or a reference to a named array, such as \@foo
• The optional third parameter (-default) is the name of the default menu choice. If not specified, the first item will be the default. The value of the previous choice will be maintained across queries.
• The optional fourth parameter (-labels) allows you to pass a reference to an associative array containing user-visible labels for one or more of the menu items. You can use this when you want the user to see one menu string, but have the browser return your program a different one. If you don't specify this, the value string will be used instead ("eenie", "meenie" and "minie" in this example).

     $popup_menu_value = $query->param('menu_name');

   Named parameter style
   print $query->scrolling_list(-name=>'list_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -default=>['eenie','moe'],
	                        -size=>5,
	                        -multiple=>'true',
                                -labels=>\%labels);

   Old style
   print $query->scrolling_list('list_name',
                                ['eenie','meenie','minie','moe'],
                                ['eenie','moe'],5,'true',
                                \%labels);

• The first and second arguments (-name,-values)are the list name and values, respectively. As in the popup menu, the second argument should be an array reference.
• The optional third argument (-default)can be either a reference to a list containing the values to be selected by default, or can be a single value to select. If this argument is missing or undefined, then nothing is selected when the list first appears.
• The optional fourth argument (-size) is the display size of the list.
• The optional fifth argument (-multiple) can be set to true to allow multiple simultaneous selections.
• The option sixth argument (-labels) can be used to assign user-visible labels to the list items different from the ones used for the values as above. In this example we assume that an associative array %labels has already been created.

     @selected = $query->param('list_name');

   Named parameter style
   print $query->checkbox_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -default=>['eenie','moe'],
	                        -linebreak=>'true',
	                        -labels=>\%labels);

   Old Style
   print $query->checkbox_group('group_name',
                                ['eenie','meenie','minie','moe'],
                                ['eenie','moe'],'true',\%labels);

   HTML3 Browsers Only
   print $query->checkbox_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
                                -rows=>2,-columns=>2);

• The first and second arguments (-name and -values) are the checkbox name and values, respectively. As in the popup menu, the second argument should be an array reference. These values are used for the user-readable labels printed next to the checkboxes as well as for the values passed to your script in the query string.
• The optional third argument (-default) can be either a reference to a list containing the values to be checked by default, or can be a single value to checked. If this argument is missing or undefined, then nothing is selected when the list first appears.
• The optional fourth argument (-linebreak) can be set to true to place line breaks between the checkboxes so that they appear as a vertical list. Otherwise, they will be strung together on a horizontal line. When the form is procesed, all checked boxes will be returned as a list under the parameter name 'group_name'. The values of the "on" checkboxes can be retrieved with:
• The optional fifth argument (-labels) is a reference to an associative array of checkbox labels. This allows you to use different strings for the user-visible button labels and the values sent to your script. In this example we assume that an associative array %labels has previously been created.
• Browsers that understand HTML3 tables (such as Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters cause checkbox_group() to return an HTML3 compatible table containing the checkbox group formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; checkbox_group will calculate the correct number of rows for you.

  To include row and column headings in the returned table, you can use the -rowheader and -colheader parameters. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpetation of the checkboxes -- they're still a single named unit.

  When viewed with browsers that don't understand HTML3 tables, the -rows and -columns parameters will leave you with a group of buttons that may be awkwardly formatted but still useable. However, if you add row and/or column headings, the resulting text will be very hard to read.

     @turned_on = $query->param('group_name');

   Named parameter list
   print $query->checkbox(-name=>'checkbox_name',
			   -checked=>'checked',
		           -value=>'TURNED ON',
		           -label=>'Turn me on');

   Old style
   print $query->checkbox('checkbox_name',1,'TURNED ON','Turn me on');

• The first parameter (-nameis the required name for the checkbox. It will also be used for the user-readable label printed next to the checkbox.
• The optional second parameter (-checkedspecifies that the checkbox is turned on by default. Aliases for this parameter are -selected and -on.
• The optional third parameter (-valuespecifies the value of the checkbox when it is checked. If not provided, the word "on" is assumed.
• The optional fourth parameter (-labelassigns a user-visible label to the button. If not provided, the checkbox's name will be used.

     $turned_on = $query->param('checkbox_name');

   Named parameter style
   print $query->radio_group(-name=>'group_name',
			     -values=>['eenie','meenie','minie'],
                             -default=>'meenie',
			     -linebreak=>'true',
			     -labels=>\%labels);

   Old style
   print $query->radio_group('group_name',['eenie','meenie','minie'],
                                          'meenie','true',\%labels);

   HTML3-compatible browsers only
   print $query->radio_group(-name=>'group_name',
                                -values=>['eenie','meenie','minie','moe'],
	                        -rows=2,-columns=>2);

• The first argument (-nameis the name of the group and is required.
• The second argument (-valuesis the list of values for the radio buttons. The values and the labels that appear on the page are identical. Pass an array reference in the second argument, either using an anonymous array, as shown, or by referencing a named array as in \@foo.
• The optional third parameter (-defaultis the value of the default button to turn on. If not specified, the first item will be the default. Specify some nonexistent value, such as "-" if you don't want any button to be turned on.
• The optional fourth parameter (-linebreakcan be set to 'true' to put line breaks between the buttons, creating a vertical list.
• The optional fifth parameter (-labelsspecifies an associative array containing labels to be printed next to each the button. If not provided the button value will be used instead. This example assumes that the associative array %labels has already been defined.
• Browsers that understand HTML3 tables (such as Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters cause radio_group() to return an HTML3 compatible table containing the radio cluster formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; radio_group will calculate the correct number of rows for you.

  To include row and column headings in the returned table, you can use the -rowheader and -colheader parameters. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpetation of the radio buttons -- they're still a single named unit.

  When viewed with browsers that don't understand HTML3 tables, the -rows and -columns parameters will leave you with a group of buttons that may be awkwardly formatted but still useable. However, if you add row and/or column headings, the resulting text will be very hard to read.

       $which_radio_button = $query->param('group_name');

   Named parameter style
   print $query->submit(-name=>'button_name',
		        -value=>'value');

  Old style
  print $query->submit('button_name','value');

• The first argument (-nameis optional. You can give the button a name if you have several submission buttons in your form and you want to distinguish between them. The name will also be used as the user-visible label.
• The second argument (-valueis also optional. This gives the button a value that will be passed to your script in the query string. You can figure out which button was pressed by using different values for each one:

    $which_one = $query->param('button_name');

  print $query->reset

  print $query->defaults('button_label')

   Named parameter style
   print $query->hidden(-name=>'hidden_name',
                        -default=>['value1','value2'...]);

   Old style
   print $query->hidden('hidden_name','value1','value2'...);

• The first argument (-name) is required and specifies the name of this field.
• The second and subsequent arguments specify the value for the hidden field. This is a quick and dirty way of passing perl arrays through forms. If you use the named parameter style, you must provide the parameter -default and an array reference here.

As of version 2.0 I have changed the behavior of hidden fields once again. Read this if you use hidden fields.

Hidden fields used to behave differently from all other fields: the provided default values always overrode the "sticky" values. This was the behavior people seemed to expect, however it turns out to make it harder to write state-maintaining forms such as shopping cart programs. Therefore I have made the behavior consistent with other fields.

Just like all the other form elements, the value of a hidden field is "sticky". If you want to replace a hidden field with some other values after the script has been called once you'll have to do it manually before writing out the form element:

     $query->param('hidden_name','new','values','here');
     print $query->hidden('hidden_name');

    $hidden_value = $query->param('hidden_name');
            -or (for values created with arrays)-
    @hidden_values = $query->param('hidden_name');

   Named parameter style
   print $query->image_button(-name=>'button_name',
                              -src=>'/images/NYNY.gif',
                              -align=>'MIDDLE');	

   Old style
   print $query->image_button('button_name','/source/URL','MIDDLE');

• The first argument(-name is required and specifies the name of this field.
• The second argument (-srcspecifies the URL of the image to display. It must be one of the types supported by inline images (e.g. GIF), but can be any local or remote URL.
• The third argument (-alignis anything you might want to use in the ALIGN attribute, such as TOP, BOTTOM, LEFT, RIGHT or MIDDLE. This field is optional.

    $x = $query->param('button_name.x');
    $y = $query->param('button_name.y');

Controlling HTML Autoescaping

Use

    $query->autoEscape(undef);

    $query->autoEscape('true');

   my_script.pl keyword1 keyword2 keyword3

   my_script.pl keyword1+keyword2+keyword3

   my_script.pl name1=value1 name2=value2

   my_script.pl name1=value1&name2=value2

   % my_script.pl
   first_name=fred
   last_name=flintstone
   occupation='granite miner'
   ^D

When debugging, you can use quotation marks and the backslash character to escape spaces and other funny characters in exactly the way you would in the shell (which isn't surprising since CGI.pm uses "shellwords.pl" internally). This lets you do this sort of thing:

    my_script.pl 'name 1'='I am a long value' "name 2"=two\ words

   print $query->dump

   <UL>
   <LI>name1
       <UL>
       <LI>value1
       <LI>value2
       </UL>
   <LI>name2
       <UL>
       <LI>value1
       </UL>
   </UL>

   print "<H2>Current Contents:</H2>\n$query\n";

accept()

Return a list of MIME types that the remote browser accepts. If you give this method a single argument corresponding to a MIME type, as in $query->accept('text/html'), it will return a floating point value corresponding to the browser's preference for this type from 0.0 (don't want) to 1.0. Glob types (e.g. text/*) in the browser's accept list are handled correctly.

auth_type()

Return the authorization type, if protection is active. Example "Basic".

path_info()

Returns additional path information from the script URL. E.G. fetching /cgi-bin/your_script/additional/stuff will result in $query->path_info() returning "/additional/stuff"

path_translated()

As per path_info() but returns the additional path information translated into a physical path, e.g. "/usr/local/etc/httpd/htdocs/additional/stuff".

referer()

Return the URL of the page the browser was viewing prior to fetching your script. Not available for all browsers.

remote_addr()

Return the dotted IP address of the remote host.

remote_ident()

Return the identity-checking information from the remote host. Only available if the remote host has the identd daemon turned on.

remote_host()

Returns either the remote host name or IP address. if the former is unavailable.

remote_user()

Return the name given by the remote user during password authorization.

script_name()

Return the script name as a partial URL, for self-refering scripts.

server_name()

Return the name of the WWW server the script is running under.

server_port()

Return the communications port the server is using.

user_agent()

Returns the identity of the remote user's browser software, e.g. "Mozilla/1.1N (Macintosh; I; 68K)"

A Script that Saves Some Information to a File and Restores It

#!/usr/local/bin/perl

use CGI;
$query = new CGI;

print $query->header;
print $query->start_html("Save and Restore Example");
print "<H1>Save and Restore Example</H1>\n";

# Here's where we take action on the previous request
&save_parameters($query)              if $query->param('action') eq 'save';
$query = &restore_parameters($query)  if $query->param('action') eq 'restore';

# Here's where we create the form
print $query->startform;
print "Popup 1: ",$query->popup_menu('popup1',['eenie','meenie','minie']),"\n";
print "Popup 2: ",$query->popup_menu('popup2',['et','lux','perpetua']),"\n";
print "<P>";
print "Save/restore state from file: ",$query->textfield('savefile','state.sav'),"\n";
print "<P>";
print $query->submit('action','save'),$query->submit('action','restore');
print $query->submit('action','usual query');
print $query->endform;

# Here we print out a bit at the end
print $query->end_html;

sub save_parameters {
    local($query) = @_;
    local($filename) = &clean_name($query->param('savefile'));
    if (open(FILE,">$filename")) {
	$query->save(FILE);
	close FILE;
	print "<STRONG>State has been saved to file $filename</STRONG>\n";
    } else {
	print "<STRONG>Error:</STRONG> couldn't write to file $filename: $!\n";
    }
}

sub restore_parameters {
    local($query) = @_;
    local($filename) = &clean_name($query->param('savefile'));
    if (open(FILE,$filename)) {
	$query = new CGI(FILE);  # Throw out the old query, replace it with a new one
	close FILE;
	print "<STRONG>State has been restored from file $filename</STRONG>\n";
    } else {
	print "<STRONG>Error:</STRONG> couldn't restore file $filename: $!\n";
    }
    return $query;
}


# Very important subroutine -- get rid of all the naughty
# metacharacters from the file name. If there are, we
# complain bitterly and die.
sub clean_name {
   local($name) = @_;
   unless ($name=~/^[\w\.-]+$/) {
      print "<STRONG>$name has naughty characters.  Only ";
      print "alphanumerics are allowed.  You can't use absolute names.</STRONG>";
      die "Attempt to use naughty characters";
   }
   return $name;
}

A Script that Uses Self-Referencing URLs to Jump to Internal Links

Many people have experienced problems with internal links on pages that have forms. Jumping around within the document causes the state of the form to be reset. A partial solution is to use the self_url() method to generate a link that preserves state information. This script illustrates how this works.

#!/usr/local/bin/perl

use CGI;
$query = new CGI;

# We generate a regular HTML file containing a very long list
# and a popup menu that does nothing except to show that we
# don't lose the state information.
print $query->header;
print $query->start_html("Internal Links Example");
print "<H1>Internal Links Example</H1>\n";

print "<A NAME=\"start\"></A>\n"; # an anchor point at the top

# pick a default starting value;
$query->param('amenu','FOO1') unless $query->param('amenu');

print $query->startform;
print $query->popup_menu('amenu',[('FOO1'..'FOO9')]);
print $query->submit,$query->endform;

# We create a long boring list for the purposes of illustration.
$myself = $query->self_url;
print "<OL>\n";
for (1..100) {
    print qq{<LI>List item #$_<A HREF="$myself#start">Jump to top</A>\n};
}
print "</OL>\n";

print $query->end_html;

Multiple forms on the same page

There is, however, a problem with maintaining the states of multiple forms. Because the browser only sends your script the parameters from the form in which the submit button was pressed, the state of all the other forms will be lost. One way to get around this, suggested in this example, is to use hidden fields to pass as much information as possible regardless of which form the user submits.

#!/usr/local/bin/perl
use CGI;

$query=new CGI;
print $query->header;
print $query->html_header('Multiple forms');
print "<H1>Multiple forms</H1>\n";

# form 1
print "<HR>\n";
print $query->startform;
print $query->textfield('text1'),$query->submit('submit1');
print $query->hidden('text2');  # pass information from the other form
print $query->endform;
print "<HR>\n";

# form 2
print $query->startform;
print $query->textfield('text2'),$query->submit('submit2');
print $query->hidden('text1');  # pass information from the other form
print $query->endform;
print "<HR>\n";

Potential Problems with the File Upload Feature

Another potential problem with the file upload feature is that it potentially involves sending more data to the CGI script than the script can hold in main memory. For this reason CGI.pm creates temporary files in either the /usr/tmp or the /tmp directory. If neither of these These temporary files have names like CGItemp125421, and should be deleted automatically.

Frequent Problems

You can't retrieve the name of the uploaded file using the param() method

You can read the name of the uploaded file, but can't retrieve the data

If you're on a non-Unix system you may need to modify CGI.pm to point at a suitable temporary directory. This directory must be writable by the user ID under which the server runs (usually "nobody") and must have sufficient capacity to handle large file uploads. Open up CGI.pm, and find the line:

      package TempFile;
      foreach ('/usr/tmp','/tmp') {
         do {$TMPDIRECTORY = $_; last} if -w $_;
      }

Using CGI.pm on non-Unix Platforms

Windows NT

CGI.pm must be put in the perl5 library directory, and all CGI scripts that use it should be placed in WebSite's cgi-shl directory. You also need to associate the .pl suffix with perl5 using the NT file manager.

VMS

Find the line:

   $CRLF="\r\n"

   $CRLF="\n";

Macintosh

The current version of CGI.pm can be found at:

  
http://www-genome.wi.mit.edu/ftp/pub/software/WWW/

You are encouraged to look at these other Web-related modules:

HTML.pm

A module that simplifies the creation of HTML documents programatically.

CGI::Base,CGI::Form,CGI::MiniSrv,CGI::Request and CGI::URI::URL

Modules for parsing script input, manipulating URLs, creating forms and even launching a miniature Web server.

libwww-perl

Modules for fetching Web resources from within Perl, writing Web robots, and much more.

GD.html

A module for creating GIF images on the fly, using Tom Boutell's gd graphics library.

qd.pl

A library for creating Macintosh PICT files on the fly (which can be converted to GIF or JPEG using NetPBM).

For a collection of CGI scripts of various levels of complexity, see the companion pages for my book How to Set Up and Maintain a World Wide Web Site

Bug Reports

Up to table of contents

Revision History: v1.3->v2.0

Version 2.01

1. Added -rows and -columns to the radio and checkbox groups. No doubt this will cause much grief because it seems to promise a level of meta-organization that it doesn't actually provide.
2. Fixed a bug in the redirect() method -- it was not truly HTTP/1.0 compliant.

Version 2.0

1. Support for named parameter style method calls. This turns out to be a big win for extending CGI.pm when Netscape adds new HTML "features".
2. Changed behavior of hidden fields back to the correct "sticky" behavior. This is going to break some programs, but it is for the best in the long run.
3. Netscape 2.0b2 broke the file upload feature. CGI.pm now handles both 2.0b1 and 2.0b2-style uploading. It will probably break again in 2.0b3.
4. There were still problems with library being unable to distinguish between a form being loaded for the first time, and a subsequent loading with all fields blank. We now forcibly create a default name for the Submit button (if not provided) so that there's always at least one parameter.
5. More workarounds to prevent annoying spurious warning messages when run under the -w switch. -w is seriously broken in perl 5.001!

Version 1.57

1. Support for the Netscape 2.0 "File upload" field.
2. The handling of defaults for selected items in scrolling lists and multiple checkboxes is now consistent.

Version 1.56

1. Created true "pod" documentation for the module.
2. Cleaned up the code to avoid many of the spurious "use of uninitialized variable" warnings when running with the -w switch.
3. Added the autoEscape() method.
4. Added string interpolation of the CGI object.
5. Added the ability to pass additional parameters to the <BODY> tag.
6. Added the ability to specify the status code in the HTTP header.

Bug fixes in version 1.55

1. Every time self_url() was called, the parameter list would grow. This was a bad "feature".
2. Documented the fact that you can pass "-" to radio_group() in order to prevent any button from being highlighted by default.

Bug fixes in version 1.54

1. The user_agent() method is now documented;
2. A potential security hole in import() is now plugged.
3. Changed name of import() to import_names() for compatability with CGI:: modules.

Bug fixes in version 1.53

1. Fixed several typos in the code that were causing the following subroutines to fail in some circumstances
   1. checkbox()
   2. hidden()
2. No features added

New features added in version 1.52

1. Added backslashing, quotation marks, and other shell-style escape sequences to the parameters passed in during debugging off-line.
2. Changed the way that the hidden() method works so that the default value always overrides the current one.
3. Improved the handling of sticky values in forms. It's now less likely that sticky values will get stuck.
4. If you call server_name(), script_name() and several other methods when running offline, the methods now create "dummy" values to work with.

Bugs fixed in version 1.51

1. param() when called without arguments was returning an array of length 1 even when there were no parameters to be had. Bad bug! Bad!
2. The HTML code generated would break if input fields contained the forbidden characters ">< or &. You can now use these characters freely.

New features added in version 1.50

1. import() method allows all the parameters to be imported into a namespace in one fell swoop.
2. Parameters are now returned in the same order in which they were defined.

Bugs fixed in version 1.45

1. delete() method didn't work correctly. This is now fixed.
2. reset() method didn't allow you to set the name of the button. Fixed.

Bugs fixed in version 1.44

1. self_url() didn't include the path information. This is now fixed.

New features added in version 1.43

1. Added the delete() method.

New features added in version 1.42

1. The image_button() method to create clickable images.
2. A few bug fixes involving forms embedded in <PRE> blocks.

New features added in version 1.4

1. New header shortcut methods
   • redirect() to create HTTP redirection messages.
   • start_html() to create the HTML title, complete with the recommended <LINK> tag that no one ever remembers to include.
   • end_html() for completeness' sake.
2. A new save() method that allows you to write out the state of an script to a file or pipe.
3. An improved version of the new() method that allows you to restore the state of a script from a file or pipe. With (2) this gives you dump and restore capabilities! (Wow, you can put a "121,931 customers served" banner at the bottom of your pages!)
4. A self_url() method that allows you to create state-maintaining hypertext links. In addition to allowing you to maintain the state of your scripts between invocations, this lets you work around a problem that some browsers have when jumping to internal links in a document that contains a form -- the form information gets lost.
5. The user-visible labels in checkboxes, radio buttons, popup menus and scrolling lists have now been decoupled from the values sent to your CGI script. Your script can know a checkbox by the name of "cb1" while the user knows it by a more descriptive name. I've also added some parameters that were missing from the text fields, such as MAXLENGTH.
6. A whole bunch of methods have been added to get at environment variables involved in user verification and other obscure features.

Bug fixes

1. The problems with the hidden fields have (I hope at last) been fixed.
2. You can create multiple query objects and they will all be initialized correctly. This simplifies the creation of multiple forms on one page.
3. The URL unescaping code works correctly now.

Last modified September 27, 1995.