CGI.pm Reference

The following methods are supported by CGI.pm.

accept 
$query->accept(['content_type'])

Returns a list of media types that the browser accepts.

  • content_type
  • If specified, returns instead the browser's preference for the specified content type, between 0.0 and 1.0
append 
$query->append(-name=>'name',-values=>'value')

Appends a value or list of values to the named parameter.

  • -name=>'name'
  • The parameter to append.
  • -values=>'value'
  • The value to append. Multiple values can be specified as a reference to an anonymous array.
auth_type 
auth_type( )

Returns the authorization method.

autoEscape 
$query->autoEscape(undef)

Turns off autoescaping of form elements.

button 
print $query->button('name','function')

Generates a JavaScript button.

  • name
  • The name of the button.
  • function
  • The function to execute when the button is clicked. Using named parameters, the syntax is: 
    print $query->button(-name=>'name', -value=>'label', -onClick=>"function");
    • -value=>'label'
    • The label to display for the button
checkbox 
print $query->checkbox('name' [,'checked','value','label'])

Generates a single checkbox.

  • name
  • The name to assign the input to (required).
  • checked
  • Checkbox should be checked initially.
  • value
  • The value to return when checked (default is on).
  • label
  • The label to use for the checkbox (default is the name of the checkbox). Using named parameters, the syntax is: 
    print $query->checkbox(-name=>'name', -checked=>'checked', -value=>'value', -label=>'label', -onClick=>function);
    • -onClick=>function
    • Browser should execute function when the user clicks on any checkbox in the group
checkbox_group 
print $query->checkbox_group('name', \@list [, selected,'true',\%labelhash ])

Generates a list of checkbox elements.

  • name
  • The name to assign the input to (required).
  • @list
  • An array reference with the list items. You can also use an anonymous array reference.
  • selected
  • The menu item(s) to be initially selected (default is that nothing is selected). This can be a single value or a reference to an array of values.
  • 'true'
  • Insert newlines between the checkboxes.
  • %labelhash
  • A hash reference listing labels for each list item. Default is the list text itself. See popup_menu for an example. Using named parameters, the syntax is: 
    print $query->checkbox_group(-name=>'name', -values=>\@list, -default=>selected, -linebreak=>'true', -labels=>\%labelhash, -columns=>n, -columnheader=>'string', -rows=>m, -rowheader=>'string', -onClick=>function);
    • -columns=>n
    • The number of columns to use.
    • -columnheader=>'string'
    • A header for the column.
    • -rows=m
    • The number of rows to use. If omitted, and -columns is specified, the rows will be calculated for you.
    • -rowheader=>'string'
    • A header for the row.
    • -onClick=>function
    • Browser should execute function when the user clicks on any checkbox in the group.
cookie 
$cookie=$query->cookie('name')

Defines or retrieves a cookie. See also header.

  • name
  • Name of the cookie (required). Using named parameters, the syntax is: 
    $cookie = $query->cookie(-name=>'name', -value=>'value', -expires=>'expcode', -path=>'partial_url', -domain=>'domain_name', -secure=>1);
print $query->header(-cookie=>$cookie);
    • -value=>'value'
    • A value to assign to the cookie. You can supply a scalar value, or a reference to an array or hash. If omitted, a cookie will be retrieved rather than defined.
    • -expires=>expcode
    • Specifies an expiration timestamp (such as +3d for three days). Values for expcode are:
      • ns
      • n seconds
      • nm
      • n minutes
      • nh
      • n hours
      • nd
      • n days
      • nM
      • n months
      • ny
      • n years
      • day_of_week, dd-MMM-YY hh:mm:ss GMT
      • At the specified time.
      • now
      • Expires immediately.
    • -path=>'partial_url'
    • The partial URL for which the cookie is valid. Default is the current URL.
    • -domain=>'domain_name'
    • The domain for which the cookie is valid.
    • -secure=>1
    • Use this cookie only for a secure session.
defaults 
print $query->defaults('label')

Generates a button that resets the form to its defaults. See also reset.

  • 'label'
  • The label to use for the button. If omitted, the label is Defaults.
delete 
$query->delete('parameter')

Deletes a parameter.

  • 'parameter'
  • The parameter to delete
delete_all 
$query->delete_all( )

Deletes the entire CGI object.

dump 
print $query->dump([true])

Dumps all name/value pairs as an HTML list.

  • true
  • If specified, prints as plain text
end_html 
print $query->end_html( )

Ends an HTML document.

filefield 
print $query->filefield('name' [,'default',size,maxlength ])

Generates a file upload field for Netscape browsers.

  • name
  • The filename to assign the supplied file contents to (required)
  • default
  • The initial value (filename) to place in the text field
  • size
  • The size of the text field (in characters)
  • maxlength
  • The maximum length of the text field (in characters)

    Using named parameters, the syntax is: 

    print $query->textfield(-name=>'name', -default=>'value', -size=>size, -maxlength=>maxlength, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);
    • -override=>1
    • Text field should not inherit its value from a previous invocation of the script
    • -onChange=>function
    • Browser should execute function when the user changes the text field
    • -onFocus=>function
    • Browser should execute function when the focus is on the text field
    • -onBlur=>function
    • Browser should execute function when the focus leaves the text field
    • -onSelect=>function
    • Browser should execute function when the user changes a selected portion of the text field
header 
print $query->header([content_type ,status ,headers])

Generates the HTTP header for the document.

  • content_type
  • The content type to return. Default is text/html.
  • status
  • The HTTP status code and description to return. Default is OK.
  • headers
  • Additional headers to include, such as Content-Length: 123. Using named parameters, the syntax is: 
    print $query->header(-type=>'content_type', -nph=>1, -status=>'status_code', -expires=>'expcode', -cookie=>'cookie', -target=>'frame', -header=>'value');
    • -type=>content_type
    • Specifies the content type.
    • -nph=>1
    • Uses headers for a no-parse-header script.
    • -status=>status_code
    • Specifies the status code.
    • -expires=>expcode
    • Specifies an expiration timestamp (such as +3d for three days). Values for expcode are:
      • ns
      • n seconds
      • nm
      • n minutes
      • nh
      • n hours
      • nd
      • n days
      • nM
      • n months
      • ny
      • n years
      • day_of_week, dd-MMM-YY hh:mm:ss GMT
      • At the specified time
      • now
      • Expires immediately
    • -cookie=>cookie
    • Specifies a cookie. The cookie may be a scalar value or an array reference.
    • -header=>value
    • Specifies any HTTP header.
    • -target=>frame
    • Writes to specified frame.
hidden 
print $query->hidden('name', 'value' [,'value'... ])

Generates a hidden text field.

  • name
  • The name to give the value (required).
  • value
  • The value to assign to name. Multiple values can be specified. Using named parameters, the syntax is: 
    print $query->hidden(-name=>'name', -default=>'value');

    With named parameters, the value can also be represented as a reference to an array, such as: 

    print $query->hidden(-name=>'name', -default=>['value1', 'value2', ... ]);
image_button 
print $query->image_button('name','url' [,'align'])

Generates a clickable image map.

  • name
  • The name to use. When clicked, the xyposition is returned as namexand namey, respectively.
  • url
  • The URL of the image for the image map.
  • align
  • The alignment type. May be TOP, BOTTOM, or MIDDLE. Using named parameters, the syntax is: 
    print $query->image_button(-name=>'name', -src=>'url', -align=>'align', -onClick=>function);
    • -onClick=>function
    • Browser should execute function when the user clicks on the image
import_names 
$query->import_names('package')

Creates variables in the specified package. Called import in older versions of CGI.pm.

  • package
  • The package to import names into
isindex 
print $query->isindex([action])

Generates an <ISINDEX> tag.

  • action
  • The URL of the index script. Default is the current URL. Using named parameters, the syntax is: 
    print $query->isindex(-action=>$action);
keywords 
@keyarray = $query->keywords( )

Retrieves keywords from an <ISINDEX> search.

  • @keyarray
  • The array that will contain the retrieved keywords
nph 
nph(1)

Treats a CGI script as a no-parsed-header (NPH) script.

param 
@name = $query->param([parameter [newvalue1, newvalue2, ...] ])

Gets or sets parameter names.

  • @name
  • The array that will contain the parameter names.
  • parameter
  • An optional single parameter to fetch. When used with no arguments, param returns a list of all known parameter names.
  • newvalue1, newvalue2, ...
  • The optional new values to assign to the parameter. Using named parameters, the syntax is: 
    $query->param(-name=>'parameter', -value=>'newvalue');

    or: 

    $query->param(-name=>'parameter', -values=>'newvalue1', 'newvalue2', ...);
password_field 
print $query->password_field('name' [,'value',size,maxlength ])

Generates a password input field.

  • name
  • The name to assign the input to (required).
  • value
  • The default password to place in the password field.
  • size
  • The size of the password field (in characters).
  • maxlength
  • The maximum length of the password field (in characters). Using named parameters, the syntax is: 
    print $query->password_field(-name=>'name', -default=>'value', -size=>size, -maxlength=>maxlength, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);
    • -override=>1
    • Text field should not inherit its value from a previous invocation of the script
    • -onChange=>function
    • Browser should execute function when the user changes the text field
    • -onFocus=>function
    • Browser should execute function when the focus is on the text field
    • -onBlur=>function
    • Browser should execute function when the focus leaves the text field
    • -onSelect=>function
    • Browser should execute function when the user changes a selected portion of the text field
path_info 
path_info( )

Returns extra path information.

path_translated 
path_translated( )

Returns translated extra path information.

popup_menu 
print $query->popup_menu('name', @array [,'selected', \%labelhash])

Generates a popup menu.

  • name
  • The name to assign the input to (required).
  • @array
  • An array reference listing the menu items. You can also use an anonymous array reference (see example below).
  • selected
  • The menu item to be initially selected (default is first menu item or the item selected in previous queries).
  • %labelhash
  • A hash reference listing labels for each menu item. Default is menu item text. For example: 
    %labels = ('UPS'=>'United Parcel Service (UPS)', 'FedExO'=>'Federal Express Overnight - 10AM delivery', 'FedExS'=>'Federal Express Standard - 2PM delivery', 'FedEx2'=>'Federal Express 2nd Day Delivery');
print $query->popup_menu('delivery_method', ['UPS', 'FedExO', 'FedExS', 'FedEx2'], 'FedExO', \%labels);

    Using named parameters, the syntax is: 

    print $query->popup_menu(-name=>'name', -values=>\@array, -default=>'selected', -labels=>\%labelhash, -onChange=>function, -onFocus=>function, -onBlur=>function);
    • -onChange=>function
    • Browser should execute function when the user changes the text field
    • -onFocus=>function
    • Browser should execute function when the focus is on on the text field
    • -onBlur=>function
    • Browser should execute function when the focus leaves the text field
radio_group 
print $query->radio_group('name', \@list [, selected, 'true', \%label ])

Generates a set of radio buttons.

  • name
  • The name to assign the input to (required).
  • @list
  • An array reference with the list items. You can also use an anonymous array reference.
  • selected
  • The menu item to be initially selected.
  • 'true'
  • Inserts newlines between radio buttons.
  • %label
  • A hash reference listing labels for each list item. Default is the list text itself. (See popup_menu for an example.) Using named parameters, the syntax is: 
    print $query->radio_group(-name=>'name', -values=>\@list, -default=>'selected', -linebreak=>'true', -labels=>\%labelhash, -columns=>n, -columnheader=>'string', -rows=>m, -rowheader=>'string');
    • -columns=>n
    • The number of columns to use.
    • -columnheader=>'string'
    • A header for the column.
    • -rows=m
    • The number of rows to use. If omitted, and -columns is specified, the rows will be calculated for you.
    • -rowheader=>'string'
    • A header for the row.
raw_cookie 
raw_cookie( )

Returns the value of the HTTP_COOKIE header.

ReadParse 
ReadParse( )

Creates a hash named %in containing query information. Used for backwards compatibility with the Perl4 cgi-lib.pl.

redirect 
print $query->redirect('url')

Generates a header for redirecting the browser.

  • url
  • The absolute URL to redirect to. Using named parameters, the syntax is: 
    print $query->redirect(-uri=>'url', -nph=>1);
referer 
referer( )

Returns the referring URL.

remote_host 
remote_host( )

Returns the remote hostname or IP address, depending on the configuration of the server.

remote_user 
remote_user( )

Returns the username supplied for authorization.

request_method 
request_method( )

Returns the request method.

reset 
print $query->reset

Generates a button that resets the form to its initial values. See also defaults.

save 
$query->save(filehandle)

Saves the form to the specified filehandle, to be read back with the new constructor.

  • filehandle
  • The filehandle to save the file to
script_name 
script_name( )

Returns the current partial URL.

scrolling_list 
print $query->scrolling_list('name',\@list[,selected,size,'true',\%labelhash]);

Generates a scrolling list.

  • name
  • The name to assign the input to (required).
  • @list
  • An array reference with the list items. You can also use an anonymous array reference.
  • selected
  • The menu item(s) to be initially selected (default is that nothing is selected). This can be a single value or a reference to a list of values.
  • size
  • The number of elements to display in the list box.
  • 'true'
  • Allows multiple selections.
  • %labelhash
  • A hash reference listing labels for each list item. Default is the list text itself. (See popup_menu for an example.) Using named parameters, the syntax is: 
    print $query->scrolling_list(-name=>'name', -values=>\@listarray, -default=>selected, -size=>size, -multiple=>'true', -labels=>\%labelhash, -onChange=>function, -onFocus=>function, -onBlur=>function);
    • -onChange=>function
    • Browser should execute function when the user changes the text field
    • -onFocus=>function
    • Browser should execute function when the focus is on on the text field
    • -onBlur=>function
    • Browser should execute function when the focus leaves the text field
self_url 
$url = $query->self_url

Returns the URL of the current script with all its state information intact.

start_html 
print $query->start_html(['title', 'email', 'base', attribute="value"])

Generates <HTML> and <BODY> tags.

  • title
  • The title of the page.
  • email
  • The author's email address.
  • base
  • Whether to use a <BASE> tag in the header.
  • attribute="value"
  • Specifies an attribute to the <BODY> tag. Using named parameters, the syntax is: 
    print $query->start_html(-title=>'title', -author=>'email_address', -base=>'true', -xbase=>'url', -meta=>{'metatag1'=>'value1', 'metatag2'=> 'value2'}, -script=>'$script', -onLoad=>'$function', -onUnload=>'$function', -attribute=>'value');
    • -title=>'title'
    • Specifies the title of the page.
    • -author=>'email_address'
    • Specifies the author's email address.
    • -xbase=>'url'
    • Provides an HREF for the <BASE> tag. Default is the current location.
    • -meta=>{'metatag1'=>'value1', ... }
    • Adds arbitrary meta information to the header as a reference to a hash. Valid tags are:
    • keywords
    • Keywords for this document
    • copyleft
    • copyleft for this document description
    • description
    • Description for this document
    • attribute=>'value'
    • Specifies an attribute to the <BODY> tag
  • -script=>'$script'
  • Specifies a JavaScript script to be embedded within a <SCRIPT> block.
  • -onLoad=>'$function'
  • Browser should execute specified function upon entering page.
  • -onUnload=>'$function'
  • Browser should execute specified function upon leaving page.
startform 
print $query->startform([method, action, encoding])

Generates a <FORM> tag.

  • method
  • The request method for the form. Values are:
    • POST
    • Use the POST method (default).
    • GET
    • Use the GET method.
  • action
  • The URL of the CGI script. Default is the current URL.
  • encoding
  • The encoding scheme. Possible values are application/x-www-form-urlencoded and multipart/form-data. Using named parameters, the syntax is: 
    print $query->startform(-method=>$method, -action=>$action, -encoding=>$encoding, -name=>$name, -target=>frame, -onSubmit=>function);
    • -name=>name
    • Names the form for identification by JavaScript functions
    • -target=>frame
    • Writes to the specified frame
    • -onSubmit=>function
    • A JavaScript function that the browser should execute upon submitting the form
start_multipart_form 
print $query->start_multipart_form([method, action])

Generates <HTML> and <BODY> tags. Same as startform, but assumes multipart/form-data encoding as the default.

submit 
print $query->submit([ 'label''value' ])

Generates a Submit button.

  • label
  • The label to use for the button.
  • value
  • The value to return when the form is submitted. Using named parameters, the syntax is: 
    print $query->submit(-name=>'name', -value=>'value', -onClick=>function);
    • -onClick=>function
    • Browser should execute function when the user clicks on the image
textarea 
print $query->textarea('name' [,'value',rows,columns ])

Generates a large multiline text input box.

  • name
  • The name to assign the input to (required).
  • value
  • The initial value to place into the text input box.
  • rows
  • The number of rows to display.
  • columns
  • The number of columns to display. Using named parameters, the syntax is: 
    print $query->textarea(-name=>'name', -default=>'value', -rows=>rows, -columns=>columns, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);
    • -override=>1
    • Text field should not inherit its value from a previous invocation of the script
    • -onChange=>function
    • Browser should execute function when the user changes the text field
    • -onFocus=>function
    • Browser should execute function when the focus is on the text field
    • -onBlur=>function
    • Browser should execute function when the focus leaves the text field
    • -onSelect=>function
    • Browser should execute function when the user changes a selected portion of the text field
textfield 
print $query->textfield('name' [,'value', size, maxlength])

Generates a text input field.

  • name
  • The name to assign the input to (required).
  • value
  • The initial value to place in the text field.
  • size
  • The size of the text field (in characters).
  • maxlength
  • The maximum length of the text field (in characters). Using named parameters, the syntax is: 
    print $query->textfield(-name=>'name', -default=>'value', -size=>size, -maxlength=>maxlength, -override=>1, -onChange=>function, -onFocus=>function, -onBlur=>function, -onSelect=>function);
    • -override=>1
    • Text field should not inherit its value from a previous invocation of the script
    • -onChange=>function
    • Browser should execute function when the user changes the text field
    • -onFocus=>function
    • Browser should execute function when the focus is on the text field
    • -onBlur=>function
    • Browser should execute function when the focus leaves the text field
    • -onSelect=>function
    • Browser should execute function when the user changes a selected portion of the text field
url 
$url = $query->url

Returns a URL of the current script without query information.

use_named_parameters 
use_named_parameters( )

Specifies that functions should take named parameters.

user_agent 
$query->user_agent( [string] )

Returns the value of the HTTP_USER_AGENT header.

  • string
  • If specified, returns only headers matching the specified string
user_name 
user_name( )

Returns the remote user's login name; unreliable.