CGI Programming

A quick guide to how CGI works and why it's a nightmare to debug.
Was the Directory Configured for CGI?

By this point, we know that the program is executable, that it sends the correct MIME header before any other output, and that it seems to work in at least a basic way if invoked from the command line.

So assuming that there aren't any logic errors—which are still a significant hurdle to overcome, even when all of these logistical errors are out of the way—we should make sure that the program is running in a directory that has been configured to run CGI programs!

First, let's think about how most programs work: When you request a document from a server, it generally makes sure that the file exists. If the file does exist, the server returns the document to the browser; if it doesn't, the server returns an error message indicating that the file wasn't found.

CGI programs work slightly differently, though—in this case, the server returns any output returned by the program, rather than the program itself. Thus the server attempts to execute the file as if it were a program, and then takes whatever that program returns and passes it on to the user.

Now the question: How does the server know which files it should simply return, and which should be executed first?

On most systems, that distinction is made by assigning several directories to be for CGI programs. These directories, traditionally called “cgi-bin”, contain the binaries (i.e., the executables) for our CGI programs. Anything contained in these directories is considered to be a program, and is executed; anything sitting elsewhere is considered to be a text file. Thus if your program is sitting in a non-CGI directory, its contents will be sent to the user as if they were a text file, displaying approximately what you would see if you were to use the Unix more command. By the same token, if you were to put one of your HTML documents in the CGI directory, requesting it would almost certainly cause an error, since the server would attempt to execute it!

Another approach, which is less common, allows users to place CGI programs anywhere on the system, so long as their filenames have certain suffixes—for example, .cgi or .pl. The good news is that this allows users to have their own CGI programs without forcing the system administrator to configure a new CGI directory each time a user wants to have a counter, or other common CGI program, on his or her home page. However, CGI programs can be a security risk, particularly when any user on the system can write or install whatever programs he or she might want. Most system administrators prefer being bothered with requests to create new CGI directories to the potential security holes that might exist with the other approach.

In either of these cases—the cgi-bin directory approach or the “any directory” approach—users who experience problems with their CGI programs should make sure that their programs are in the right directories, that the CGI directories are set up for CGI programs, and that they have the right suffixes. I often get e-mail from people who wonder why they get the error cannot perform POST method to the non-script whenever they try to execute their CGI program. What this admittedly terse and cryptic error message is trying to say is, “You tried to send data from an HTML form to a file that doesn't appear to be a program. If you want to set this up as a program, make sure to define it as such on your system by using the appropriate configuration!”

The solution, then, is to make sure that your program is in one of the directories declared to be for CGI programs. Your system administrator should be able to do this by using the ScriptAlias directive (for NCSA httpd and Apache), or the Exec directive (for CERN httpd). Once that is done, your program should run—although once again, I should stress that just because all of the above steps are in order doesn't mean that your program will work! It just means that your server will be able to run it, and that the program will return at least some results to your browser.

Next Time

That's all the space we have for this installment. Next month, we will discuss the httpd error log, to which our programs send all of their error messages and warnings when things go wrong. We will see how to read the error log, and how to understand what it is saying when our programs don't work when we expect them to—as well as how to use it to our advantage to make sure that our programs work correctly.

Reuven M. Lerner has been playing with the Web since early 1993, when it seemed like more of a fun toy than the world's Next Great Medium. He currently works from his apartment in Haifa, Israel as an independent Internet and Web consultant. When not working on the Web or informally volunteering with school-age children, he enjoys reading (on just about any subject, but especially computers, politics, and philosophy—separately and together), cooking, solving crossword puzzles, and hiking. You can reach him at or