Adapted from the CGI Introduction and Primer documents at http://hoohoo.ncsa.uiuc.edu/cgi/.

What is CGI?

The Common Gateway Interface, or CGI, is a standard for external gateway programs to interface with information servers such as HTTP servers. A plain HTML document that the Web daemon retrieves is static, which means it exists in a constant state: a text file that doesn't change. A CGI program, on the other hand, is executed in real-time, so that it can output dynamic information.

CGI is a mechanism for running programs on a WWW server. Typical applications include accessing a database, submitting an order, or posting messages to a bulletin board.

CGI is a common standard agreed and supported by all major HTTPDs.

HTTP Headers

HTTP is the protocol of the Web, by which Servers and Clients (typically browsers) communicate. An HTTP transaction comprises a Request sent by the Client to the Server, and a Response returned from the Server to the Client.

Every HTTP request and response includes a message header, describing the message. These are processed by the HTTPD, and may often be mostly ignored by CGI applications (but see below).

A message body may also be included:

1. A HEAD or GET request sends only a header. Any form data is encoded in an HTTP_QUERY_STRING header field, which is available to the CGI program as an environment variable QUERY_STRING.
2. A POST request sends both header and body. The body typically comprises data entered by a user in a form.
3. A HEAD request does not expect a body in the response.
4. A GET or POST request will accept a response with or without a body, according to the header. The body of a response is typically an HTML document.

Most HTTP request headers are passed to the CGI script as environment variables. Some are guaranteed by the CGI spec. Others are server, browser and/or application dependent.

The HTTPD will insert necessary response headers on your behalf, always provided it is configured to do so.

However, it is conventional for servers to insert the Content-type header based on a page's filename, and for CGI scripts it will often be absent or wrong. Hence the usual advice is to print an explicit Content-type header.

GET requests should always be idempotent on the server. This means that whereas one GET request might (rarely) change some state on the Server, two or more identical requests will have no further effect.

In the case of a POST request, form data is passed on STDIN, so the script should read from there (the number of bytes to be read is given by the Content-length header). In the case of GET, the data is passed in the environment variable QUERY_STRING. The content-type (application/x-www-form-urlencoded) is identical for GET and POST requests.

The Common Gateway Interface

How do I get information from the server?

Each time a client requests the URL corresponding to your CGI program, the server will execute it in real-time. The output of your program will go more or less directly to the client.

A common misconception about CGI is that you can send command-line options and arguments to your program, such as

command% myprog -qa blorf

CGI uses the command line for other purposes and thus this is not directly possible. Instead, CGI uses environment variables to send your program its parameters. The two major environment variables you will use for this purpose are:

• QUERY_STRING
  

  QUERY_STRING is defined as anything which follows the first ? in the URL. This information could be added either by an ISINDEX document, or by an HTML form (with the GET action). It could also be manually embedded in an HTML anchor which references your gateway. This string will usually be an information query, i.e. what the user wants to search for in the archie databases, or perhaps the encoded results of your feedback GET form.

  This string is encoded in the standard URL format of changing spaces to +, and encoding special characters with %xx hexadecimal encoding. You will need to decode it in order to use it.

  If your gateway is not decoding results from a FORM, you will also get the query string decoded for you onto the command line. This means that each word of the query string will be in a different section of ARGV. For example, the query string "forms rule" would be given to your program with argv[1]="forms" and argv[2]="rule". If you choose to use this, you do not need to do any processing on the data before using it.

• PATH_INFO
  

  CGI allows for extra information to be embedded in the URL for your gateway which can be used to transmit extra context-specific information to the scripts. This information is usually made available as "extra" information after the path of your gateway in the URL. This information is not encoded by the server in any way.

  The most useful example of PATH_INFO is transmitting file locations to the CGI program. To illustrate this, let's say I have a CGI program on my server called /cgi-bin/foobar that can process files residing in the DocumentRoot of the server. I need to be able to tell foobar which file to process. By including extra path information to the end of the URL, foobar will know the location of the document relative to the DocumentRoot via the PATH_INFO environment variable, or the actual path to the document via the PATH_TRANSLATED environment variable which the server generates for you.

How do I send my document back to the client?

I have found that the most common error in beginners' CGI programs is not properly formatting the output so the server can understand it.

CGI programs can return a myriad of document types. They can send back an image to the client, and HTML document, a plaintext document, or perhaps even an audio clip. They can also return references to other documents. The client must know what kind of document you're sending it so it can present it accordingly. In order for the client to know this, your CGI program must tell the server what type of document it is returning.

In order to tell the server what kind of document you are sending back, whether it be a full document or a reference to one, CGI requires you to place a short header on your output. This header is ASCII text, consisting of lines separated by either linefeeds or carriage returns (or both) followed by a single blank line. The output body then follows in whatever native format.

• A full document with a corresponding MIME type
  

  In this case, you must tell the server what kind of document you will be outputting via a MIME type. Common MIME types are things such as text/html for HTML, and text/plain for straight ASCII text.

  For example, to send back HTML to the client, your output should read:

  Content-type: text/html
  
  <HTML><HEAD>
  <TITLE>output of HTML from CGI script</TITLE>
  </HEAD><BODY>
  <H1>Sample output</H1>
  What do you think of <STRONG>this?</STRONG>
  </BODY></HTML>
  

• A reference to another document
  

  Instead of outputting the document, you can just tell the browser where to get the new one, or have the server automatically output the new one for you.

  For example, say you want to reference a file on your Gopher server. In this case, you should know the full URL of what you want to reference and output something like:

  Content-type: text/html
  Location: gopher://httprules.foobar.org/0
  
  <HTML><HEAD>
  <TITLE>Sorry...it moved</TITLE>
  </HEAD><BODY>
  <H1>Go to gopher instead</H1>
  Now available at
  <A HREF="gopher://httprules.foobar.org/0">a new location</A>
  on our gopher server.
  </BODY></HTML>
  

  However, today's browsers are smart enough to automatically throw you to the new document, without ever seeing the above since. If you get lazy and don't want to output the above HTML, NCSA HTTPd will output a default one for you to support older browsers.

  If you want to reference another file (not protected by access authentication) on your own server, you don't have to do nearly as much work. Just output a partial (virtual) URL, such as the following:

  Location: /dir1/dir2/myfile.html
  

  The server will act as if the client had not requested your script, but instead requested http://yourserver/dir1/dir2/myfile.html. It will take care of most everything, such as looking up the file type and sending the appropriate headers. Just be sure that you output the second blank line.

CGI Links

CGI Links on
CGI Primer (ASCII text)
CGI Interface Specification
CGI Test program (UNIX shell script)
Sample CGI Test program output CGI
Run the CGI Test program on this server

Back to the CTEC1906 Page