Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CGI::Response(3)      User Contributed Perl Documentation     CGI::Response(3)

       CGI::Response - Respond to CGI requests

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

   Full	Interface
	 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.]

   Simple Interface
       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

	      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;

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

       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

perl v5.32.0			  1995-11-26		      CGI::Response(3)


Want to link to this manual page? Use this URL:

home | help