THE COMMON GATEWAY INTERFACE (CGI)
FREQUENTLY ASKED QUESTIONS (FAQ) LIST
This copy generated: Mon Jun 19 21:26:39 1995
_________________________________________________________________
Contents
* General Questions
1. How can I learn about CGI?
2. My script works fine when I run it from my shell, but when I
try to run it from my browser, I get a generic error message
(like "Server Error 500"), or the browser just lists the
source of the script. How am I supposed to know what's wrong?
* Forms
1. Do different browsers handle forms submissions differently?
* Environment Variables
1. Can I get the email addresses of the people who visit my
site? (or, Can sites I visit get my email address?)
* Object Headers
1. What does the "malformed header from script" error mean, and
how can I get rid of it?
* Language-Specific Questions
1. Resources for C Programmers
2. Resources for Perl Programmers
3. Resources for Python Programmers
4. Resources for TCL Programmers
* Platform-Specific Questions
1. I'm trying to make a CGI script for MacHTTP, and I'm having
trouble. Are there materials for MacHTTP CGI programmers?
_________________________________________________________________
General Questions
How can I learn about CGI?
For a list of online materials relating to CGI programming,
please see the CGI Programmer's Reference. Online materials are
far more likely to be up-to-date, though they are sometimes
more terse than a beginner would like. Every CGI programmer
should read the CGI documentation at
.
There are several hardcopy publications that discuss CGI
programming:
1. Managing Internet Information Services, by Cricket Liu, Jerry
Peek, Russ Jones, Bryan Buus and Adrian Nye, published by
O'Reilly & Associates (1st Edition December 1994, 668
pages, ISBN: 1-56592-062-7, $29.95), spends a chapter (24
pages) discussing gateways and forms. It includes clear
examples and good illustrations, though it is more of an
introduction than a complete reference. (The rest of the book
is excellent, too.)
2. Netscape Communications' documentation for their Netsite
servers provides an excellent appendix (43 pages) on CGI
programming. The manual is available through their online
order form, by calling 1-800-NETSITE (both methods for North
American customers only), or by calling +1-415-428-4330
(international customers). The price is $30.00.
My script works fine when I run it from my shell, but when I try to
run it from my browser, I get a generic error message (like
"Server Error 500"), or the browser just lists the source of
the script. How I supposed to know what's wrong?
Once you've determined that your script works from a shell
command-line, there are a few common problems to look for:
1. Is your script readable and executable by your server?
When you execute your script from a shell command-line, it
runs under your user-id and it can use any resource you can.
Since public-access CGI scripts can be executed by any user
on the Web, your web server probably runs under a special
user-id (usually "nobody") with a reduced set of privileges.
In general, CGI scripts need to be world-readable and
world-executable to work. In addition, any other programs
that your script calls -- including the interpreter (i.e.,
"#!/usr/bin/perl") -- need to be world-readable and
executable as well. See your local 'chmod(1)' man page if you
need help with setting permissions.
2. Is it in a directory that the server can reach?
See above. The directory in which your script resides needs
to be world-readable and world-executable.
3. Is that directory ScriptAliased or ExecCGI-enabled?
These terms refer to configuration options in the NCSA
srm.conf file. (Other servers may use different methods of
server resource management.) A "ScriptAliased" directory is
one in which every file is executed as a CGI script. A
directory with "ExecCGI" enabled allows files with certain
filename extensions to be executed as scripts. In short, you
can't just write a script and expect it to run -- your server
must know that your file is a script. Contact your server
administrator or look over your server documentation for more
information.
4. If it returns data to the browser, does it send a
Content-type header?
This is most likely the problem if you are getting a
"malformed header from script" error.
5. Have you checked the server's error log for a more specific
error message?
Error messages from scripts are sent to STDERR -- usually
just to your screen. When a browser executes a script and the
script encounters an error, however, the server redirects
STDERR to its error log. Use a utility like "grep" to search
the error log for references to your script.
6. Have you tried returning error messages to the browser as
HTML?
If a script runs but some parts of it don't work, try sending
error messages to standard output, maybe enclosed in
tags. Particularly, look for operations
that make use of system resources, change directories, read
files, etc., and have them complain loudly if their attempts
to do so fail.
_________________________________________________________________
Forms
Do different browsers handle forms submissions differently?
Yes. Glenn Trewitt has written a suite of tests to evaluate
handling of forms, the results of which can be found at
.
The results are available sorted by browser and by test, as
well as in matrix format.
_________________________________________________________________
Environment Variables
Can I get the email addresses of the people who visit my site? (OR,
can sites I visit get my email address?)
It depends on the browser. Certain browsers send an environment
variable, HTTP_FROM, which contains the user's email address
as entered in their "Preferences." The draft HTTP 1.0
specification, at
, gives some information on the
planned specification for request headers; and at
, the same document warns against
abuse of this information.
Please see the browser survey for information on which browsers
send this and other environment variables.
_________________________________________________________________
Object Headers
What does the "malformed header from script" error mean, and how can I
get rid of it?
This is the most frequent error new CGI programmers encounter.
It usually arises when the programmer writes a script that
returns some HTML when called -- in other words, a script that
generates a Web page on the fly.
"Header" refers to the HTTP object header lines in a server's
response to a client's request. The server sends several lines
of "metainformation" describing the content that will follow, a
blank line, and then the requested object. As with news and
mail, the header and the body are always separated by a blank
line.
CGI scripts that wish to return information to clients are
required to:
1. send a header line, Content-type:, describing with a MIME
Content-type the object that will follow (for instance, if
the script wanted to return HTML, this header would read,
"Content-type: text/html");
2. a blank line; and
3. the desired content.
A Perl script that generated HTML, then, would use the
following line to declare its Content-type:
print "Content-type: text/html\n\n";
The Content-type declaration must always be the first line sent
to standard output, if the script intends to return any
information to the client.
_________________________________________________________________
Language-Specific Questions
Resources for C Programmers
EIT distributes a C library for CGI programmers at
.
Resources for Perl Programmers
The most commonly-used Perl CGI resource is Steven Brenner's
cgi-lib.pl, a library of routines for manipulating form
submissions. The library is available at
.
Somewhat off topic, Roy Fielding has developed libwww-perl, a
library of Perl 4 packages for programming WWW clients and
tools. Distribution information can be found at
.
Resources for Python Programmers
Michael McLay distributes a Python CGI
class from . He
also lists some other Python/WWW resources at
.
Resources for TCL Programmers
There is a page on processing CGI arguments under TCL at
.
_________________________________________________________________
Platform-Specific Questions
I'm trying to make a CGI script for MacHTTP, and I'm having trouble.
Are there materials for MacHTTP CGI programmers?
Yes. MacHTTP does have a number of differences from other
servers in its handling of forms and CGI applications.
Fortunately, Jon Wiederspan, author of the outstanding WWW
Developer Resources, has written a tutorial on extending
MacHTTP, which can be found at
. Jon is an excellent writer, and his tutorial is
worthwhile for new and old programmers alike.
_________________________________________________________________
HTML 2.0 Checked!
Copyright 1995 Marc Hedlund,