CGI Reference
Overview
The server executes a CGI script by forking a child process which
executes the CGI binary. Before creating the child process, the
parent process sets up communication channels between the webserver
and CGI process. The CGI script reads the input provided by the
webserver, generates the document to be sent to the client, sends it
back to the webserver and exits. The webserver processes the
response, for example adding extra header lines and encrypting the
data for transfer over an SSL session, and then sends the result to
the client.
Input
The CGI script gets input from two sources, the environment and
optionally from standard input for POST requests.
ENVIRONMENT
The following variables will be set in the environment:
| PATH |
This is set to the same value as the PATH variable in the
environment the webserver was started in.
e.g. /usr/local/bin:/usr/bin:/bin |
| SERVER_SOFTWARE |
The name of the webserver software that executed the
CGI script.
e.g. Zeus/3.0 |
| GATEWAY_INTERFACE |
The version of the CGI specification that the webserver
supports. Zeus Server supports the latest CGI/1.1
format.
Value: CGI/1.1 |
| SERVER_PROTOCOL |
The version of the HTTP protocol that the webserver
supports. Zeus Server supports the latest HTTP/1.1
specification. CGI scripts run by the Zeus Server can also
generate responses for newer versions of the HTTP specification.
Value: HTTP/1.1 |
| AUTH_TYPE |
The protocol the webserver uses for client authentication.
Value: Basic. |
| SCRIPT_FILENAME |
The absolute filename of the CGI script being run.
e.g. /usr/local/zeus/cgi/counter.cgi |
| SERVER_NAME |
The DNS name of the virtual server the client sent this request to.
If the virtual server does not have a valid DNS address, it will be
a textual IP-address (e.g. 10.0.0.5).
e.g. www.zeus.co.uk |
| SERVER_PORT |
The port number of the virtual server that the client sent this
request to.
e.g. 80 |
| REQUEST_METHOD |
The HTTP method that client used for this request.
e.g. GET or POST |
| PATH_INFO | The extra path information associated with this request. For example, if the CGI script being executed has a URL of /cgi-bin/counter.cgi and the client makes a request for /cgi-bin/counter.cgi/sales/index.html, this environment variable will be set to /sales/index.html. |
| PATH_TRANSLATED | The extra path information associated with this request translated into an absolute filename. For example if the CGI script being executed has a URL of /cgi-bin/counter.cgi and the client makes a request of /cgi-bin/counter.cgi/sales/index.html and this virtual server has a document root of /disk2/docs, this environment variable will be set to /disk2/docs/sales/index.html. |
| SCRIPT_NAME |
The URL the client requested to execute this script.
e.g. /cgi-bin/counter.cgi |
| QUERY_STRING |
Query information sent as part of the URL for this request. This is
information supplied after the '?' in a URL. This information will
be encoded by the client's browser in the usual fashion.
e.g. open+id+32 |
| REMOTE_HOST |
The DNS name (or textual IP-address) of the client.
e.g. olympus.zeus.co.uk |
| REMOTE_ADDR |
The textual IP-address of the client.
e.g. 192.34.98.1 |
| CONTENT_LENGTH |
The amount of data available on standard input. For GET
requests, this is always zero.
e.g. 382 |
| HTTP_* |
Any request information sent by the client that does not fit into
one of the above variables is added to the environment for the CGI
to access. The client request line is converted to upper-case,
hyphens "-" are converted into underscores
"_" and then it is prefixed with HTTP_ before
being inserted into the environment.
e.g. HTTP_ACCEPT_LANGUAGE=en |
COMMAND LINE ARGUMENTS
If the CGI script has some QUERY_STRING information, and this information does not include an '=' symbol (encoded in the request by the browser from a form input), then the CGI script is also given supplied command line arguments. This is to enable the execution of non-CGI programs as if they were CGIs, and is called an ISINDEX request. Specifically, the QUERY_STRING is split into substrings on the '+' symbol and each substring is from left to right is assigned to a subsequent command line argument.For example, if a CGI has a request with a QUERY_STRING of a+b+c then it will also be provided with argv[1] = "a", argv[2] = "b" and argv[3] == "c".
STANDARD INPUT
Information from the POST method is available to the CGI script from standard input (file descriptor 0 under UNIX). The amount of information available is set in the CONTENT_LENGTH environment variable. This information is encoded in the usual fashion, with spaces converted to '+' symbols and any non-alphanumeric characters converted to %xx where xx is a two-digit hexadecimal string describing the ASCII character it represents.
Output
Output from the CGI script to the webserver is via standard output
(file descriptor 1 under UNIX). The webserver also multiplexes
standard error onto standard output so any errors in the script
processing get sent to the client, this greatly eases debugging of CGI
scripts.
The output from the CGI script consists of two parts, the CGI headers, and the content body.
CGI HEADERS
The CGI headers consist of a sequence of HTTP response lines in any order terminated by either a \r\n\r\n or \n\n or a non-HTTP response line (where \r and \n stand for the ASCII characters 13 and 10 respectively).A HTTP response line has a format <text>: <text>(\n|\r\n).
For example, generally a CGI will output something similar to:
SPECIAL HEADER LINES
If the first line of the CGI output has a special format of HTTP/x.y aaa desc the CGI can return a HTTP response of an arbitrary version of the HTTP protocol. For example, the HTTP/1.2 protocol might support a HTTP response code 420 - Credit Card Invalid. In which case the web server can be extended to support this new format by a CGI script which generates the HTTP response for this error message, such as:The following HTTP response lines are also considered special:
| Response line | Action taken by the webserver |
| Status | Sets the HTTP status code for this response. For example:
|
| Location | Forces a 302 Moved Temporarily HTTP response to be sent
to the client. The Location line should specify where the client's
browser should be redirected to. For example:
|
CONTENT BODY
The content body is the data to be sent to the client, normally a HTML page, but could just as easily be a GIF image for example. If the CGI set a Content-Length header then the content-body should consist of exactly this amount of data.
Notes
For performance reasons, if the CGI script knows at the time of
generating the CGI header the size of the content-body it will output,
it should set a Content-Length line in the headers. This
will let the webserver use the HTTP/1.1 Keep-Alive feature with
browsers that support this performance extension.