What is CGI

http://hoohoo.ncsa.uiuc.edu/cgi/intro.html

 

---

 

The Common Gateway Interface, or CGI, is a standard for external gateway programs to interface with information servers such as HTTP servers.

The current version is CGI/1.1.

---

Overview

---

The Common Gateway Interface (CGI) is a standard for interfacing external applications with information servers, such as HTTP or Web 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.

For example, let's say that you wanted to "hook up" your Unix database to the World Wide Web, to allow people from all over the world to query it. Basically, you need to create a CGI program that the Web daemon will execute to transmit information to the database engine, and receive the results back again and display them to the client. This is an example of a gateway, and this is where CGI, currently version 1.1, got its origins.

The database example is a simple idea, but most of the time rather difficult to implement. There really is no limit as to what you can hook up to the Web. The only thing you need to remember is that whatever your CGI program does, it should not take too long to process. Otherwise, the user will just be staring at their browser waiting for something to happen.

---

Specifics

---

Since a CGI program is executable, it is basically the equivalent of letting the world run a program on your system, which isn't the safest thing to do. Therefore, there are some security precautions that need to be implemented when it comes to using CGI programs. Probably the one that will affect the typical Web user the most is the fact that CGI programs need to reside in a special directory, so that the Web server knows to execute the program rather than just display it to the browser. This directory is usually under direct control of the webmaster, prohibiting the average user from creating CGI programs. There are other ways to allow access to CGI scripts, but it is up to your webmaster to set these up for you. At this point, you may want to contact them about the feasibility of allowing CGI access.

If you have a version of the NCSA HTTPd server distribution, you will see a directory called /cgi-bin. This is the special directory mentioned above where all of your CGI programs currently reside. A CGI program can be written in any language that allows it to be executed on the system, such as:

• C/C++
• Fortran
• PERL
• TCL
• Any Unix shell
• Visual Basic
• AppleScript

It just depends what you have available on your system. If you use a programming language like C or Fortran, you know that you must compile the program before it will run. If you look in the /cgi-src directory that came with the server distribution, you will find the source code for some of the CGI programs in the /cgi-bin directory. If, however, you use one of the scripting languages instead, such as PERL, TCL, or a Unix shell, the script itself only needs to reside in the /cgi-bin directory, since there is no associated source code. Many people prefer to write CGI scripts instead of programs, since they are easier to debug, modify, and maintain than a typical compiled program.

 

 

CGI Documentation

If you have no idea what CGI is, you should read this introduction.

Once you have a basic idea of what CGI is and what you can use it for, you should read this primer which will help you get started writing your own gateways.

If you are interested in handling the output of HTML forms with your CGI program, you will want to read this guide to handling forms with CGI programs.

Security is a crucial issue when writing CGI programs. Please read these tips on how to write CGI programs which do not allow malicious users to abuse them.

When you get more advanced, you should read the interface specification which will help you utilize CGI to the fullest extent. If you are a server software author, it will help you add CGI compliance to your information server.

There is now also a tutorial for writing ErrorDocument handling CGI scripts.

---

 

Examples of CGI behavior and programs

You may wish to look at this page of examples which demonstrate how the client URL affects the interface variables.

We have created an archive of CGI programs on our FTP server. These programs were written by various people around the world in a variety of programming languages. Some of the entries are libraries which may make writing your CGI program easier.

You can now search the CGI documentation contained herein. Click here to search now.

If you would like to submit one of your CGI programs to the archive, you should first package it with any documentation, copyright notices, etc. Then, upload it to hoohoo.ncsa.uiuc.edu into the directory /incoming/cgi and send mail to [e-mail] with a short description of what the file is.

 

http://hoohoo.ncsa.uiuc.edu/cgi/primer.html

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.

  If you do want to reference a document that is protected by access authentication, you will need to have a full URL in the Location:, since the client and the server need to re-transact to establish that you access to the referenced document.

Advanced usage: If you would like to output headers such as Expires or Content-encoding, you can if your server is compatible with CGI/1.1. Just output them along with Location or Content-type and they will be sent back to the client.