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 Thu, 16 Nov 2000 22:19:15 GMT
slive       00/11/16 14:19:14

  Modified:    htdocs/manual/howto cgi.html
  Log:
  1. Go from CGI script back to CGI program.  We'll see how many times
  we can reverse that decision.
  2. Take the white space and punctuation out of the internal links.
  3. A couple small content changes.
  Submitted by:	Chris Pepper, Joshua Slive
  
  Revision  Changes    Path
  1.5       +95 -95    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.4
  retrieving revision 1.5
  diff -u -d -b -u -r1.4 -r1.5
  --- cgi.html	2000/11/12 23:54:17	1.4
  +++ cgi.html	2000/11/16 22:19:13	1.5
  @@ -14,68 +14,67 @@
    
   
   <ul>
  -<li><a href="#dynamic content with cgi">Dynamic Content with
  +<li><a href="#dynamiccontentwithcgi">Dynamic Content with
   CGI</a></li>
   
  -<li><a href="#configuring apache to permit cgi">Configuring Apache to
  +<li><a href="#configuringapachetopermitcgi">Configuring Apache to
   permit CGI</a>
   
   <ul>
   <li><a href="#scriptalias">ScriptAlias</a></li>
   
  -<li><a href="#cgi outside of scriptalias directories">CGI outside of
  +<li><a href="#cgioutsideofscriptaliasdirectories">CGI outside of
   ScriptAlias directories</a>
   
   <ul>
  -<li><a href=
  -"#explicitly using options to permit cgi execution">Explicitly using
  +<li><a href="#explicitlyusingoptionstopermitcgiexecution">Explicitly using
   Options to permit CGI execution</a></li>
   
  -<li><a href="#.htaccess files">.htaccess files</a></li>
  +<li><a href="#htaccessfiles">.htaccess files</a></li>
   </ul>
   </li>
   </ul>
   </li>
   
  -<li><a href="#writing a cgi script">Writing a CGI script</a>
  +<li><a href="#writingacgiprogram">Writing a CGI program</a>
   
   <ul>
  -<li><a href="#your first cgi script">Your first CGI script</a></li>
  +<li><a href="#yourfirstcgiprogram">Your first CGI program</a></li>
   </ul>
   </li>
   
  -<li><a href="#but it's still not working!">But it's still not
  +<li><a href="#butitsstillnotworking">But it's still not
   working!</a>
   
   <ul>
  -<li><a href="#file permissions">File permissions</a></li>
  +<li><a href="#filepermissions">File permissions</a></li>
   
  -<li><a href="#path information">Path information</a></li>
  +<li><a href="#pathinformation">Path information</a></li>
   
  -<li><a href="#syntax errors">Syntax errors</a></li>
  +<li><a href="#syntaxerrors">Syntax errors</a></li>
   
  -<li><a href="#error logs">Error logs</a></li>
  +<li><a href="#errorlogs">Error logs</a></li>
   </ul>
   </li>
   
  -<li><a href="#what's going on behind the scenes">What's going on behind
  +<li><a href="#whatsgoingonbehindthescenes">What's going on behind
   the scenes?</a>
   
   <ul>
  -<li><a href="#environment variables">Environment variables</a></li>
  +<li><a href="#environmentvariables">Environment variables</a></li>
   
  -<li><a href="#stdin and stdout">STDIN and STDOUT</a></li>
  +<li><a href="#stdinandstdout">STDIN and STDOUT</a></li>
   </ul>
   </li>
   
  -<li><a href="#cgi modules/libraries">CGI modules/libraries</a></li>
  +<li><a href="#cgimoduleslibraries">CGI modules/libraries</a></li>
   
  -<li><a href="#for more information">For more information</a></li>
  +<li><a href="#formoreinformation">For more information</a></li>
   </ul>
   
   <!-- INDEX END -->
   <hr>
  -<h2><a name="dynamic content with cgi">Dynamic Content with
  +<h2><a name="dynamiccontentwithcgi">Dynamic Content with
   CGI</a></h2>
   
   <table border="1">
  @@ -95,24 +94,25 @@
   </td></tr></table>
   
   <p>The CGI (Common Gateway Interface) defines a way for a web server
  -to interact with external content-generating programs.  It 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 scripts.</p>
  +to interact with external content-generating programs, which are often
  +referred to as CGI programs or CGI scripts.  It 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>
   
   <hr>
  -<h2><a name="configuring apache to permit cgi">Configuring Apache to
  +<h2><a name="configuringapachetopermitcgi">Configuring Apache to
   permit CGI</a></h2>
   
  -<p>In order to get your CGI scripts to work properly, you'll need to
  +<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>
   
   <h3><a name="scriptalias">ScriptAlias</a></h3>
   
   <p>The <code>ScriptAlias</code> directive tells Apache that a
  -particular directory is set aside for CGI scripts. Apache will assume
  -that every file in this directory is a CGI script, and will attempt to
  +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> directive looks like:</p>
  @@ -130,11 +130,11 @@
   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 script. So, the example above
  +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
  -script.</p>
  +program.</p>
   
   <p>For example, if the URL
   <code>http://dev.rcbowen.com/cgi-bin/test.pl</code> is requested,
  @@ -143,22 +143,21 @@
   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>
   
  -<h3><a name="cgi outside of scriptalias directories">CGI outside of
  +<h3><a name="cgioutsideofscriptaliasdirectories">CGI outside of
   ScriptAlias directories</a></h3>
   
  -<p>CGI scripts are often restricted to <code>ScriptAlias</code>'ed
  +<p>CGI programs are often restricted to <code>ScriptAlias</code>'ed
   directories for security reasons.  In this way, administrators can
  -tightly control who is allowed to use CGI scripts.  However, if the
  +tightly control who is allowed to use CGI programs.  However, if the
   proper security precautions are taken, there is no reason why
  -CGI scripts cannot be run from arbitrary directories.  For example,
  +CGI programs cannot be run from arbitrary directories.  For example,
   you may wish to let users have web content in their home directories
   with the <code>UserDir</code> directive. If they want to have their
  -own CGI scripts, but don't have access to the main
  +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
  -scripts elsewhere.</p>
  +programs elsewhere.</p>
   
  -<h3><a name=
  -"explicitly using options to permit cgi execution">Explicitly using
  +<h3><a name="explicitlyusingoptionstopermitcgiexecution">Explicitly using
   Options to permit CGI execution</a></h3>
   
   <p>You could explicitly use the <code>Options</code> directive, inside
  @@ -175,13 +174,13 @@
   files. You will also need to tell the server what files are CGI files.
   The following <code>AddHandler</code> directive tells the server
   to treat all files with the <code>cgi</code> or <code>pl</code>
  -extension as CGI scripts:</p>
  +extension as CGI programs:</p>
   
   <pre>
        AddHandler cgi-script cgi pl
   </pre>
   
  -<h3><a name=".htaccess files">.htaccess files</a></h3>
  +<h3><a name="htaccessfiles">.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
  @@ -205,16 +204,16 @@
           Options +ExecCGI
   </pre>
   
  -<p>which tells Apache that execution of CGI scripts is permitted in
  +<p>which tells Apache that execution of CGI programs is permitted in
   this directory.</p>
   
   <hr>
  -<h2><a name="writing a cgi script">Writing a CGI script</a></h2>
  +<h2><a name="writingacgiprogram">Writing a CGI program</a></h2>
   
   <p>There are two main differences between ``regular'' programming, and
   CGI programming.</p>
   
  -<p>First, all output from your CGI script must be preceded by a
  +<p>First, all output from your CGI program must be preceded 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>
   
  @@ -224,15 +223,15 @@
   
   <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 script that outputs a gif
  +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 script will look a lot
  +<p>Apart from those two things, writing a CGI program will look a lot
   like any other program that you might write.</p>
   
  -<h3><a name="your first cgi script">Your first CGI script</a></h3>
  +<h3><a name="yourfirstcgiprogram">Your first CGI program</a></h3>
   
  -<p>The following is an example CGI script that prints one line to your
  +<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>
  @@ -256,7 +255,7 @@
   <p>If you open your favorite browser and tell it to get the address</p>
   
   <pre>
  -        http://www.example.com/cgi-bin/first.pl</a>
  +        http://www.example.com/cgi-bin/first.pl
   </pre>
   
   <p>or wherever you put your file, you will see the one line
  @@ -265,37 +264,38 @@
   getting just about anything working.</p>
   
   <hr>
  -<h2><a name="but it's still not working!">But it's still not
  +<h2><a name="butitsstillnotworking">But it's still not
   working!</a></h2>
   
   <p>There are four basic things that you may see in your browser when
  -you try to access your CGI script from the web:</p>
  +you try to access your CGI program from the web:</p>
   
   <dl>
  -<dt>The output of your CGI script</dt>
  +<dt>The output of your CGI program</dt>
   <dd>Great!  That means everything worked fine.<br><br></dd>
   
  -<dt>The source code of your CGI script</dt> 
  -<dd>That means that you have not properly configured Apache to process
  -your CGI script.  Reread the section on <a
  -href="#configuring%20apache%20to%20permit%20cgi">configuring
  -Apache</a> and try to find what you missed.<br><br></dd>
  +<dt>The source code of your CGI program or a "POST Method Not Allowed"
  +message</dt> 
  +<dd>That means that you have not properly configured
  +Apache to process your CGI program.  Reread the section on <a
  +href="#configuringapachetopermitcgi">configuring Apache</a> and try to
  +find what you missed.<br><br></dd>
   
   <dt>A message starting with "Forbidden"</dt> <dd>That means that there
  -is a permissions problem.  Check the <a href="#error%20logs">Apache
  +is a permissions problem.  Check the <a href="#errorlogs">Apache
   error log</a> and the section below on <a
  -href="#file%20permissions">file permissions</a>.<br><br></dd>
  +href="#filepermissions">file permissions</a>.<br><br></dd>
   
   <dt>A message saying "Internal Server Error"</dt> <dd>If you check the
  -<a href="#error%20logs">Apache error log</a>, you will probably find
  +<a href="#errorlogs">Apache error log</a>, you will probably find
   that it says "Premature end of script headers", possibly along with an
  -error message generated by your CGI script.  In this case, you will
  +error message generated by your CGI program.  In this case, you will
   want to check each of the below sections to see what might be preventing
  -your CGI script from emitting the proper HTTP headers.</dt>
  +your CGI program from emitting the proper HTTP headers.</dt>
   </dl>
   
   
  -<h3><a name="file permissions">File permissions</a></h3>
  +<h3><a name="filepermissions">File permissions</a></h3>
   
   <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 unprivileged
  @@ -313,30 +313,30 @@
   this.</p>
   
   <p>The exception to this is when the server is configured to use <a
  -href="../suexec.html">suexec</a>.  This program allows CGI scripts to
  +href="../suexec.html">suexec</a>.  This program allows CGI programs to
   be run under different user permissions, depending on which virtual
   host or user home directory they are located in.  Suexec has very
   strict permission checking, and any failure in that checking will
  -result in your CGI scripts failing with an "Internal Server Error".
  +result in your CGI programs failing with an "Internal Server Error".
   In this case, you will need to check the suexec log file to see what
   specific security check is failing.</p>
   
  -<h3><a name="path information">Path information</a></h3>
  +<h3><a name="pathinformation">Path information</a></h3>
   
   <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 script runs through the web server as a CGI script, it does
  -not have that path. Any programs that you invoke in your CGI script
  +<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 script.</p>
  +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
  -script, which will look something like:</p>
  +program, which will look something like:</p>
   
   <pre>
        #!/usr/bin/perl
  @@ -344,15 +344,15 @@
   
   <p>Make sure that this is in fact the path to the interpreter.</p>
   
  -<h3><a name="syntax errors">Syntax errors</a></h3>
  +<h3><a name="syntaxerrors">Syntax errors</a></h3>
   
  -<p>Most of the time when a CGI script fails, it's because of a problem
  -with the script itself. This is particularly true once you get the
  +<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 script from the command line before you
  +Always attempt to run your program from the command line before you
   test if via a browser. This will eliminate most of your problems.</p>
   
  -<h3><a name="error logs">Error logs</a></h3>
  +<h3><a name="errorlogs">Error logs</a></h3>
   
   <p>The error logs are your friend. Anything that goes wrong generates
   message in the error log. You should always look there first. If the
  @@ -362,16 +362,16 @@
   problems are quickly identified, and quickly solved.</p>
   
   <hr>
  -<h2><a name="what's going on behind the scenes">What's going on behind
  +<h2><a name="whatsgoingonbehindthescenes">What's going on behind
   the scenes?</a></h2>
   
   <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 script that prints
  +Because although it's all very well to write a program that prints
   ``Hello, World.'', it's not particularly useful.</p>
   
  -<h3><a name="environment variables">Environment variables</a></h3>
  +<h3><a name="environmentvariables">Environment variables</a></h3>
   
   <p>Environment variables are values that float around you as you use
   your computer. They are useful things like your path (where the
  @@ -383,7 +383,7 @@
   <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 script that is being
  +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
  @@ -391,8 +391,8 @@
   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 script will display all of the environment
  -variables that are being passed around.  Two similar scripts are
  +<p>This simple Perl CGI program will display all of the environment
  +variables that are being passed around.  Two similar programs are
   included in the <code>cgi-bin</code> directory of the Apache
   distribution. Note that some variables are required, while others are
   optional, so you may see some variables listed that were not in the
  @@ -408,7 +408,7 @@
        }
   </pre>
   
  -<h3><a name="stdin and stdout">STDIN and STDOUT</a></h3>
  +<h3><a name="stdinandstdout">STDIN and STDOUT</a></h3>
   
   <p>Other communication between the server and the client happens over
   standard input (<code>STDIN</code>) and standard output
  @@ -416,9 +416,9 @@
   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 script, the data in
  +<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 script over <code>STDIN</code>. The script then can process
  +your CGI program over <code>STDIN</code>. The program then can process
   that data as though it was coming in from the keyboard, or from a
   file</p>
   
  @@ -441,30 +441,30 @@
   setting the <code>METHOD</code> attribute in the <code>FORM</code>
   tag.</p>
   
  -<p>Your script is then responsible for splitting that string up into
  +<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 script.</p>
  +aspects of your CGI program.</p>
   
   <hr>
  -<h2><a name="cgi modules/libraries">CGI modules/libraries</a></h2>
  +<h2><a name="cgimoduleslibraries">CGI modules/libraries</a></h2>
   
  -<p>When you write CGI scripts, you should consider using a code
  +<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 scripts 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
  -scripts.</p>
  +<p>If you're writing CGI programs in Perl, modules are available on <a
  +href="http://www.cpan.org/">CPAN</a>. 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 scripts in C, there are a variety of options.
  +<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>
  -<h2><a name="for more information">For more information</a></h2>
  +<h2><a name="formoreinformation">For more information</a></h2>
   
   <p>There are a large number of CGI resources on the web. You can
   discuss CGI problems with other users on the Usenet group
  @@ -474,7 +474,7 @@
   "http://www.hwg.org/lists/hwg-servers/">http://www.hwg.org/lists/hwg-servers/</a></p>
   
   <p>And, of course, you should probably read the CGI specification,
  -which has all the details on the operation of CGI scripts.  You can
  +which has all the details on the operation of CGI programs.  You can
   find the original version at the <a href=
   "http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">NCSA</a> and there is
   an updated draft at the <a
  @@ -485,7 +485,7 @@
   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 script was in, and, if possible, the
  +running, what language your CGI program was in, and, if possible, the
   offending code. This will make finding your problem much simpler.</p>
   
   <p>Note that questions about CGI problems should <strong>never</strong>
  
  
  

Mime
View raw message