Common Gateway Interface

A web server that supports CGI can be configured to interpret(解析) a URL that it serves as a reference to CGI scripts. A common convention is to have a cgi-bin/ directory at the base of the directory tree and treat all executable files within it as CGI scripts. Another popular convention is to use filename extensions; for instance, if CGI scripts are consistently given the extension .cgi, the web server can be configured to interpret all such files as CGI scripts.

In the case of HTTP PUT or POSTs, the user-submitted data is provided to the program via the standard input. In any case, according to the CGI standard, data is passed into the program using certain, specific environment variables. This is in contrast to typical execution, where command-line arguments are used and the environment is in constant upheaval and cannot be trusted. Apache creates a small, efficient subset of the environment variables passed to it and adds details pertinent to the execution of the program.

[edit]Simple Example

The following CGI program shows all the environment variables passed by the web server:

 #!/usr/local/bin/perl
 ##
 ##  printenv—demo CGI program which just prints its environment
 ##
 #
 print "Content-type: text/plain\n\n";
 foreach $var (sort(keys(%ENV))) {
   $val = $ENV{$var};
   $val =~ s|\n|\\n|g;
   $val =~ s|"|\\"|g;
   print "${var}=\"${val}\"\n";
 }

• If a web browser request the document at http://example.com/cgi-bin/printenv.pl/ponylove?q=20%C001er&moar=kitties, the following information is returned:

COMSPEC="C:\Windows\system32\cmd.exe"
DOCUMENT_ROOT="C:/Program Files (x86)/Apache Software Foundation/Apache2.2/htdocs"
GATEWAY_INTERFACE="CGI/1.1"
HOME="/home/SYSTEM"
HTTP_ACCEPT="text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
HTTP_ACCEPT_CHARSET="ISO-8859-1,utf-8;q=0.7,*;q=0.7"
HTTP_ACCEPT_ENCODING="gzip, deflate"
HTTP_ACCEPT_LANGUAGE="en-us,en;q=0.5"
HTTP_CONNECTION="keep-alive"
HTTP_COOKIE="ShowBlockedFriends=1; oneswarmView=list; swarmsPerPage=6; Community contacts=true; OneSwarm=Y6XAAAAAX; friend_list_open=true"
HTTP_HOST="example.com"
HTTP_USER_AGENT="Mozilla/5.0 (Windows NT 6.1; WOW64; rv:5.0) Gecko/20100101 Firefox/5.0"
PATH="/home/SYSTEM/bin:/bin:/cygdrive/c/progra~2/php:/cygdrive/c/windows/system32:..."
PATHEXT=".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC"
PATH_INFO="/ponylove"
PATH_TRANSLATED="C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs\ponylove"
QUERY_STRING="q=20%C001er&moar=kitties"
REMOTE_ADDR="127.0.0.1"
REMOTE_PORT="63555"
REQUEST_METHOD="GET"
REQUEST_URI="/cgi-bin/printenv.pl/ponylove?q=20%C001er&moar=kitties"
SCRIPT_FILENAME="C:/Program Files (x86)/Apache Software Foundation/Apache2.2/cgi-bin/printenv.pl"
SCRIPT_NAME="/cgi-bin/printenv.pl"
SERVER_ADDR="127.0.0.1"
SERVER_ADMIN="(server admin's email address)"
SERVER_NAME="127.0.0.1"
SERVER_PORT="80"
SERVER_PROTOCOL="HTTP/1.1"
SERVER_SIGNATURE=""
SERVER_SOFTWARE="Apache/2.2.19 (Win32) PHP/5.2.17"
SYSTEMROOT="C:\Windows"
TERM="cygwin"
WINDIR="C:\Windows"

From the environment, we see that the web browser is Firefox running on Windows 7 running on a PC, the web server is an Apache running on a system which emulates Unix, and the CGI script is named cgi-bin/printenv.pl.

The program could then generate any content, that written to its standard output, will be transmitted by the web server to the browser.

[edit]Environment variables passed to a CGI program

• Server specific variables:
  • SERVER_SOFTWARE — name/version of HTTP server.
  • SERVER_NAME — host name of the server, may be dot-decimal IP address.
  • GATEWAY_INTERFACE — CGI/version.
• Request specific variables:
  • SERVER_PROTOCOL — HTTP/version.
  • SERVER_PORT — TCP port (decimal).
  • REQUEST_METHOD — name of HTTP method (see above).
  • PATH_INFO — path suffix, if appended to URL after program name and a slash.
  • PATH_TRANSLATED — corresponding full path as supposed by server, if PATH_INFO is present.
  • SCRIPT_NAME — relative path to the program, like /cgi-bin/script.cgi.
  • QUERY_STRING — the part of URL after ? character. May be composed of *name=value pairs separated with ampersands (such as var1=val1&var2=val2…) when used to submit form data transferred via GET method as defined by HTML application/x-www-form-urlencoded.
  • REMOTE_HOST — host name of the client, unset if server did not perform such lookup.
  • REMOTE_ADDR — IP address of the client (dot-decimal).
  • AUTH_TYPE — identification type, if applicable.
  • REMOTE_USER used for certain AUTH_TYPEs.
  • REMOTE_IDENT — see ident, only if server performed such lookup.
  • CONTENT_TYPE — MIME type of input data if PUT or POST method are used, as provided via HTTP header.
  • CONTENT_LENGTH — similarly, size of input data (decimal, in octets) if provided via HTTP header.
  • Variables passed by user agent (HTTP_ACCEPT, HTTP_ACCEPT_LANGUAGE, HTTP_USER_AGENT, HTTP_COOKIE and possibly others) contain values of corresponding HTTP headers and therefore have the same sense.

[edit]Output format

The program returns the result to the web server in the form of standard output, prefixed by a header and a blank line.

The header is encoded in the same way as an HTTP header and must include the MIME type of the document returned.^[1] The headers are generally forwarded with the response back to the user, supplemented by the web server.

[edit]Example

An example of a CGI program is one implementing a wiki. The user agent requests the name of an entry; the server retrieves the source of that entry's page (if one exists), transforms it into HTML, and sends the result.