httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@locus.apache.org
Subject cvs commit: httpd-docs-1.3/htdocs/manual/howto cgi.html
Date Sun, 12 Nov 2000 21:39:34 GMT
slive       00/11/12 13:39:34

  Modified:    htdocs/manual/howto cgi.html
  Log:
  Just running this through html-tidy to make it easier to edit by hand.
  
  Revision  Changes    Path
  1.2       +414 -290  httpd-docs-1.3/htdocs/manual/howto/cgi.html
  
  Index: cgi.html
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/howto/cgi.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- cgi.html	2000/11/12 13:15:52	1.1
  +++ cgi.html	2000/11/12 21:39:34	1.2
  @@ -1,315 +1,439 @@
   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  -<HTML>
  -<HEAD>
  -<TITLE>Dynamic Content with CGI</TITLE>
  -<LINK REV="made" HREF="mailto:rbowen@rcbowen.com">
  -</HEAD>
  -
  +<html>
  +<head>
  +<meta name="generator" content="HTML Tidy, see www.w3.org">
  +<title>Dynamic Content with CGI</title>
  +<link rev="made" href="mailto:rbowen@rcbowen.com">
  +</head>
   <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  -<BODY
  - BGCOLOR="#FFFFFF"
  - TEXT="#000000"
  - LINK="#0000FF"
  - VLINK="#000080"
  - ALINK="#FF0000"
  ->
  +<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080"
  +alink="#FF0000">
   <!--#include virtual="header.html" -->
  -<H1 ALIGN="CENTER">Dynamic Content with CGI</H1>
  +<h1 align="CENTER">Dynamic Content with CGI</h1>
  +
  +<a name="__index__"></a> <!-- INDEX BEGIN -->
  + 
  +
  +<ul>
  +<li><a href="#dynamic content with cgi">Dynamic Content with
  +CGI</a></li>
  +
  +<li><a href="#configuring apache to permit cgi">Configuring Apache to
  +permit CGI</a></li>
   
  +<li style="list-style: none">
  +<ul>
  +<li><a href="#scriptalias">ScriptAlias</a></li>
   
  -<A NAME="__index__"></A>
  -<!-- INDEX BEGIN -->
  +<li><a href="#cgi outside of scriptalias directories">CGI outside of
  +ScriptAlias directories</a></li>
   
  -<UL>
  +<li style="list-style: none">
  +<ul>
  +<li><a href=
  +"#explicitly using options to permit cgi execution">Explicitly using
  +Options to permit CGI execution</a></li>
   
  -	<LI><A HREF="#dynamic content with cgi">Dynamic Content with CGI</A></LI>
  -	<LI><A HREF="#configuring apache to permit cgi">Configuring Apache to permit
CGI</A></LI>
  -	<UL>
  +<li><a href="#.htaccess files">.htaccess files</a></li>
  +</ul>
  +</li>
  +</ul>
  +</li>
   
  -		<LI><A HREF="#scriptalias">ScriptAlias</A></LI>
  -		<LI><A HREF="#cgi outside of scriptalias directories">CGI outside of ScriptAlias
directories</A></LI>
  -		<UL>
  +<li><a href="#writing a cgi program">Writing a CGI program</a></li>
   
  -			<LI><A HREF="#explicitly using options to permit cgi execution">Explicitly
using Options to permit CGI execution</A></LI>
  -			<LI><A HREF="#.htaccess files">.htaccess files</A></LI>
  -		</UL>
  +<li style="list-style: none">
  +<ul>
  +<li><a href="#your first cgi program">Your first CGI program</a></li>
  +</ul>
  +</li>
   
  -	</UL>
  +<li><a href="#but it's still not working!">But it's still not
  +working!</a></li>
   
  -	<LI><A HREF="#writing a cgi program">Writing a CGI program</A></LI>
  -	<UL>
  +<li style="list-style: none">
  +<ul>
  +<li><a href="#file permissions">File permissions</a></li>
   
  -		<LI><A HREF="#your first cgi program">Your first CGI program</A></LI>
  -	</UL>
  +<li><a href="#path information">Path information</a></li>
   
  -	<LI><A HREF="#but it's still not working!">But it's still not working!</A></LI>
  -	<UL>
  +<li><a href="#syntax errors">Syntax errors</a></li>
   
  -		<LI><A HREF="#file permissions">File permissions</A></LI>
  -		<LI><A HREF="#path information">Path information</A></LI>
  -		<LI><A HREF="#syntax errors">Syntax errors</A></LI>
  -		<LI><A HREF="#error logs">Error logs</A></LI>
  -	</UL>
  +<li><a href="#error logs">Error logs</a></li>
  +</ul>
  +</li>
   
  -	<LI><A HREF="#what's going on behind the scenes">What's going on behind the
scenes?</A></LI>
  -	<UL>
  +<li><a href="#what's going on behind the scenes">What's going on behind
  +the scenes?</a></li>
   
  -		<LI><A HREF="#environment variables">Environment variables</A></LI>
  -		<LI><A HREF="#stdin and stdout">STDIN and STDOUT</A></LI>
  -	</UL>
  +<li style="list-style: none">
  +<ul>
  +<li><a href="#environment variables">Environment variables</a></li>
   
  -	<LI><A HREF="#cgi modules/libraries">CGI modules/libraries</A></LI>
  -	<LI><A HREF="#for more information">For more information</A></LI>
  -</UL>
  +<li><a href="#stdin and stdout">STDIN and STDOUT</a></li>
  +</ul>
  +</li>
  +
  +<li><a href="#cgi modules/libraries">CGI modules/libraries</a></li>
  +
  +<li><a href="#for more information">For more information</a></li>
  +</ul>
  +
   <!-- INDEX END -->
  +<hr>
  +<h1><a name="dynamic content with cgi">Dynamic Content with
  +CGI</a></h1>
  +
  +<p>The CGI (Common Gateway Interface) is the simplest, and most common,
  +way to put dynamic content on your web site. This document will be an
  +introduction to setting up CGI on your Apache web server, and getting
  +started writing CGI programs.</p>
  +
  +<p>For all the gory details about CGI, see the CGI specification, at <a
  +href=
  +"http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</a></p>
  +
  +<hr>
  +<h1><a name="configuring apache to permit cgi">Configuring Apache to
  +permit CGI</a></h1>
  +
  +<p>In order to get your CGI programs to work properly, you'll need to
  +have Apache configured to permit CGI execution. There are several ways
  +to do this.</p>
  +
  +<h2><a name="scriptalias">ScriptAlias</a></h2>
  +
  +<p>The <code>ScriptAlias</code> directive tells Apache that a
  +particular directory is set aside for CGI programs. Apache will assume
  +that every file in this directory is a CGI program, and will attempt to
  +execute it, when that particular resource is requested by a client.</p>
  +
  +<p>The <code>ScriptAlias</code> direcive looks like:</p>
  +
  +<pre>
  +        ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
  +</pre>
  +
  +<p>The example shown is from your default <code>httpd.conf</code>
  +configuration file, if you installed Apache in the default location.
  +The <code>ScriptAlias</code> directive is much like the
  +<code>Alias</code> directive, which defines a URL prefix that is to
  +mapped to a particular directory. <code>Alias</code> and
  +<code>ScriptAlias</code> are usually used for directories that are
  +outside of the <code>DocumentRoot</code> directory. The difference
  +between <code>Alias</code> and <code>ScriptAlias</code> is that
  +<code>ScriptAlias</code> has the added meaning that everything under
  +that URL prefix will be considered a CGI program. So, the example above
  +tells Apache that any request for a resource beginning with
  +<code>/cgi-bin/</code> should be served from the directory
  +<code>/usr/local/apache/cgi-bin/</code>, and should be treated as a CGI
  +program.</p>
  +
  +<p>For example, if the URL
  +<code>http://dev.rcbowen.com/cgi-bin/test.pl</code> is requested,
  +Apache will attempt to execute the file
  +<code>/usr/local/apache/cgi-bin/test.pl</code> and return the output.
  +Of course, the file will have to exist, and be executable, and return
  +output in a particular way, or Apache will return an error message.</p>
  +
  +<h2><a name="cgi outside of scriptalias directories">CGI outside of
  +ScriptAlias directories</a></h2>
  +
  +<p>Occasionally you will want to have CGI programs outside of
  +<code>ScriptAlias</code>'ed directories. Usually, this will be for the
  +purpose of letting users have web content in their home directories
  +with the <code>UserDir</code> directive. If they want to have their own
  +CGI programs, but don't have access to the main <code>cgi-bin</code>
  +directory, they will need to be able to run CGI programs elsewhere.</p>
  +
  +<h3><a name=
  +"explicitly using options to permit cgi execution">Explicitly using
  +Options to permit CGI execution</a></h3>
  +
  +<p>You could explicitly use the <code>Options</code> directive, inside
  +your main server configuration file, to specify that CGI execution was
  +permitted in a particular directory:</p>
   
  -<HR>
  -<P>
  -<H1><A NAME="dynamic content with cgi">Dynamic Content with CGI</A></H1>
  -<P>The CGI (Common Gateway Interface) is the simplest, and most common, way to put
  -dynamic content on your web site. This document will be an introduction
  -to setting up CGI on your Apache web server, and getting started writing
  -CGI programs.</P>
  -<P>For all the gory details about CGI, see the CGI specification, at
  -<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</A></P>
  -<P>
  -<HR>
  -<H1><A NAME="configuring apache to permit cgi">Configuring Apache to permit
CGI</A></H1>
  -<P>In order to get your CGI programs to work properly, you'll need to have Apache
  -configured to permit CGI execution. There are several ways to do this.</P>
  -<P>
  -<H2><A NAME="scriptalias">ScriptAlias</A></H2>
  -<P>The <CODE>ScriptAlias</CODE> directive tells Apache that a particular
directory is
  -set aside for CGI programs. Apache will assume that every file in this 
  -directory is a CGI program, and will attempt to execute it, when that particular
  -resource is requested by a client.</P>
  -<P>The <CODE>ScriptAlias</CODE> direcive looks like:</P>
  -<PRE>
  -        ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/</PRE>
  -<P>The example shown is from your default <CODE>httpd.conf</CODE> configuration
file, if you
  -installed Apache in the default location. 
  -The <CODE>ScriptAlias</CODE> directive is much like the <CODE>Alias</CODE>
directive, which defines
  -a URL prefix that is to mapped to a particular directory. <CODE>Alias</CODE>
and <CODE>ScriptAlias</CODE>
  -are usually used for directories that are outside of the <CODE>DocumentRoot</CODE>
directory.
  -The difference between <CODE>Alias</CODE> and <CODE>ScriptAlias</CODE>
is
  -that <CODE>ScriptAlias</CODE> has the added meaning that everything under that
URL prefix
  -will be considered a CGI program.
  -So, the example above tells Apache that any request
  -for a resource beginning with <CODE>/cgi-bin/</CODE> should be served from
the directory
  -<CODE>/usr/local/apache/cgi-bin/</CODE>, and should be treated as a CGI program.</P>
  -<P>For example, if the URL <CODE>http://dev.rcbowen.com/cgi-bin/test.pl</CODE>
is requested,
  -Apache will attempt to execute the file <CODE>/usr/local/apache/cgi-bin/test.pl</CODE>
and
  -return the output. Of course, the file will have to exist, and be executable,
  -and return output in a particular way, or Apache will return an error message.</P>
  -<P>
  -<H2><A NAME="cgi outside of scriptalias directories">CGI outside of ScriptAlias
directories</A></H2>
  -<P>Occasionally you will want to have CGI programs outside of <CODE>ScriptAlias</CODE>'ed
  -directories. Usually, this will be for the purpose of letting users have web
  -content in their home directories with the <CODE>UserDir</CODE> directive.
If they 
  -want to have their own CGI programs, but don't have access to the main 
  -<CODE>cgi-bin</CODE> directory, they will need to be able to run CGI programs
  -elsewhere.</P>
  -<P>
  -<H3><A NAME="explicitly using options to permit cgi execution">Explicitly using
Options to permit CGI execution</A></H3>
  -<P>You could explicitly use the <CODE>Options</CODE> directive, inside
your main server
  -configuration file, to specify that CGI execution was permitted in a particular
  -directory:</P>
  -<PRE>
  +<pre>
           &lt;Directory /usr/local/apache/htdocs/somedir&gt;
                   Options +ExecCGI
  -        &lt;/Directory&gt;</PRE>
  -<P>The above directive tells Apache to permit the execution of CGI files.
  -You will also need to tell the server what files are CGI files.
  -This is done with the <CODE>AddHandler</CODE> directive:</P>
  -<PRE>
  -     AddHandler cgi-script cgi pl</PRE>
  -<P>
  -<H3><A NAME=".htaccess files">.htaccess files</A></H3>
  -<P>A <CODE>.htaccess</CODE> file is a way to set configuration directives
on a per-directory
  -basis. When Apache serves a resource, it looks in the directory from which it
  -is serving a file for a file called <CODE>.htaccess</CODE>, and, if it finds
it, it will
  -apply directives found therein. <CODE>.htaccess</CODE> files can be permitted
with the
  -<CODE>AllowOverride</CODE> directive, which specifies what types of directives
  -can appear in these files, or if they are not allowed at all. To permit
  -the directive we will need for this purpose, the following configuration
  -will be needed in your main server configuration:</P>
  -<PRE>
  -        AllowOverride Options</PRE>
  -<P>In the <CODE>.htaccess</CODE> file, you'll need the following directive:</P>
  -<PRE>
  -        Options +ExecCGI</PRE>
  -<P>which tells Apache that execution of CGI programs is permitted in this
  -directory.</P>
  -<P>
  -<HR>
  -<H1><A NAME="writing a cgi program">Writing a CGI program</A></H1>
  -<P>There are two main differences between ``regular'' programming, and CGI programming.</P>
  -<P>First, all output from your CGI program must be preceeded by a MIME-type header.
  -This is HTTP header that tells the client what sort of content it is receiving.
  -Most of the time, this will look like:</P>
  -<PRE>
  -        Content-type: text/html</PRE>
  -<P>Secondly, your output needs to be in HTML, or some other format that a browser

  -will be able to display. Most of the time, this will be HTML, but occasionally
  -you might write a CGI program that outputs a gif image, or other non-HTML content.</P>
  -<P>Apart from those two things, writing a CGI program will look a lot like any other
  -program that you might write.</P>
  -<P>
  -<H2><A NAME="your first cgi program">Your first CGI program</A></H2>
  -<P>The following is an example CGI program that prints one line to your browser.
  -Type in the following, save it to a file called <CODE>first.pl</CODE>, and
put it in your
  -<CODE>cgi-bin</CODE> directory.</P>
  -<PRE>
  +        &lt;/Directory&gt;
  +</pre>
  +
  +<p>The above directive tells Apache to permit the execution of CGI
  +files. You will also need to tell the server what files are CGI files.
  +This is done with the <code>AddHandler</code> directive:</p>
  +
  +<pre>
  +     AddHandler cgi-script cgi pl
  +</pre>
  +
  +<h3><a name=".htaccess files">.htaccess files</a></h3>
  +
  +<p>A <code>.htaccess</code> file is a way to set configuration
  +directives on a per-directory basis. When Apache serves a resource, it
  +looks in the directory from which it is serving a file for a file
  +called <code>.htaccess</code>, and, if it finds it, it will apply
  +directives found therein. <code>.htaccess</code> files can be permitted
  +with the <code>AllowOverride</code> directive, which specifies what
  +types of directives can appear in these files, or if they are not
  +allowed at all. To permit the directive we will need for this purpose,
  +the following configuration will be needed in your main server
  +configuration:</p>
  +
  +<pre>
  +        AllowOverride Options
  +</pre>
  +
  +<p>In the <code>.htaccess</code> file, you'll need the following
  +directive:</p>
  +
  +<pre>
  +        Options +ExecCGI
  +</pre>
  +
  +<p>which tells Apache that execution of CGI programs is permitted in
  +this directory.</p>
  +
  +<hr>
  +<h1><a name="writing a cgi program">Writing a CGI program</a></h1>
  +
  +<p>There are two main differences between ``regular'' programming, and
  +CGI programming.</p>
  +
  +<p>First, all output from your CGI program must be preceeded by a
  +MIME-type header. This is HTTP header that tells the client what sort
  +of content it is receiving. Most of the time, this will look like:</p>
  +
  +<pre>
  +        Content-type: text/html
  +</pre>
  +
  +<p>Secondly, your output needs to be in HTML, or some other format that
  +a browser will be able to display. Most of the time, this will be HTML,
  +but occasionally you might write a CGI program that outputs a gif
  +image, or other non-HTML content.</p>
  +
  +<p>Apart from those two things, writing a CGI program will look a lot
  +like any other program that you might write.</p>
  +
  +<h2><a name="your first cgi program">Your first CGI program</a></h2>
  +
  +<p>The following is an example CGI program that prints one line to your
  +browser. Type in the following, save it to a file called
  +<code>first.pl</code>, and put it in your <code>cgi-bin</code>
  +directory.</p>
  +
  +<pre>
           #!/usr/bin/perl
  -        print &quot;Content-type: text/html\r\n\r\n&quot;;
  -        print &quot;Hello, World.&quot;;</PRE>
  -<P>Even if you are not familiar with Perl, you should be able to see what is happening
  -here. The first line tells Apache (or whatever shell you happen to be running 
  -under) that this program can be executed by feeding the file to the interpreter
  -found at the location <CODE>/usr/bin/perl</CODE>. The second line prints the
content-type
  -declaration we talked about, followed by two carriage-return newline pairs. This
  -puts a blank line after the header, to indicate the end of the HTTP headers, and 
  -the beginning of the body. The third line prints the string ``Hello, World.'' And
  -that's the end of it.</P>
  -<P>If you open your favorite browser and tell it to get the address</P>
  -<PRE>
  -        <A HREF="http://your.server.com/cgi-bin/first.pl">http://your.server.com/cgi-bin/first.pl</A></PRE>
  -<P>or wherever you put your file, you will see the one line <CODE>Hello, World.</CODE>
appear
  -in your browser window. It's not very exciting, but once you get that working, 
  -you'll have a good chance of getting just about anything working.</P>
  -<P>
  -<HR>
  -<H1><A NAME="but it's still not working!">But it's still not working!</A></H1>
  -<P>If your program still is not working, here are some of the things that you need
  -to look for in order to resolve your problem.</P>
  -<P>
  -<H2><A NAME="file permissions">File permissions</A></H2>
  -<P>Remember that the server does not run as you. That is, when the server starts
up,
  -it is running with the permissions of an unpriveleged user - usually ``nobody'', or
  -``www'' - and so it will need extra permissions to execute files that are owned 
  -by you. Usually, the way to give a file sufficient permissions to be executed
  -by ``nobody'' is to give everyone execute permission on the file:</P>
  -<PRE>
  -        chmod a+x first.pl</PRE>
  -<P>Also, if your program reads from, or writes to, any other files, those files
  -will need to have the correct permissions to permit this.</P>
  -<P>
  -<H2><A NAME="path information">Path information</A></H2>
  -<P>When you run a program from your command line, you have certain information that
  -is passed to the shell without you thinking about it. For example, you have a path, 
  -which tells the shell where it can look for files that you reference.</P>
  -<P>When a program runs through the web server as a CGI program, it does not have
that
  -path. Any programs that you invoke in your CGI program (like 'sendmail', for example)
  -will need to be specified by a full path, so that the shell can find them
  -when it attempts to execute your CGI program.</P>
  -<P>A common manifestation of this is the path to the script interpreter
  -(often <CODE>perl</CODE>) indicated in the first line of your CGI program,
which will
  -look something like:</P>
  -<PRE>
  -     #!/usr/bin/perl</PRE>
  -<P>Make sure that this is in fact the path to the interpreter.</P>
  -<P>
  -<H2><A NAME="syntax errors">Syntax errors</A></H2>
  -<P>Most of the time when a CGI program fails, it's because of a problem with the
  -program itself. This is particularly true once you get the hang of this CGI stuff,
  -and no longer make the above two mistakes. Always attempt to run your program
  -from the command line before you test if via a browser. This will elimate most
  -of your problems.</P>
  -<P>
  -<H2><A NAME="error logs">Error logs</A></H2>
  -<P>The error logs are your friend. Anything that goes wrong generatesa message
  -in the error log. You should always look there first. If the place where
  -you are hosting your web site does not permit you access to the error log,
  -you should probably host your site somewhere else. Learn to read the error
  -logs, and you'll find that almost all of your problems are quickly
  -identified, and quickly solved.</P>
  -<P>
  -<HR>
  -<H1><A NAME="what's going on behind the scenes">What's going on behind the
scenes?</A></H1>
  -<P>As you become more advanced in CGI programming, it will become useful to understand
  -more about what's happening behind the scenes. Specifically, how the browser and
  -server communicate with one another. Because although it's all very well
  -to write a program that prints ``Hello, World.'', it's not particularly useful.</P>
  -<P>
  -<H2><A NAME="environment variables">Environment variables</A></H2>
  -<P>Environment variables are values that float around you as you use your
  -computer. They are useful things like your path (where the computer searches
  -for a the actual file implementing a command when you type it), your username,
  -your terminal type, and so on. For a full list of your normal, every day
  -environment variables, type <CODE>env</CODE> at a command prompt.</P>
  -<P>During the CGI transaction, the server and the browser also set environment
  -variables, so that they can communicate with one another. These are things
  -like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS,
  -WebSite), the name of the CGI program that is being run, and so on.</P>
  -<P>These variables are available to the CGI programmer, and are half of the
  -story of the client-server communication. The complete list of required
  -variables is at <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/env.html">http://hoohoo.ncsa.uiuc.edu/cgi/env.html</A></P>
  -<P>This simple Perl CGI program will display all of the environment variables that
  -are being passed around. Note that some variables are required, while others
  -are optional, so you may see some variables listed that were not in the
  -official list.</P>
  -<PRE>
  +        print "Content-type: text/html\r\n\r\n";
  +        print "Hello, World.";
  +</pre>
  +
  +<p>Even if you are not familiar with Perl, you should be able to see
  +what is happening here. The first line tells Apache (or whatever shell
  +you happen to be running under) that this program can be executed by
  +feeding the file to the interpreter found at the location
  +<code>/usr/bin/perl</code>. The second line prints the content-type
  +declaration we talked about, followed by two carriage-return newline
  +pairs. This puts a blank line after the header, to indicate the end of
  +the HTTP headers, and the beginning of the body. The third line prints
  +the string ``Hello, World.'' And that's the end of it.</p>
  +
  +<p>If you open your favorite browser and tell it to get the address</p>
  +
  +<pre>
  +        <a href=
  +"http://your.server.com/cgi-bin/first.pl">http://your.server.com/cgi-bin/first.pl</a>
  +</pre>
  +
  +<p>or wherever you put your file, you will see the one line
  +<code>Hello, World.</code> appear in your browser window. It's not very
  +exciting, but once you get that working, you'll have a good chance of
  +getting just about anything working.</p>
  +
  +<hr>
  +<h1><a name="but it's still not working!">But it's still not
  +working!</a></h1>
  +
  +<p>If your program still is not working, here are some of the things
  +that you need to look for in order to resolve your problem.</p>
  +
  +<h2><a name="file permissions">File permissions</a></h2>
  +
  +<p>Remember that the server does not run as you. That is, when the
  +server starts up, it is running with the permissions of an unpriveleged
  +user - usually ``nobody'', or ``www'' - and so it will need extra
  +permissions to execute files that are owned by you. Usually, the way to
  +give a file sufficient permissions to be executed by ``nobody'' is to
  +give everyone execute permission on the file:</p>
  +
  +<pre>
  +        chmod a+x first.pl
  +</pre>
  +
  +<p>Also, if your program reads from, or writes to, any other files,
  +those files will need to have the correct permissions to permit
  +this.</p>
  +
  +<h2><a name="path information">Path information</a></h2>
  +
  +<p>When you run a program from your command line, you have certain
  +information that is passed to the shell without you thinking about it.
  +For example, you have a path, which tells the shell where it can look
  +for files that you reference.</p>
  +
  +<p>When a program runs through the web server as a CGI program, it does
  +not have that path. Any programs that you invoke in your CGI program
  +(like 'sendmail', for example) will need to be specified by a full
  +path, so that the shell can find them when it attempts to execute your
  +CGI program.</p>
  +
  +<p>A common manifestation of this is the path to the script interpreter
  +(often <code>perl</code>) indicated in the first line of your CGI
  +program, which will look something like:</p>
  +
  +<pre>
        #!/usr/bin/perl
  -     print &quot;Content-type: text/html\n\n&quot;;
  -     foreach $key (keys %ENV) {
  -          print &quot;$key --&gt; $ENV{$key}&lt;br&gt;&quot;;
  -     }</PRE>
  -<P>
  -<H2><A NAME="stdin and stdout">STDIN and STDOUT</A></H2>
  -<P>Other communication between the server and the client happens over standard
  -input (<CODE>STDIN</CODE>) and standard output (<CODE>STDOUT</CODE>).
In normal everyday context,
  -<CODE>STDIN</CODE> means the keyboard, or a file that a program is given to
act on,
  -and <CODE>STDOUT</CODE> usually means the console or screen.</P>
  -<P>When you <CODE>POST</CODE> a web form to a CGI program, the data in
that form is
  -bundled up into a special format and gets delivered to your CGI program
  -over <CODE>STDIN</CODE>. The program then can process that data as though it
wsa coming
  -in from the keyboard, or from a file</P>
  -<P>The ``special format'' is very simple. A field name and its value are joined
  -together with an equals (=) sign, and pairs of values are joined together
  -with an ampersand (&amp;). Inconvenient characters like spaces, ampersands, and
  -equals signs, are converted into their hex equivalent so that they don't gum
  -up the works. The whole data string might look something like:</P>
  -<PRE>
  -     name=Rich%20Bowen&amp;city=Lexington&amp;state=KY&amp;sidekick=Squirrel%20Monkey</PRE>
  -<P>You'll sometimes also see this type of string appended to the a URL. When
  -that is done, the server puts that string into the environment variable
  -called <CODE>QUERY_STRING</CODE>. That's called a <CODE>GET</CODE>
request. Your HTML form
  -specifies whether a <CODE>GET</CODE> or a <CODE>POST</CODE> is
used to deliver the data, by
  -setting the <CODE>METHOD</CODE> attribute in the <CODE>FORM</CODE>
tag.</P>
  -<P>Your program is then responsible for splitting that string up into useful
  -information. Fortunately, there are libraries and modules available to
  -help you process this data, as well as handle other of the aspects of
  -your CGI program.</P>
  -<P>
  -<HR>
  -<H1><A NAME="cgi modules/libraries">CGI modules/libraries</A></H1>
  -<P>When you write CGI programs, you should consider using a code library,
  -or module, to do most of the grunt work for you. This leads to fewer
  -errors, and faster development.</P>
  -<P>If you're writing CGI programs in Perl, modules are available on CPAN 
  -(http://www.cpan.org/). The most popular module for this purpose is
  -CGI.pm. You might also consider CGI::Lite, which implements a
  -minimal set of functionality, which is all you need in most programs.</P>
  -<P>If you're writing CGI programs in C, there are a variety of options.
  -One of these is the CGIC library, from <A HREF="http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</A></P>
  -<P>
  -<HR>
  -<H1><A NAME="for more information">For more information</A></H1>
  -<P>There are a large number of CGI resources on the web. You can discuss CGI
  -problems with other users on the Usenet group
  -comp.infosystems.www.authoring.cgi. And the -servers mailing list from the
  -HTML Writers Guild is a great source of answers to your questions. You can 
  -find out more at <A HREF="http://www.hwg.org/lists/hwg-servers/">http://www.hwg.org/lists/hwg-servers/</A></P>
  -<P>And, of course, as I mentioned above, you should probably read the CGI
  -specification, which you can find at 
  -<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</A></P>
  -<P>When you post a question about a CGI problem that you're having, whether
  -to a mailing list, or to a newsgroup, make sure you provide enough information
  -about what happened, what you expected to happen, and how what actually happened
  -was different, what server you're running, what language your CGI program 
  -was in, and, if possible, the offending code. This will make finding your 
  -problem much simpler.</P>
  +</pre>
  +
  +<p>Make sure that this is in fact the path to the interpreter.</p>
   
  -</BODY>
  +<h2><a name="syntax errors">Syntax errors</a></h2>
  +
  +<p>Most of the time when a CGI program fails, it's because of a problem
  +with the program itself. This is particularly true once you get the
  +hang of this CGI stuff, and no longer make the above two mistakes.
  +Always attempt to run your program from the command line before you
  +test if via a browser. This will elimate most of your problems.</p>
  +
  +<h2><a name="error logs">Error logs</a></h2>
  +
  +<p>The error logs are your friend. Anything that goes wrong generatesa
  +message in the error log. You should always look there first. If the
  +place where you are hosting your web site does not permit you access to
  +the error log, you should probably host your site somewhere else. Learn
  +to read the error logs, and you'll find that almost all of your
  +problems are quickly identified, and quickly solved.</p>
  +
  +<hr>
  +<h1><a name="what's going on behind the scenes">What's going on behind
  +the scenes?</a></h1>
  +
  +<p>As you become more advanced in CGI programming, it will become
  +useful to understand more about what's happening behind the scenes.
  +Specifically, how the browser and server communicate with one another.
  +Because although it's all very well to write a program that prints
  +``Hello, World.'', it's not particularly useful.</p>
  +
  +<h2><a name="environment variables">Environment variables</a></h2>
  +
  +<p>Environment variables are values that float around you as you use
  +your computer. They are useful things like your path (where the
  +computer searches for a the actual file implementing a command when you
  +type it), your username, your terminal type, and so on. For a full list
  +of your normal, every day environment variables, type <code>env</code>
  +at a command prompt.</p>
  +
  +<p>During the CGI transaction, the server and the browser also set
  +environment variables, so that they can communicate with one another.
  +These are things like the browser type (Netscape, IE, Lynx), the server
  +type (Apache, IIS, WebSite), the name of the CGI program that is being
  +run, and so on.</p>
  +
  +<p>These variables are available to the CGI programmer, and are half of
  +the story of the client-server communication. The complete list of
  +required variables is at <a href=
  +"http://hoohoo.ncsa.uiuc.edu/cgi/env.html">http://hoohoo.ncsa.uiuc.edu/cgi/env.html</a></p>
  +
  +<p>This simple Perl CGI program will display all of the environment
  +variables that are being passed around. Note that some variables are
  +required, while others are optional, so you may see some variables
  +listed that were not in the official list.</p>
  +
  +<pre>
  +     #!/usr/bin/perl
  +     print "Content-type: text/html\n\n";
  +     foreach $key (keys %ENV) {
  +          print "$key --&gt; $ENV{$key}&lt;br&gt;";
  +     }
  +</pre>
  +
  +<h2><a name="stdin and stdout">STDIN and STDOUT</a></h2>
  +
  +<p>Other communication between the server and the client happens over
  +standard input (<code>STDIN</code>) and standard output
  +(<code>STDOUT</code>). In normal everyday context, <code>STDIN</code>
  +means the keyboard, or a file that a program is given to act on, and
  +<code>STDOUT</code> usually means the console or screen.</p>
  +
  +<p>When you <code>POST</code> a web form to a CGI program, the data in
  +that form is bundled up into a special format and gets delivered to
  +your CGI program over <code>STDIN</code>. The program then can process
  +that data as though it wsa coming in from the keyboard, or from a
  +file</p>
  +
  +<p>The ``special format'' is very simple. A field name and its value
  +are joined together with an equals (=) sign, and pairs of values are
  +joined together with an ampersand (&amp;). Inconvenient characters like
  +spaces, ampersands, and equals signs, are converted into their hex
  +equivalent so that they don't gum up the works. The whole data string
  +might look something like:</p>
  +
  +<pre>
  +     name=Rich%20Bowen&amp;city=Lexington&amp;state=KY&amp;sidekick=Squirrel%20Monkey
  +</pre>
  +
  +<p>You'll sometimes also see this type of string appended to the a URL.
  +When that is done, the server puts that string into the environment
  +variable called <code>QUERY_STRING</code>. That's called a
  +<code>GET</code> request. Your HTML form specifies whether a
  +<code>GET</code> or a <code>POST</code> is used to deliver the
data, by
  +setting the <code>METHOD</code> attribute in the <code>FORM</code>
  +tag.</p>
  +
  +<p>Your program is then responsible for splitting that string up into
  +useful information. Fortunately, there are libraries and modules
  +available to help you process this data, as well as handle other of the
  +aspects of your CGI program.</p>
  +
  +<hr>
  +<h1><a name="cgi modules/libraries">CGI modules/libraries</a></h1>
  +
  +<p>When you write CGI programs, you should consider using a code
  +library, or module, to do most of the grunt work for you. This leads to
  +fewer errors, and faster development.</p>
  +
  +<p>If you're writing CGI programs in Perl, modules are available on
  +CPAN (http://www.cpan.org/). The most popular module for this purpose
  +is CGI.pm. You might also consider CGI::Lite, which implements a
  +minimal set of functionality, which is all you need in most
  +programs.</p>
  +
  +<p>If you're writing CGI programs in C, there are a variety of options.
  +One of these is the CGIC library, from <a href=
  +"http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</a></p>
  +
  +<hr>
  +<h1><a name="for more information">For more information</a></h1>
  +
  +<p>There are a large number of CGI resources on the web. You can
  +discuss CGI problems with other users on the Usenet group
  +comp.infosystems.www.authoring.cgi. And the -servers mailing list from
  +the HTML Writers Guild is a great source of answers to your questions.
  +You can find out more at <a href=
  +"http://www.hwg.org/lists/hwg-servers/">http://www.hwg.org/lists/hwg-servers/</a></p>
  +
  +<p>And, of course, as I mentioned above, you should probably read the
  +CGI specification, which you can find at <a href=
  +"http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</a></p>
  +
  +<p>When you post a question about a CGI problem that you're having,
  +whether to a mailing list, or to a newsgroup, make sure you provide
  +enough information about what happened, what you expected to happen,
  +and how what actually happened was different, what server you're
  +running, what language your CGI program was in, and, if possible, the
  +offending code. This will make finding your problem much simpler.</p>
  +</body>
  +</html>
   
  -</HTML>
  
  
  

Mime
View raw message