The WWW Common Gateway Interface Version 1.1

Abstract

The interface has been in use by the WWW since 1993. This specification defines the interface known as "CGI/1.1".

Notational Conventions and Generic Grammar

The following rules are used throughout this specification to describe basic parsing constructs.

alpha = lowalpha | hialpha
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

OCTET = <any 8-bit byte>
CHAR = <any character>
CTL = <any control character>
SP = <space character>
NL = <newline>
LWSP = SP | NL | <horizontal-tab>
tspecial = "(" | ")" | "@" | "," | ";" | ":" | "\" | <"> | "/" | "[" | "]" | "?" | SP
token = 1*<any CHAR except CTLs or tspecials>
quoted-string = ( <"> *qdtext <"> ) | ( "<" *qatext ">")
qdtext = <any CHAR except <"> and CTLs but including LWSP>
qatext = <any CHAR except "<", ">" and CTLs but including LWSP>

Introduction

The CGI defines the abstract parameters, known as environment variables, which describe the client's request. Together with a concrete programmer interface, this specifies a platform-independent interface between this script and the HTTP server.

The Script URI

The script URI has the syntax of generic-RL as defined in section 2.1 of RFC 1808 [8], with the exception that object parameters and fragment identifiers are not permitted:

<scheme>://<host>:<port>/<path>?<query>

script-uri = protocol "://" SERVER_NAME ":" SERVER_PORT enc-script enc-path-info "?" QUERY_STRING

Define URL-encoding

Environment variables

Case is not signifcant in the names, in that there cannot be two different variable whose names differ in case only. Here they are shown using a canonical representation of capitals plus underscore ("_"). The actual representation of the names is system specific; for a particular system the representation may be defined differently to this.

The standard variables are:

AUTH_TYPE
CONTENT_LENGTH
CONTENT_TYPE
GATEWAY_INTERFACE
HTTP_*
PATH_INFO
PATH_TRANSLATED
QUERY_STRING
REMOTE_ADDR
REMOTE_HOST
REMOTE_IDENT
REMOTE_USER
REQUEST_METHOD
SCRIPT_NAME
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE

AUTH_TYPE

The variable is specific to requests made with HTTP.

If the script URI would require access authentication for external access, then this variable is found from the `auth-scheme' token in the request, otherwise NULL.

AUTH_TYPE = "" | auth-scheme
auth-scheme = "Basic" | token

HTTP access authentication schemes are described in section 11 of the HTTP/1.0 specification [2]. The auth-scheme is not case-sensitive.

CONTENT_LENGTH

The size of the attached entity, if any, in decimal number of octets. If no data is attached, then NULL. The syntax is the same as the HTTP Content-Length header (section 10, HTTP/1.0 specification [2]).

CONTENT_LENGTH = "" | [ 1*digit ]

CONTENT_TYPE

The Internet Media Type [3] of the attached entity. The syntax is the same as the HTTP Content-Type header.

CONTENT_TYPE = "" | media-type
media-type = type "/" subtype *( ";" parameter)
type = token
subtype = token
parameter = attribute "=" value
attribute = token
value = token | quoted-string

The type, subtype and parameter attribute names are not case-sensitive. Parameter values may be case sensitive. Media types and their use in HTTP are described section 3.6 of the HTTP/1.0 specification [2]. Example:

application/x-www-form-urlencoded

There is no default value for this variable. If (and only if) it is unset, then the script may attempt to determine the media type from the data received. If the type remains unknown, then application/octet-stream should be assumed.

GATEWAY_INTERFACE

The version of the CGI specification to which this server complies. Syntax:

GATEWAY_INTERFACE = "CGI" "/" 1*digit "." 1*digit

Note that the major and minor numbers should be treated as separate integers and that each may be incremented higher than a single digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in turn is lower than CGI/12.3. Leading zeros should be ignored by scripts and never generated by servers.

This document defines the 1.1 version of the CGI interface.

Note: the server needs to be able to identify any OS specific parts of the interface, and also any extensions that it provides.

HTTP_*

These variables are specific to requests made with HTTP.

Environment variables with names beginning with "HTTP_" contain header data read from the client, if the protocol used was HTTP. The HTTP header name is converted to upper case, has all occurrences of "-" replaced with "_" and has "HTTP_" prepended to give the environment variable name. The header data may be presented as sent by the client, or may be rewritten in ways which do not change its semantics. For example, the sever may remove comments from the header. The server must, if necessary, change the representation of the data to be appropriate for a CGI environment variable. Interpretation of these variables may depend on the value of SERVER_PROTOCOL.

The server is not required to create environment variables for all the headers that it receives. In particular, it might remove any headers carrying authentication information, such as `Authorization'.

Notes: should there be a requirement not to pass on certain data?
Should the server be required to remove CRLF from folded headers?

PATH_INFO

A path to be interpreted by the CGI script. It identifies the resource or sub-resource to be returned by the CGI script. The syntax and semantics are similar to a decoded HTTP URL `hpath' token (defined in RFC 1738 [4]), with the exception that a PATH_INFO of "/" represents a single void path segment. Otherwise, the leading "/" character is not part of the path.

PATH_INFO = "" | "/" path
path = segment *( "/" segment )
segment = *pchar
pchar = <any CHAR except "/">

The PATH_INFO string is some trailing part of the <path> component of the script URI, derived in some implementation defined manner.

PATH_TRANSLATED

The OS path to the file that httpd would attempt to access were the client to request the absolute URI containing the path PATH_INFO. i.e for a request of

protocol "://" SERVER_NAME ":" SERVER_PORT enc-path-info

where `enc-path-info' is a URL-encoded version of PATH_INFO. If PATH_INFO is NULL then PATH_TRANSLATED is set to NULL.

PATH_TRANSLATED = *CHAR

PATH_TRANSLATED need not be supported by the server. The server may choose to set PATH_TRANSLATED to NULL for reasons of security, or because the path would not be interpretable by a CGI script; such as the object it represented was internal to the server and not visible in the filesystem; or for any other reason.

The algorithm httpd uses to derive PATH_TRANSLATED is obviously system dependent; CGI scripts which use this variable may suffer limited portability.

Note: httpd gets it `wrong' if the translated URI would require authentication.

QUERY_STRING

A URL-encoded search string; the <query> part of the script URI.

QUERY_STRING = query-string
query-string = *qchar
qchar = unreserved | escape | ":" | "@" | "&" | "="
unreserved = alpha | digit | safe | extra
safe = "$" | "-" | "_" | "." | "+"
extra = "!" | "*" | "'" | "(" | ")" | ","
escape = "%" hex hex
hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"

The URL syntax for a search string is described in RFC 1738 [4].

REMOTE_ADDR

The IP address of the agent sending the request to the server. Not necessarily that of the client.

REMOTE_ADDR = hostnumber
hostnumber = digits "." digits "." digits "." digits
digits = 1*digit

REMOTE_HOST

The fully qualified domain name of the agent sending the request to the server, if available, otherwise NULL. Not necessarily that of the client. Fully qualified domain names take the form as described in section 3.5 of RFC 1034 [5] and section 2.1 of RFC 1123 [6]; a sequence of domain labels separated by ".", each domain label starting and ending with an alphanumerical character and possibly also containing "-" characters. The rightmost domain label will never start with a digit. Domain names are not case sensitive.

REMOTE_HOST = "" | hostname
hostname = *( domainlabel ".") toplabel
domainlabel = alphadigit [ *alphahypdigit alphadigit ]
toplabel = alpha [ *alphahypdigit alphadigit ]
alphahypdigit = alphadigit | "-"
alphadigit = alpha | digit

Note: the current documentation only requires this to be the `hostname', rather than the FQDN.

REMOTE_IDENT

The identity information reported about the connection by a RFC 931 [7] request to the remote agent, if available. The server may choose not to support this feature, or not to request the data for efficiency reasons.

REMOTE_IDENT = *CHAR

The data returned is not appropriate for use as authentication information.

REMOTE_USER

This variable is specific to requests made with HTTP.

If AUTH_TPYE is "Basic", then the user-ID sent by the client. If AUTH_TYPE is NULL, then NULL, otherwise undefined.

REMOTE_USER = "" | userid | *OCTET
userid = token

REQUEST_METHOD

This variable is specific to requests made with HTTP.

The method with which the request was made, as described in section 5.1.1 of the HTTP/1.0 specification [2].

REQUEST_METHOD = http-method
http-method = "GET" | "HEAD" | "POST" | extension-method
extension-method = token

The method is case sensitive.

SCRIPT_NAME

A URI path that could identify the CGI script (rather then the particular CGI output). The syntax and semantics are identical to a decoded HTTP URL `hpath' token [4].

SCRIPT_NAME = "" | "/" [ path ]

The leading "/" is not part of the path. It is optional if the path is NULL.

The SCRIPT_NAME string is some leading part of the <path> component of the script URI.

SERVER_NAME

The name for this server, as used in the <host> part of the script URI. Thus either a fully qualified domain name, or an IP address.

SERVER_NAME = hostname | hostnumber

SERVER_PORT

The port on which this request was received, as used in the <port> part of the script URI.

SERVER_PORT = 1*digit

SERVER_PROTOCOL

The name and revision of the information protocol this request came in with.

SERVER_PROTOCOL = HTTP-Version | extension-version
HTTP-Version = "HTTP" "/" 1*digit "." 1*digit
extension-version = protocol "/" 1*digit "." 1*digit
protocol = 1*( alpha | digit | "+" | "-" | "." )

`protocol' is a version of the part of the script URI, and is not case sensitive. By convention, `protocol' is in upper case.

SERVER_SOFTWARE

The name and version of the information server software answering the request (and running the gateway).

SERVER_SOFTWARE = *CHAR

The CGI script command line

search-string = search-word *( "+" search-word )
search-word = 1*schar
schar = xunreserved | escape | ";" | ":" | "@" | "&"
xunreserved = alpha | digit | xsafe | extra
xsafe = "$" | "-" | "_" | "."

If the server cannot create any part of the argument list, then the server should generate no command line information. For example, the number of arguments may greater than operating system or server limitations, or one of the words may not be representable as an argument.

Note: the original documentation did not limit this to a GET or HEAD request

Data input to the CGI script

There will be at least CONTENT_LENGTH bytes available for the script to read. The script is not obliged to read the data, but it must not attempt to read more than CONTENT_LENGTH bytes, even if more data is available.

For non-parsed header (NPH) scripts (see below), the server should attempt to ensure that the script input comes directly from the client, with minimal buffering.

Data output from the CGI script

There are two forms of output that the script can give; non-parsed header (NPH) output, and parsed header output. A server is only required to support the latter; distinguishing between the two types of output (or scripts) is implementation defined.

Non-Parsed Header Output

The server should attempt to ensure that the script output is sent directly to the client, with minimal buffering.

Parsed Header Output

CGI-Response = *( CGI-Header | HTTP-Header ) NL [ Entity-Body ]
CGI-Header = Content-type
| Location
| Status
| extension-header

The CGI headers have the generic syntax:

generic-header = field-name ":" [ field-value ] NL
field-name = 1*<any CHAR, excluding CTLs, SP and ":">
field-value = *( field-content | LWSP )
field-content = * ( token | tspecial | quoted-string)

Content-Type

The Internet Media Type [3] of the entity body.

Content-Type = "Content-Type" ":" media-type NL

Location

This is used to specify to the server that the script is returning a reference to a document rather than an actual document.

Location = "Location" ":" fragment-URI | rel-URL-abs-path NL
fragment-URI = URI [ # fragmentid ]
rel-URL-abs-path = "/" [ URL-path ] [ "?" query-string ]
URL-path = psegment *( "/" psegment )
psegment = *qchar

The location value is either an absolute URI with optional fragment, as defined in RFC 1630 [1], or an absolute path and optional query-string. If an absolute URI is returned by the script, then the server will generate a redirect HTTP response message, and if no entity body is supplied by the script, then the server will produce one. If the Location value is a path, then the server will generate the response that it would have produced in response to a request containing the URI

protocol "://" SERVER_NAME ":" SERVER_PORT rel-URL-abs-path

Status

The Status header is used to indicate to the server what status code it should use in the response message. It should not be sent if the script returns a Location header.

Status = "Status" ":" 3digit SP reason-phrase NL
reason-phrase = *<CHAR, excluding CTLs, NL>

The valid status codes are listed in section 6.1.1 of the HTTP/1.0 specification [2]. If the script does not return a Status header, then "200 OK" should be assumed.

HTTP headers

The script may return any other headers defined by the HTTP/1.0 specification [2]. The server must translate the header data from the CGI header syntax to the HTTP header syntax if these differ. For example, the character sequence for newline (such as Unix's ASCII NL) used by CGI scripts may not be the same as that used by HTTP (ASCII CR followed by LF).

Requirements for servers

The value for SCRIPT_NAME is governed by the server configuration and the location of the script in the OS filesystem. Given this, any access to the partial URI

SCRIPT_NAME extra-path ? query-information

Servers should reject with error 404 any requests that would result in an encoded "/" being decoded into PATH_INFO or SCRIPT_NAME.

Note: this should be made a requirement.

Although the server and the CGI script need not be consistent in their handling of URL paths (client URLs and the PATH_INFO data, respectively), server authors may wish to impose consistency. So the server implementation should define its behaviour for the following cases:

• define any restrictions on allowed characters, in particular whether ASCII NULL is permitted;
• define any restrictions on allowed path segments, in particular whether non-terminal NULL segments are permitted;
• define the behaviour for "." or ".." path segments; i.e. whether they are prohibited, treated as ordinary path segments or interpreted in accordance with the relative URL specification [8];
• define any limits of the implementation, including limits on path or search string lengths, and limits on the volume of headers the server will parse.

Recommendations for scripts

If the output of a form is being processed, check that CONTENT_TYPE is "application/x-www-form-urlencoded" [9].

Note: presumably 400 is the appropriate error code in this case.

As it is impossible for the script to determine the client URI that initiated this request, the script should not return text/html documents containing relative-URL links without including a <BASE> tag in the document.

When returning headers, the script should try to send the CGI headers as soon as possible, and preferably before any HTTP headers. This may help reduce the server's memory requirements.

System-specific standards

AmigaDOS

Environment variables

These are accessed by the dos library routine GetVar. The flags argument should be 0. Case is ignored, but upper case is recommended for compatability with case-sensitive systems.

The current working directory

The current working directory for the script is set to the directory containing the script.

Unix

Environment variables

These are accessed by the C library routine getenv.

The command line

This is accessed using the the argc and argv arguments to main(). The words are have any characters which are `active' in the bourne shell escaped with a backslash.

The current working directory

The current working directory for the script is set to the directory containing the script.

References

[2] Berners-Lee, T., Fielding, R. T. and Frystyk Nielsen, H., `Hypertext Transfer Protocol -- HTTP/1.0', Work in progress (draft-ietf-http-v10-spec-04.txt), MIT/LCS, UC Irvine, October 1995.

[3] Postel, J., `Media Type Registration Procedure', RFC 1590, ISI, March 1994.

[4] Berners-Lee, T., Masinter, L. and McCahill, M., Editors, `Uniform Resource Locators (URL)', RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994.

[5] Mockapetris, P., `Domain Names - Concepts and Facilities', STD 13, RFC 1034, ISI, November 1987.

[6] Braden, R., Editor, `Requirements for Internet Hosts -- Application and Support', STD 3, RFC 1123, IETF, October 1989.

[7] StJohns, M., `Authentication Server', RFC 931, TPSC, January 1985.

[8] Fielding, R., `Relative Uniform Resource Locators', RFC 1808, UC Irving, June 1995.

[9] Berners-Lee, T. and Connolly, D., `Hypertext Markup Language - 2.0', RFC 1866, MIT/W3C, November 1995.