Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
CGI::Response(3) User Contributed Perl Documentation CGI::Response(3)

CGI::Response - Respond to CGI requests

  use CGI::Response qw(:Simple);
  print ContentType;
  print "<html><head>\n"; # .....

  use CGI::Response;
  $response = new CGI::Response;
  print $response->as_string;
  print "<html><head>\n"; # .....

CGI::Response is a Perl5 module for constructing responses to Common Gateway Interface (CGI) requests. It is designed to be light-weight and efficient for the most common tasks, and also to provide access to all HTTP response features for more advanced CGI applications.

There are two ways to use CGI::Response. For basic applications, the Simple Interface provides a number of plain functions that cover the most commonly-used CGI response headers. More advanced applications may employ the Full Interface object methods to access any HTTP header, or to add experimental or non-standard headers. Both interfaces try to generate reasonable defaults whenever possible.

For efficiency, just the Simple Interface functions are compiled on start-up. Full Interface methods are compiled only when they are called. This helps to make CGI::Response usable in a variety of applications. [See SelfLoader for more information.]

The Simple Interface methods are not exported by default. In order to use them, you must import them explicitly. You can import all of the methods at once by saying:

   use CGI::Response qw(:Simple);

Or, you can import just one function by listing it by name, as in:

   use CGI::Response qw(ContentType);

Only one Simple Interface function should be called in a response, since all of these functions terminate the response header (that is, send the blank line denoting the end of the header) immediately upon execution. If you need to use a combination of headers not provided by the Simple Interface, use the Full Interface instead.

All of the Simple Interface functions force a flush on the currently-selected output channel (that is, they set "$| = 1"). This is done to prevent a common probelm in CGI scripts, where a "system()" or "exec()" call causes output before the response header, and generates a server error. If you do not want "$| = 1", you should either set it back to 0 after using the Simple Interface, or you should employ the Full Interface, which does not have this side effect.

For reference, below is a list of the headers sent by each function, and the default header values, if any. Arguments are listed in the order they should appear. Square brackets ([]) indicate optional arguments; angled brackets (<>) indicate required arguments.

   Function      Argument(s)      Header(s)      Default(s)
   --------      -----------      ---------      ----------
   &ContentType  [content-type]   Content-Type   text/html

   &Redirect     <Location/URI>   Location       [none]
                 [permanent?]     URI            [none]
                                  Content-Type   text/html
                                  Status         302 Moved Temporarily

   &NoCache      [content-type]   Content-Type   text/html
                                  Pragma         no-cache
                                  Expires        [now]

   &NoContent                     Status         204 No Content

Each of these functions is documented more completely below, and examples for each are provided.

This is the most commonly-used function. It identifies the Internet Media Type of the entity that follows. If you call it without an argument, it will send "text/html" as the content-type.

   use CGI::Response qw(:Simple);
   print &ContentType;   # defaults to text/html

Otherwise, you can specify some other content-type:

   use CGI::Response qw(:Simple);
   print &ContentType('image/gif');

This function should be called as early as possible to prevent server errors (see the note on $| above).

A redirect causes the user-agent to make a follow-up request for some other resource. Some user-agents will be better than others at complying with a redirect, so this function tries to be as explicit as possible.

You are required to give one argument, specifying the URL which the user-agent should request. A second argument is accepted as a Boolean value -- if any second argument is present, the browser will be told that the requested resource has moved permanently to a new URL (that is, future requests for the document should be to the new URL, not to the one which was first requested).

   use CGI::Response qw(:Simple);
   print &Redirect('', 'permanent');
   # this resource has moved permanently, status 301

If no second argument is given, the redirect will be specified as temporary.

   use CGI::Response qw(:Simple);
   print &Redirect('');   
   # this resource has moved temporarily, status 302

A brief HTML page is output after the header so that users whose user-agents fail to recognize the redirect will get an informative message with a link to the redirect. Use the Full Interface to supply some other page or none at all.

This function tries to inform user-agents and proxy servers that the included resource should not be cached. It does so by sending both an "Expires" header, set for immediate expiration, and a "Pragma: no-cache" header, which older user-agents and servers might not recognize.

Preventing caching is important to CGI applications which produce output based on some factor of the request (such as which user-agent made the request). For instance, a shopping-basket application would not want to allow caching of an order information page, which may contain user-specific information.

It must be noted, however, that caches prevent excess network load and cache-friendly applications are always preferable to use of the &NoCache function. This function should only be used when there is no other alternative.

&NoCache takes one optional argument, the content-type of the entity to follow. Therefore, its call is nearly identical to the &ContentType function, and the two functions may be interchanged easily. As with &ContentType, if you call &NoCache without an argument, it will send "text/html" as the content-type.

   use CGI::Response qw(:Simple);
   print &NoCache;   # defaults to text/html

Otherwise, you can specify some other content-type:

   use CGI::Response qw(:Simple);
   print &NoCache('image/gif');

As noted earlier, this function should be called as early as possible to prevent server errors (see the note on $| above).

&NoContent allows a script to accept input without changing the current page in the user-agent's view. This may be useful for a successful form input that requires no response, or for an imagemap click that does not have a defined link.

A No Content response does not reset form fields after submission. HTTP/1.1 will include a "205 Reset Document" status for this purpose, and a future version of this module will provide a &Reset function to support this status.

This function sends only one header, "Status: 204 No Content", and it takes no arguments.

   use CGI::Response qw(:Simple);
   print &NoContent;

The Full Interface is still under development and is not currently documented.

CGI::Base(3pm), CGI::BasePlus(3pm), CGI::Request(3pm), CGI::Lite(3pm), CGI(3pm), CGI::Form(3pm), LWP(3pm), SelfLoader(3pm)

Please note that future versions are not guaranteed to be backwards-compatible with this version. The interface will be frozen at version 0.1 (first beta release).

  Version:      0.03 (alpha release)
  Release date: 02 December 1995

  Marc Hedlund <>
  Copyright 1995, All rights reserved
1995-11-26 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.