File: cgic.html

package info (click to toggle)
libcgic 1.06-4
links: PTS
area: main
in suites: potato
size: 284 kB
ctags: 199
sloc: ansic: 1,206; makefile: 92; sh: 3
file content (1290 lines) | stat: -rw-r--r-- 63,556 bytes
parent folder | download | duplicates (2)
<html>
<head>
<title>cgic: an ANSI C library for CGI Programming</title>
</head>
<body>
<h1>cgic: an ANSI C library for CGI Programming</h1>
<h2>By <a href="http://www.boutell.com/boutell/">Thomas Boutell</a></h2>
<em><a href="http://www.boutell.com/cgic/">
The LATEST documentation is available here. Check often
for new releases.</a></em>
<h3>Table of Contents</h3>
<strong>NOTICE: VERSION 1.06 (this version) contains important
security fixes. Upgrading is STRONGLY RECOMMENDED.</strong> (Yes,
the upgrade is free.)
<p>
<ul>
<li><a href="#credits">Credits and license terms</a>
<li><a href="#support">How to get support</a>
<li><a href="#whatsnew106">What's new in version 1.06?</a>
<li><a href="#whatis">What is cgic?</a>
<li><a href="#obtain">Obtaining cgic</a>
<li><a href="#build">Building and testing cgic: a sample application</a>
<li><a href="#nocompile">What to do if it won't compile</a>
<li><a href="#howto">How to write a cgic application</a>
<li><a href="#images">How can I generate images from my cgic application?</a>
<li><a href="#debug">CGI debugging features: using capture</a>
<li><a href="#functions">cgic function reference</a>
<li><a href="#variables">cgic variable reference</a>
<li><a href="#resultcodes">cgic result code reference</a>
<li><a href="#index">cgic quick index</a>
</ul>

<h3><a name="credits">Credits and License Terms</a></h3>

cgic can be used free of charge, <strong>provided that a
credit notice is provided online.</strong> Alternatively,
a nonexclusive Commercial License can be purchased, which
grants the right to use cgic without a public credit notice.
<p>
Please see the file
<code><a href="license.txt">license.txt</a></code>
for the details of the Basic License and Commercial License,
including ordering information for the Commercial License.
<p>
Thanks are due to Jon Ribbens and other CGIC users who have
corresponded over the years.
<h3><a name="support">How to Get Support</a></h3>

<h4>STOP! READ THIS FIRST! REALLY!</h4>
 
    Are you getting a "server error," indicating that your web server
    "cannot allow POST to this URL," or a similar message? <strong>YOU MUST
    CONFIGURE YOUR WEB SERVER TO ALLOW CGI PROGRAMS, AND YOU MUST
    INSTALL CGI PROGRAMS IN THE LOCATION (OR WITH THE EXTENSION) THAT
    YOUR WEB SERVER EXPECTS TO SEE.</strong> Please don't send me email about
    this. It is strictly between you and your web server's documentation,
    or between you and your ISP. Thanks!
<p>
Anyone can mail questions about the gd and cgic libraries to
boutell@boutell.com. However, I receive a very large volume of email on
many subjects, and while I do my best to respond to all queries this can
take some time. Sometimes the response must take the form of an eventual
new release or an addition to a FAQ or other document, as opposed to an
detailed individual response.
<p>
The old "priority support" offer for CGIC has been discontinued,
due to the impracticality of billing for it.

<h3><a name="whatsnew106">What's new in version 1.06?</a></h3>
1. A potentially significant buffer overflow problem has been
corrected. Jon Ribbens correctly pointed out to me (and to the
Internet's bugtraq mailing list) that the cgiFormEntryString
function, which is used directly or indirectly by almost all
CGIC programs, can potentially write past the buffer passed
to it by the programmer. This bug has been corrected.
Upgrading to version 1.06 is <strong>strongly recommended.</strong>
<P>
2. The function <code>cgiSaferSystem()</code> has been
removed entirely. This function escaped only a few metacharacters,
while most shells have many, and there was no way to account for
the many different operating system shells that might be in use
on different operating systems. Since this led to a false sense
of security, the function has been removed. It is our recommendation
that user input should never be passed directly on the command line
unless it has been carefully shown to contain only characters
regarded as safe and appropriate by the programmer. Even then, it is
better to design your utilities to accept their input from standard
input rather than the command line.
<h3><a name="whatsnew105">What's new in version 1.05?</a></h3>
Non-exclusive commercial license fee reduced to $200.
<h3><a name="whatsnew104">What's new in version 1.04?</a></h3>
For consistency with other packages, the standard Makefile
now produces a true library for cgic (libcgic.a). 
<h3><a name="whatsnew103">What's new in version 1.03?</a></h3>
Version 1.03 sends line feeds only (ascii 10) to end 
Content-type:, Status:, and other HTTP protocol output lines,
instead of CR/LF sequences. The standard specifies CR/LF.
Unfortunately, too many servers reject CR/LF to make
implementation of that standard practical. No server
tested ever rejects LF alone in this context. 
<h3><a name="whatsnew102">What's new in version 1.02?</a></h3>
Version 1.02 corrects bugs in previous versions:
<ul>
<li>
<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> specified
its arguments in the wrong order, with surprising results.
This bug has been corrected.
<li>
Many small changes have been made to increase compatibility.
cgic now compiles with no warnings under the compilers
available at boutell.com.
</ul>
<h3><a name="whatsnew101">What's new in version 1.01?</a></h3>
Version 1.01 adds no major functionality but corrects 
significant bugs and incompatibilities:
<ul>
<li>
<a href="#cgiFormInteger">cgiFormInteger</a>,
<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>,
<a href="#cgiFormDouble">cgiFormDouble</a> and
<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> now
accept negative numbers properly. They also accept positive
numbers with an explicit + sign.
<li>Hex values containing the digit <code>9</code> are
now properly decoded.
<li><a href="#cgiFormString">cgiFormString</a> now
represents each newline as a single line feed (ascii 10 decimal)
as described in the documentation, not a carriage return
(ascii 13 decimal) as in version 1.0. The latter approach
pleased no one.
<li><a href="#cgiFormString">cgiFormString</a> and
<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>
no longer erroneously return cgiFormEmpty in place of
cgiFormSuccess.
<li>The main() function of cgic now flushes standard output
and sleeps for one second before exiting in order to inhibit
problems with the completion of I/O on some platforms. This was
not a cgic bug per se, but has been reported as a common problem
with CGI when used with the CERN server. This change should
improve compatibility.
<li>The single selection example in the testform.html
example now works properly. This was an error in the
form itself, not cgic.
<li><a href="#cgiRemoteUser">cgiRemoteUser</a> and
<a href="#cgiRemoteIdent">cgiRemoteIdent</a> are now
documented accurately. They were reversed earlier.
</ul>
<h3><a name="whatis">What is cgic?</a></h3>
cgic is an ANSI C-language library for the creation of CGI-based
World Wide Web applications. For basic information about
the CGI standard, see the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">
CGI documentation</a> at NCSA.
<p>
cgic performs the following tasks:
<ul>
<li>Parses form data, correcting for defective and/or inconsistent browsers
<li>Transparently accepts both GET and POST form data
<li>Handles line breaks in form fields in a consistent manner
<li>Provides string, integer, floating-point, and single- and
multiple-choice functions to retrieve form data
<li>Provides bounds checking for numeric fields
<li>Loads CGI environment variables into C strings which are always non-null
<li>Provides a way to capture CGI situations for replay in a debugging
environment
</ul>
<p>
cgic should be compatible with any CGI-compliant server environment.
<h3><a name="obtain">Obtaining cgic</a></h3>
cgic is distributed via the web in two forms: as a Windows-compatible
.ZIP file, and as a compressed tar file. Most users of Windows and
related operating systems have access to 'unzip' or 'pkunzip'. All Unix 
systems come with 'uncompress' and 'tar' as standard equipment. Versions
of these programs for other operating systems are widely
available if you do not already have them.
<p>
<strong>Important:</strong> to use cgic, you will need an ANSI-standard
C compiler. The Sun cc distributed with SunOS 4.1.3 is <strong>not</strong>
ANSI-standard. Unix users may wish to obtain gcc, which is free and widely 
available, or purchase Sun's development package, which also includes a 
proper compiler. Users of Windows-related operating systems should not have
ANSI C-related problems as all of the popular compilers follow the ANSI 
standard.
<p>
<strong>Note for Windows Programmers:</strong> cgic should work in a
16-bit environment but is not designed to cater to such an environment.
Form fields which require more than 64K individually will not work
as expected unless the huge memory model is used. Using a 32-bit
compiler and operating environment is strongly recommended.
<p>
Your web browser should inquire whether to save the file to disk
when you select one of the links below. Under Unix and compatible
operating systems, save it, then issue the following
commands to unpack it:
<pre>
uncompress cgic106.tar.Z
tar -xf cgic106.tar
</pre>
This should produce the subdirectory 'cgic106', which will contain
the complete cgic distribution for version 1.06, including a copy of this 
documentation in the file cgic.html.
<p>
Under Windows and compatible operating systems, save it,
open a DOS window, and issue the following commands to unpack it:
<pre>
pkunzip /d cgic106.zip
</pre>
This command also produces the subdirectory 'cgic106', which will contain
the complete cgic distribution for version 1.06, including a copy of this 
documentation in the file CGIC.HTM.
<p>
cgic is available via the web from www.boutell.com:
<ul>
<li><a href="http://www.boutell.com/cgic/cgic106.tar.Z">Obtain cgic: compressed tar file</a>
<li><a href="http://www.boutell.com/cgic/cgic106.zip">Obtain cgic: .ZIP file</a>
</ul>
<h3><a name="build">Building cgic: a sample application</a></h3>
The sample application 'cgictest.c' is provided as part of the
cgic distribution. This CGI program accepts input submitted
by the form cgictest.html. 
<p>
On a Unix system, you can build cgictest simply by typing
'make cgictest'. cgic.c and cgictest.c will be compiled and linked
together to produce the cgictest application. Under non-Unix
operating systems, you will need to create and compile an appropriate
project containing the files cgic.c and cgictest.c. 
<p>
<strong>IMPORTANT:</strong> after compiling cgictest, you will
need to place it in a location on your server system which is
designated by your server administrator as an appropriate location
for CGI scripts. Also, the URL of the action of the sample form in
testform.html must be changed to correctly indicate the location
of cgictest on your web server. The right locations for CGI
programs vary greatly from one server to another. Resolving
this issue is between you, your web server administrator,
and your web server documentation. Before submitting a bug
report for cgic, make certain that the CGI example programs
which came with your server <em>do</em> work for you. Otherwise
it is very likely that you have a server configuration problem.
<p>
Once you have moved cgictest to an appropriate cgi directory
and edited form.html to properly refer to its location,
use the web browser of your choice to access form.html.
Fill out the various fields in any manner you wish, then
select the SUBMIT button.
<p>
If all goes well, cgictest will respond with a page which
indicates the various settings you submitted. If not,
please see the second paragraph above.
<h3><a name="nocompile">What to do if it won't compile</a></h3>
<ul>
<li><strong>Are you using Visual C++ or Borland C++? Did you forget to add
cgic.c to your project?</strong>
<li><strong>Make sure you are using an ANSI C or C++ compiler.</strong>
(All of the Windows compilers are ANSI C compliant.)
<li>If your compiler can't find the #include file <code>unistd.h</code>,
define the preprocessor macro NO_UNISTD and recompile. (A place for defining
macros is provided in the project settings of all the Windows compilers.)
</ul>
If none of the above proves effective, please see the
section regarding <a href="#support">support</a>.
<h3><a name="howto">How to write a cgic application</a></h3>
<em>Note: </em> All cgic applications must be linked to the cgic.c module
itself. How to do this depends on your operating system; under Unix,
just use the provided Makefile as an example.
<p>
Since all CGI applications must perform certain initial
tasks, such as parsing form data and examining
environment variables, the cgic library provides its
own main() function. When you write applications that
use cgic, you will begin your own programs by writing
a cgiMain() function, which cgic will invoke when
the initial cgi work has been successfully completed. Your
program must also be sure to #include the file cgic.h.
<p>
<strong>Important:</strong> if you write your own main()
function, your program will not link properly. Your own
code should begin with cgiMain(). The library
provides main() for you.
<p>
Consider the cgiMain function of cgictest.c:
<p>
<PRE>
int cgiMain() {
#if DEBUG
        /* Load a saved CGI scenario if we're debugging */
        <a href="#cgiReadEnvironment">cgiReadEnvironment</a>("/path/to/capcgi.dat");
#endif
	/* Important: we must indicate the type of document */
        <a href="#cgiHeaderContentType">cgiHeaderContentType</a>("text/html");
	/* Now invoke other functions to handle each part of the form */
        fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;HTML&gt;&lt;HEAD&gt;\n");                        
        fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;TITLE&gt;cgic test&lt;/TITLE&gt;&lt;/HEAD&gt;\n"):
        fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;BODY&gt;&lt;H1&gt;cgic test&lt;/H1&gt;\n");
        Name();
        Address();
        Hungry();
        Temperature();
        Frogs();
        Color();
        Flavors();
        NonExButtons();
        RadioButtons();
        fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/BODY&gt;&lt;/HTML&gt;\n");
	/* This value will be the exit code of the program; 0 
		generally indicates success among Unix and DOS programs */ 
        return 0;
}
</PRE>
Note the DEBUG #ifdef. If DEBUG is defined at compile time, either by
inserting the line "#define DEBUG 1" into the program or by setting
it in the Makefile or other development environment, then the
<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> function will be called 
to restore a captured CGI environment for debugging purposes. See
the discussion of the <a href="#debug">capture</a> program, which is
provided for use in CGI debugging.
<h4>Outputting the Header</h4>
Next, one of the cgiHeader functions should be called.
In this program, <a href="#cgiHeaderContentType">cgiHeaderContentType()</a> is 
called to indicate the MIME type of the document being output, in this case 
"text/html" (a normal HTML document). A few other common MIME types are
"image/gif", "image/jpeg" and "audio/basic". 
<p>
Note that <a href="#cgiHeaderStatus">cgiHeaderStatus()</a> or 
<a href="#cgiHeaderLocation">cgiHeaderLocation()</a> could have
been invoked instead to output an error code or redirect the
request to a different URL. Only one of the cgiHeader functions
should be called in a single execution of the program.
<p>
<strong>Important:</strong> one of the cgiHeader functions,
usually <a href="#cgiHeaderContentType">cgiHeaderContentType()</a>, 
<em>must</em> be invoked before outputting any other
response to the user. Otherwise, the result will not be a valid
document and the browser's behavior will be unpredictable.
You may, of course, output your own ContentType and other
header information to <a href="#cgiOut">cgiOut</a> if you prefer. The cgiHeader functions
are provided as a convenience.
<p>
Next, cgiMain() invokes various functions to handle individual parts
of the form. When the function is finished, it returns 0, the usual
return code for a successful program.
<p>
<h4>Handling Text Input</h4>
The Name() function of cgictest is shown below:
<PRE>
void Name() {
        char name[81];
        <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>("name", name, 81);
        fprintf(<a href="#cgiOut">cgiOut</a>, "Name: %s&lt;BR&gt;\n", name);
}
</PRE>
The purpose of this function is to retrieve and display the name that was
input by the user. Since the programmer has decided that names should
be permitted to have up to 80 characters, a buffer of 81 characters
has been declared (allowing for the final null character). 
The <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>
function is then invoked to retrieve the name and ensure that
carriage returns are not present in the name (despite the
incorrect behavior of some web browsers). The first argument
is the name of the input field in the form, the second argument
is the buffer to which the data should be copies, and the third
argument is the size of the buffer. cgic will never write beyond
the size of the buffer, and will always provide a null-terminated
string in response; if the buffer is too small, the string will
be shortened. If this is not acceptable, the
<a href="#cgiFormStringSpaceNeeded">cgiFormStringSpaceNeeded()</a>
function can be used to check the amount of space needed; the
return value of cgiFormStringNoNewlines() can also be checked
to determine whether truncation occurred. See
the full description of <a href="#cgiFormStringNoNewlines">
cgiFormStringNoNewlines()</a>.
<h4>Handling Output</h4>
Note that Name() writes its HTML output to <a href="#cgiOut">cgiOut</a>, not
to stdout.
<p>
<strong>Important:</strong> <a href="#cgiOut">cgiOut</a> is normally equivalent
to stdout, and there is no performance penalty for using it.
It is recommended that you write output to <a href="#cgiOut">cgiOut</a> to ensure compatibility
with future versions of the cgic library for special
environments that do not provide stdin and stdout for
each cgi connection.
<p>
Note that, for text input areas in which carriage returns <em>are</em>
desired, the function <a href="#cgiFormString">cgiFormString</a>
should be used instead. cgiFormString ensures that line breaks
are always represented by a single carriage return (ascii decimal 13),
making life easier for the programmer. See the source code to
the Address() function of cgictest.c for an example.
<h4>Handling Single Checkboxes</h4>
Consider the Hungry() function, which determines whether
the user has selected the "hungry" checkbox:
<PRE>
void Hungry() {
        if (<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a>("hungry") == <a href="#cgiFormSuccess">cgiFormSuccess</a>) {
                fprintf(cgiOut, "I'm Hungry!&lt;BR&gt;\n");
        } else {
                fprintf(cgiOut, "I'm Not Hungry!&lt;BR&gt;\n");
        }
}
</PRE>
This function takes advantage of the
<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle()</a> function, which
determines whether a single checkbox has been selected. 
cgiFormCheckboxSingle() accepts the name attribute of the checkbox
as its sole argument and returns <a href="#cgiFormSuccess">
cgiFormSuccess</a> if the checkbox is selected, or 
<a href="#cgiFormNotFound">cgiFormNotFound</a> if it is not.
If multiple checkboxes with the same name are in use,
consider the <a href="#cgiFormCheckboxMultiple">
cgiFormCheckboxMultiple()</a> and 
<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>
functions.
<h4>Handling Numeric Input</h4>
Now consider the Temperature() function, which retrieves
a temperature in degrees (a floating-point value) and ensures
that it lies within particular bounds:
<PRE>
void Temperature() {
        double temperature;
        <a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a>("temperature", &amp;temperature, 80.0, 120.0, 98.6);
        fprintf(<a href="#cgiOut">cgiOut</a>, "My temperature is %f.&lt;BR&gt;\n", temperature);
}
</PRE>
The temperature is retrieved by the function 
<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a>. The first
argument is the name of the temperature input field in the form;
the second argument points to the address of the variable that will 
contain the result. The next two arguments are the lower and upper
bounds, respectively. The final argument is the default value to
be returned if the user did not submit a value.
<p>
This function always retrieves a reasonable value within the
specified bounds; values above or below bounds are constrained
to fit the bounds. However, the return value of
cgiFormDoubleBounded can be checked to make sure the
actual user entry was in bounds, not blank, and so forth;
see the description of <a href="#cgiFormDoubleBounded">
cgiFormDoubleBounded()</a> for more details. If bounds checking
is not desired, consider using <a href="#cgiFormDouble">
cgiFormDouble()</a> instead.
<p>
Note that, for integer input, the functions
<a href="#cgiFormInteger">cgiFormInteger</a> and
<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>
are available. The behavior of these functions is similar to
that of their floating-point counterparts above.
<h4>Handling Single-Choice Input</h4>
The &lt;SELECT&gt; tag of HTML is used to provide the user with
several choices. Radio buttons and checkboxes can also be used
when the number of choices is relatively small. Consider
the Color() function of cgictest.c:
<PRE>
char *colors[] = {
        "Red",
        "Green",
        "Blue"
};

void Color() {
        int colorChoice;
        <a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("colors", colors, 3, &amp;colorChoice, 0);
        fprintf(<a href="#cgiOut">cgiOut</a>, "I am: %s&lt;BR&gt;\n", colors[colorChoice]);
}
</PRE>
This function determines which of several colors the user chose
from a &lt;SELECT&gt; list in the form. An array of colors is
declared; the <a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a>
function is then invoked to determine which, if any, of those choices
was selected. The first argument indicates the name of the input
field in the form. The second argument points to the list of
acceptable colors. The third argument indicates the number of
entries in the color array. The fourth argument points to the
variable which will accept the chosen color, and the last argument
indicates the index of the default value to be set if no
selection was submitted by the browser. 
<p>
<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> will
always indicate a reasonable selection value. However, if
the programmer wishes to know for certain that a value was
actually submitted, that the value submitted was a legal
response, and so on, the return value of cgiFormSelectSingle()
can be consulted. See the full description of
<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> for
more information.
<p>
Note that radio button groups and &lt;SELECT&gt; lists can both
be handled by this function. If you are processing radio
button groups, you may prefer to invoke 
<a href="#cgiFormRadio">cgiFormRadio()</a>, which functions
identically. 
<p>
<em>"What if I won't know the acceptable choices at runtime?"</em>
<p>
If the acceptable choices aren't known <em>until</em> runtime,
one can simply load the choices from disk. But if the acceptable
choices aren't fixed at all (consider a list of country names;
new names may be added to the form at any time and it is
inconvenient to also update program code or a separate list
of countries), simply invoke 
<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>
instead to retrieve the string directly. Keep in mind that, if
you do so, validating the response to make sure it is
safe and legitimate becomes a problem for your own
program to solve. The advantage of cgiFormSelectSingle() is that invalid 
responses are never returned.
<p>
To handle multiple-selection &lt;SELECT&gt; lists and
groups of checkboxes with the same name, see the
discussion of the NonExButtons() function of cgictest.c, immediately below.
<h4>Handling Multiple-Choice Input</h4>
Consider the first half of the NonExButtons() function of cgictest.c:
<PRE>
char *votes[] = {
	"A",
	"B",
	"C",
	"D"
};

void NonExButtons() {
	int voteChoices[4];
	int i;
	int result;	
	int invalid;

	char **responses;

	/* Method #1: check for valid votes. This is a good idea,
		since votes for nonexistent candidates should probably
		be discounted... */
	fprintf(<a href="#cgiOut">cgiOut</a>, "Votes (method 1):&lt;BR&gt;\n");
	result = <a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>("vote", votes, 4, 
		voteChoices, &amp;invalid);
	if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {
		fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!&lt;p&gt;\n");
	} else {	
		fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");
		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;ul&gt;\n");
		for (i=0; (i &lt; 4); i++) {
			if (voteChoices[i]) {
				fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;li&gt;%s\n", votes[i]);
			}
		}
		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/ul&gt;\n");
	}
</PRE>
This function takes advantage of
<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a>,
which is used to identify one or more selected checkboxes with 
the same name. This function performs identically to
<a href="#cgiFormSelectMultiple">cgiFormSelectMultiple()</a>.
That is, &lt;SELECT&gt; tags with the MULTIPLE attribute are handled
just like a group of several checkboxes with the same name.
<p>
The first argument to <a href="#cgiFormCheckboxMultiple">
cgiFormCheckboxMultiple()</a> is the name given to all
checkbox input fields in the group. The second argument
points to an array of legitimate values; these should
correspond to the VALUE attributes of the checkboxes
(or OPTION tags in a &lt;SELECT&gt; list). The third argument
indicates the number of entries in the array of
legitimate values. The fourth argument points to
an array of integers with the same number of entries
as the array of legitimate values; each entry
will be set true if that checkbox or option was selected,
false otherwise.
<p>
The last argument points to an integer which will be set to the 
number of invalid responses (responses not in the array of
valid responses) that were submitted. If this value is not
of interest, the last argument may be a null pointer (0).
<p>
Note that the return value of cgiFormCheckboxMultiple is
inspected to determine whether any choices at all were
set. See the full description of
<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>
for other possible return values. 
<p>
<em>"What if I won't know the acceptable choices at runtime?"</em>
<p>
If the acceptable choices aren't known <em>until</em> runtime,
one can simply load the choices from disk. But if the acceptable
choices aren't fixed at all (consider a list of ice cream flavors;
new names may be added to the form at any time and it is
inconvenient to also update program code or a separate list
of countries), a more dynamic approach is needed. Consider
the second half of the NonExButtons() function of cgictest.c:
<PRE>
	/* Method #2: get all the names voted for and trust them.
		This is good if the form will change more often
		than the code and invented responses are not a danger
		or can be checked in some other way. */
	fprintf(<a href="#cgiOut">cgiOut</a>, "Votes (method 2):&lt;BR&gt;\n");
	result = <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);
	if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {	
		fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!&lt;p&gt;\n");
	} else {
		int i = 0;
		fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");
		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;ul&gt;\n");
		while (responses[i]) {
			fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;li&gt;%s\n", responses[i]);
			i++;
		}
		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/ul&gt;\n");
	}
	/* We must be sure to free the string array or a memory
		leak will occur. Simply calling free() would free
		the array but not the individual strings. The
		function cgiStringArrayFree() does the job completely. */	
	<A HREF="#cgiStringArrayFree">cgiStringArrayFree</a>(responses);
}
</PRE>
This code excerpt demonstrates an alternate means of retrieving
a list of choices. The function
<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> is used
to retrieve an array consisting of all the strings submitted
for with a particular input field name. This works both for
&lt;SELECT&gt; tags with the MULTIPLE attribute and for 
groups of checkboxes with the same name. 
<P>
The first argument to <a href="#cgiFormStringMultiple">
cgiFormStringMultiple()</a> is the name of the input field or
group of input fields in question. The second argument should
be the address of a pointer to a pointer to a string, which
isn't as bad as it sounds. Consider the following simple call
of the function:
<PRE>
/* An array of strings; each C string is an array of characters */
char **responses; 

<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);
</PRE>
<em>"How do I know how many responses there are?"</em>
<p>
After the call, the last entry in the string array will be
a null pointer. Thus the simple loop:
<PRE>
int i = 0;
while (responses[i]) {
	/* Do something with the string responses[i] */
	i++;
}
</PRE>
can be used to walk through the array until the last
entry is encountered.
<p>
<strong>Important:</strong> unlike other functions in the cgic library,
the <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a> function
returns a pointer to <strong>allocated memory</strong>. Your code
should not modify the strings in the responses array or the responses
array itself; if modification is needed, the strings should be
copied. When your code is done examining the responses array,
you <strong>MUST</strong> call <a href="#cgiStringArrayFree">
cgiStringArrayFree()</a> with the array as an argument to free the memory 
associated with the array. Otherwise, the memory may be lost permanently 
(under some operating systems), or will not be available again until the
program exists. <strong>Don't</strong> just call the free() function;
if you do, the individual strings will not be freed.
<h4>Examining CGI environment variables</h4>
The CGI standard specifies a number of environment variables
which are set by the server. However, servers are somewhat
unpredictable as to whether these variables will be null or
point to empty strings when an environment variable is not set.
Also, in order to allow the programmer to restore saved
CGI environments, the cgic library needs have a way of insulating
the programmer from the actual environment variables.
<p>
Instead of calling getenv() to determine the value of a
variable such as HTTP_USER_AGENT (the browser software being used),
always use the
<a href="#variables">cgic copies of the environment variables</a>,
which are always valid C strings (they are never null, although
they may point to an empty string). For instance, the cgic
variable containing the name of the browser software is
<a href="#cgiUserAgent">cgiUserAgent</a>. The referring URL appears
in the variable <a href="#cgiReferrer">cgiReferrer</a>.
<h3><a name="images">How can I generate images from my cgic application?</a></h3>
cgic can be used in conjunction with the
<a href="http://siva.cshl.org/gd/gd.html">gd graphics library</a>, which
can produce GIF images on the fly.
<p>
The following short sample program hints at the possibilities:
<pre>
#include "cgic.h"
#include "gd.h"

char *colors[] = {
	"red", "green", "blue"
};

#define colorsTotal 3

int cgiMain() {
	int colorChosen;
	gdImagePtr im;
	int r, g, b;
	/* Use gd to create an image */
	im = gdImageCreate(64, 64);
	r = gdImageColorAllocate(im, 255, 0, 0);	
	g = gdImageColorAllocate(im, 0, 255, 0);	
	b = gdImageColorAllocate(im, 0, 0, 255);	
	/* Now use cgic to find out what color the user requested */
	<a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("color", 3, &amp;colorChosen, 0);	
	/* Now fill with the desired color */
	switch(colorChosen) {
		case 0:
		gdImageFill(im, 32, 32, r);
		break;
		case 1:
		gdImageFill(im, 32, 32, g);
		break;
		case 2:
		gdImageFill(im, 32, 32, b);
		break;
	}	
	/* Now output the image. Note the content type! */
	cgiHeaderContentType("image/gif");
	/* Send the image to cgiOut */
	gdImageGif(im, cgiOut);
	/* Free the gd image */
	gdImageDestroy(im);
	return 0;
}
</pre>
Note that this program would need to be linked with both cgic.o
and libgd.a. Often programs of this type respond to one
cgiPathInfo value by returning an HTML page with an inline image
reference that, in turn, generates a GIF image.
<h3><a name="debug">Debugging CGI applications: using capture</a></h3>
Debugging CGI applications can be a painful task. Since CGI applications
run in a special environment created by the web server, it is difficult
to execute them in a debugger. However, the cgic library provides a way 
of capturing "live" CGI environments to a file, and also provides a way
to reload saved environments. 
<p>
The provided program 'capture.c' can be used to capture CGI
environments. Just change the first line of the cgiMain() function
of capture.c to save the CGI environment to a filename appropriate
on your system and type 'make capture'. Then place capture in your
cgi directory and set the form action or other link you want to test
to point to it. When the form submission or other link takes place,
capture will write the CGI environment active at that time to
the filename you specified in the source. The
<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> function can then 
be invoked on the same filename at the beginning of the cgiMain() function 
of the application you want to test in order to restore the captured 
environment.  You can then execute your program in the debugger of your choice,
and it should perform exactly as it would have performed had
it been launched by the actual web server.
<p>
<strong>Important:</strong> Make sure you specify the full path, as the the
current working directory of a CGI script may not be what you
think it is.
<p>
<strong>Even More Important:</strong> If you call getenv() yourself
in your code, instead of using the provided <a href="#variables">
cgic copies of the CGI environment variables</a>, you will
<em>not</em> get the values you expect when running with
a saved CGI environment. Always use the cgic variables instead
of calling getenv().
<h3><a name="functions">cgic function reference</a></h3>
<dl>
<dt><a name="cgiFormString">cgiFormResultType cgiFormString(
	char *name, char *result, int max)</a>
<dd>cgiFormString attempts to retrieve the string sent for the
	specified input field. The text will be copied into
	the buffer specified by result, up to but not
	exceeding max-1 bytes; a terminating null is then
	added to complete the string. Regardless of the newline
	format submitted by the browser, cgiFormString always
	encodes each newline as a single line feed (ascii decimal 10); as
	a result the final string may be slightly shorter than indicated
	by a call to <a href="#cgiFormStringSpaceNeeded">
	cgiFormStringSpaceNeeded</a> but will never be longer.
	cgiFormString returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the string was 
	successfully retrieved, 
	<a href="#cgiFormTruncated">cgiFormTruncated</a> if the string was
	retrieved but was truncated to fit the buffer,
	cgiFormEmpty if the string was 
	retrieved but was empty, cgiFormLong if the string was retrieved 
	but was truncated to fit into the buffer, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no 
	such input field was submitted. In the last case, 
	an empty string is copied to result. 
<br><dt><a name="cgiFormStringNoNewlines">
cgiFormResultType cgiFormStringNoNewlines(
	char *name, char *result, int max)</a>
<dd>
cgiFormStringNoNewlines() is exactly equivalent to <a href="#cgiFormString">
	cgiFormString()</a>, except
	that any carriage returns or line feeds that occur in the input
	will be stripped out. The use of this function is recommended
	for single-line text input fields, as some browsers will submit
	carriage returns and line feeds when they should not. 
<br><dt><a name="cgiFormStringSpaceNeeded">
cgiFormResultType cgiFormStringSpaceNeeded(
	char *name, int *length)</a>
<dd>
cgiFormStringSpaceNeeded() is used to determine the length of the input text 
	buffer needed to receive the contents of the specified input field. 
	This is useful if the programmer wishes to allocate sufficient memory 
	for input of arbitrary length. The actual length of the string 
	retrieved by a subsequent call to cgiFormString() may be slightly shorter
	but will never be longer than *result. On success, cgiFormStringSpaceNeeded() 
	sets the value pointed to by length to the number of bytes of data, 
	including the terminating null, and returns <a href="#cgiFormSuccess">cgiFormSuccess</a>. If no 
	value was submitted for the specified field, cgiFormStringSpaceNeeded sets 
	the value pointed to by length to 1 and returns <a href="#cgiFormNotFound">cgiFormNotFound</a>. 1 is
	set to ensure space for an empty string (a single null
	character) if cgiFormString is called despite the return value.

<br><dt><a name="cgiFormStringMultiple">cgiFormResultType cgiFormStringMultiple(
	char *name, char ***ptrToStringArray)</a>
<dd>cgiFormStringMultiple is useful in the unusual case in which several
	input elements in the form have the same name and, for whatever
	reason, the programmer does not wish to use the checkbox, radio 
	button and selection menu functions provided below. This is
	occasionally needed if the programmer cannot know 
	in advance what values might appear in a multiple-selection list
	or group of checkboxes on a form. The value pointed to
	by result will be set to a pointer to an array of strings; the last
	entry in the array will be a null pointer.  This array is allocated 
	by the CGI library. Important: when done working with the array,
	you must call cgiStringArrayFree() with the array pointer as the 
	argument.  cgiFormStringMultiple() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if at least
	one occurrence of the name is found, <a href="#cgiFormNotFound">cgiFormNotFound</a>
	if no occurrences are found, or cgiFormMemory if not enough
	memory is available to allocate the array to be returned.
	In all cases except the last, ptrToStringArray is set to point to a 
	valid array of strings, with the last element in the array being a 
	null pointer; in the out-of-memory case ptrToStringArray is set to 
	a null pointer.

<br><dt><a name="cgiStringArrayFree">void cgiStringArrayFree(char **stringArray)
</a>
<dd>
cgiStringArrayFree() is used to free the memory associated with
	a string array created by cgiFormStringMultiple(). 
<br><dt><a name="cgiFormInteger">cgiFormResultType cgiFormInteger(
	char *name, int *result, int defaultV)</a>
<dd>cgiFormInteger() attempts to retrieve the integer sent for the
	specified input field. The value pointed to by result
	will be set to the value submitted. cgiFormInteger() returns 
	cgiFormSuccess if the value was successfully retrieved,
	cgiFormEmpty if the value submitted is an empty string,
	cgiFormBadType if the value submitted is not an integer,
	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted. 
	In the last three cases, the value pointed to by result
	is set to the specified default.
<br><dt><a name="cgiFormIntegerBounded">
cgiFormResultType cgiFormIntegerBounded(
	char *name, int *result, int min, int max, int defaultV)</a>
<dd>cgiFormIntegerBounded() attempts to retrieve the integer sent for the
	specified input field, and constrains the result to be within
	the specified bounds. The value pointed to by result
	will be set to the value submitted. cgiFormIntegerBounded() returns 
	cgiFormSuccess if the value was successfully retrieved,
	<a href="#cgiFormConstrained">cgiFormConstrained</a> if the value was out of bounds and result
	was adjusted accordingly, <a href="#cgiFormEmpty">cgiFormEmpty</a> if the value submitted is 
	an empty string, <a href="#cgiFormBadType">cgiFormBadType</a> if the value submitted is not an 
	integer, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted. 
	In the last three cases, the value pointed to by result
	is set to the specified default.

<br><dt><a name="cgiFormDouble">cgiFormResultType cgiFormDouble(
	char *name, double *result, double defaultV)</a>
<dd>cgiFormDouble attempts to retrieve the floating-point value sent for 
	the specified input field. The value pointed to by result
	will be set to the value submitted. cgiFormDouble returns 
	cgiFormSuccess if the value was successfully retrieved,
	cgiFormEmpty if the value submitted is an empty string,
	cgiFormBadType if the value submitted is not a number,
	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted. 
	In the last three cases, the value pointed to by result
	is set to the specified default. 
<br><dt><a name="cgiFormDoubleBounded">
cgiFormResultType cgiFormDoubleBounded(
	char *name, double *result, double min, double max, 
	double defaultV)</a>
<dd>
cgiFormDoubleBounded() attempts to retrieve the floating-point
	value  sent for the specified input field, and constrains the 
	result to be within the specified bounds. The value pointed to by 
	result will be set to the value submitted. cgiFormDoubleBounded() returns 
	cgiFormSuccess if the value was successfully retrieved,
	<a href="#cgiFormConstrained">cgiFormConstrained</a> if the value was out of bounds and result
	was adjusted accordingly, <a href="#cgiFormEmpty">cgiFormEmpty</a> if the value submitted is 
	an empty string, <a href="#cgiFormBadType">cgiFormBadType</a> if the value submitted is not a 
	number, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted. 
	In the last three cases, the value pointed to by result
	is set to the specified default. 

<br><dt><a name="cgiFormSelectSingle">
cgiFormResultType cgiFormSelectSingle(
	char *name, char **choicesText, int choicesTotal, 
	int *result, int defaultV)</a>
<dd>
cgiFormSelectSingle() retrieves the selection number associated with a
	&lt;SELECT&gt; element that does not allow multiple selections. name
	should identify the NAME attribute of the &lt;SELECT&gt; element. choicesText 
	should point to an array of strings identifying each choice; 
	choicesTotal should indicate the total number of choices. The value 
	pointed to by result will be set to the position of the actual choice
	selected within the choicesText array, if any, or to the value of 
	default, if no selection was submitted or an invalid selection was 
	made.  cgiFormSelectSingle() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the value was
	successfully retrieved, <a href="#cgiFormNotFound">cgiFormNotFound</a> if no selection
	was submitted, and <a href="#cgiFormNoSuchChoice">cgiFormNoSuchChoice</a> if the selection
	does not match any of the possibilities in the choicesText array. 
<dt>
<a name="cgiFormSelectMultiple">
cgiFormResultType cgiFormSelectMultiple(
	char *name, char **choicesText, int choicesTotal, 
	int *result, int *invalid)</a>
<dd>cgiFormSelectMultiple() retrieves the selection numbers associated with a
	&lt;SELECT&gt; element that does allow multiple selections. name should
	identify the NAME attribute of the &lt;SELECT&gt; element. choicesText 
	should point to an array of strings identifying each choice; 
	choicesTotal should indicate the total number of choices. result
	should point to an array of integers with as many elements as there
	are strings in the choicesText array. For each choice in the
	choicesText array that is selected, the corresponding integer in
	the result array will be set to one; other entries in the result
	array will be set to zero. cgiFormSelectMultiple() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> 
	if at least one valid selection was successfully retrieved or
	cgiFormNotFound if no valid selections were submitted.
	The integer pointed to by invalid is set to the number of
	invalid selections that were submitted, which should be zero
	unless the form and the choicesText array do not agree.

<br><dt>
<a name="cgiFormCheckboxSingle">
cgiFormResultType cgiFormCheckboxSingle(
	char *name)</a>
<dd>
cgiFormCheckboxSingle determines whether the checkbox with the specified name
	is checked. cgiFormCheckboxSingle returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the
	button is checked, <a href="#cgiFormNotFound">cgiFormNotFound</a> if the checkbox is
	not checked. cgiFormCheckboxSingle is intended for single
	checkboxes with a unique name; see below for functions to
	deal with multiple checkboxes with the same name, and
	with radio buttons.

<br><dt><a name="cgiFormCheckboxMultiple">
cgiFormResultType cgiFormCheckboxMultiple(
	char *name, char **valuesText, int valuesTotal, 
	int *result, int *invalid)</a>
<dd>cgiFormCheckboxMultiple() determines which checkboxes among a group
	of checkboxes with the same name are checked. This is distinct
	from radio buttons (see <a href="#cgiFormRadio">cgiFormRadio</a>). 
	valuesText 
	should point to an array of strings identifying the VALUE
	attribute of each checkbox; valuesTotal should indicate the total 
	number of checkboxes. result should point to an array of integers with 
	as many elements as there are strings in the valuesText array. For 
	each choice in the valuesText array that is selected, the corresponding
	integer in the result array will be set to one; other entries in the 
	result array will be set to zero. cgiFormCheckboxMultiple returns 
	cgiFormSuccess if at least one valid checkbox was checked or
	cgiFormNotFound if no valid checkboxes were checked.
	The integer pointed to by invalid is set to the number of
	invalid selections that were submitted, which should be zero
	unless the form and the valuesText array do not agree.
<br><dt><a name="cgiFormRadio">
cgiFormResultType cgiFormRadio(
	char *name, char **valuesText, int valuesTotal, 
	int *result, int defaultV)</a>
<dd>cgiFormRadio() determines which, if any, of a group of radio boxes with
	the same name was selected. valuesText should point to an array of 
	strings identifying the VALUE attribute of each radio box; 
	valuesTotal should indicate the total number of radio boxes. The value 
	pointed to by result will be set to the position of the actual choice 
	selected within the valuesText array, if any, or to the value of 
	default, if no radio box was checked or an invalid selection was 
	made. cgiFormRadio() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if a checked radio box was 
	found in the group, <a href="#cgiFormNotFound">cgiFormNotFound</a> if no box was checked, and 
	<a href="#cgiFormNoSuchChoice">cgiFormNoSuchChoice</a> if the radio box submitted does not match any of 
	the possibilities in the valuesText array.

/* Header output functions. Call the first to specify a new URL
	if the document request should be redirected.
	Call the second if you wish to respond to a request
	with an HTTP error status code and message; see the
	HTTP documentation for the legal codes. Call the third
	in the normal case, in order to specify the mime type of 
	the document (such as "text/html"); you may then output
	the actual document directly to cgiOut. */
<br><dt><a name="cgiHeaderLocation">
void cgiHeaderLocation(char *redirectUrl)</a>
<dd>
cgiHeaderLocation() should be called if the programmer wishes to
redirect the user to a different URL. No futher output
is needed in this case.
Only one of the cgiHeader functions
(<a href="#cgiHeaderLocation">cgiHeaderLocation</a>,
<a href="#cgiHeaderStatus">cgiHeaderStatus</a> and 
<a href="#cgiHeaderContentType">cgiHeaderContentType</a>)
should be invoked for each CGI transaction.
<br><dt><a name="cgiHeaderStatus">
void cgiHeaderStatus(int status, char *statusMessage)</a>
<dd>
cgiHeaderStatus() should be called if the programmer wishes to
output an HTTP error status code instead of a document. The status
code is the first argument; the second argument is the status
message to be displayed to the user.
Only one of the cgiHeader functions
(<a href="#cgiHeaderLocation">cgiHeaderLocation</a>,
<a href="#cgiHeaderStatus">cgiHeaderStatus</a> and 
<a href="#cgiHeaderContentType">cgiHeaderContentType</a>)
should be invoked for each CGI transaction.
<br><dt><a name="cgiHeaderContentType">
void cgiHeaderContentType(char *mimeType)</a>
<dd>
cgiHeaderContentType() should be called if the programmer wishes to
output a new document in response to the user's request. This is
the normal case. The single argument is the MIME document type
of the response; typical values are "text/html" for HTML documents, 
"text/plain" for plain ASCII without HTML tags, "image/gif" for
a GIF image and "audio/basic" for .au-format audio.
Only one of the cgiHeader functions
(<a href="#cgiHeaderLocation">cgiHeaderLocation</a>,
<a href="#cgiHeaderStatus">cgiHeaderStatus</a> and 
<a href="#cgiHeaderContentType">cgiHeaderContentType</a>)
should be invoked for each CGI transaction.
<br><dt><a name="cgiWriteEnvironment">
cgiEnvironmentResultType cgiWriteEnvironment(char *filename)</a>
<dd>
cgiWriteEnvironment() can
	be used to write the entire CGI environment, including
	form data, to the specified output file; <a href="#cgiReadEnvironment">
	cgiReadEnvironment()</a> 
	can then be used to restore that environment from the specified
	input file for debugging. Of course, these will only work as expected
	if you use the <a href="#variables">cgic copies of the CGI environment 
	variables</a> and <a href="#cgiIn">cgiIn</a> and 
	<a href="#cgiOut">cgiOut</a> rather than stdin and
	stdout (also see above). These functions are useful in order 
	to capture real CGI situations while the web server is running, then
	recreate them in a debugging environment. Both functions
	return <a href="#cgiEnvironmentSuccess">cgiEnvironmentSuccess</a> on 
	success, <a href="#cgiEnvironmentIO">cgiEnvironmentIO</a> on an I/O 
	error, and <a href="#cgiEnvironmentMemory">cgiEnvironmentMemory</a>
	on an out-of-memory error.
<br><dt><a name="cgiReadEnvironment">
cgiEnvironmentResultType cgiReadEnvironment(char *filename)</a>
<dd>
cgiReadEnvironment() restores a CGI environment saved to the specified file by
	<a href="#cgiWriteEnvironment">cgiWriteEnvironment().</a> 
	Of course, these will only work as expected
	if you use the <a href="#variables">cgic copies of the CGI environment 
	variables</a> and <a href="#cgiIn">cgiIn</a> and 
	<a href="#cgiOut">cgiOut</a> rather than stdin and
	stdout (also see above). These functions are useful in order 
	to capture real CGI situations while the web server is running, then
	recreate them in a debugging environment. Both functions
	return <a href="#cgiEnvironmentSuccess">cgiEnvironmentSuccess</a> on success, 
	<a href="#cgiEnvironmentIO">cgiEnvironmentIO</a> on an I/O error, and 
	<a href="#cgiEnvironmentMemory">cgiEnvironmentMemory</a>
	on an out-of-memory error.
<br><dt><a name="cgiMain">int cgiMain()</a>
<dd><strong>The programmer must write this function</strong>, which performs 
	the unique task of the program and is invoked by the true main() 
	function, found in the cgic library itself. The return value from 
	cgiMain will be the return value of the program. It is expected that 
	the user will make numerous calls to the cgiForm functions
	from within this function. See <a href="#howto">how to write
	a cgic application</a> for details.
</dl>
<h3><a name="variables">cgic variable reference</a></h3>
This section provides a reference guide to the various global
variables provided by cgic for the programmer to utilize.
These variables should always be used in preference to
stdin, stdout, and calls to getenv() in order to ensure
compatibility with the <a href="#debug">cgic CGI debugging features</a>.
<p>
Most of these variables are equivalent to various CGI environment
variables. The most important difference is that the cgic
environment string variables are never null pointers. They will always 
point to valid C strings of zero or more characters.
<dl>
<dt><a name="cgiServerSoftware">char *cgiServerSoftware</a>
<dd>Points to the name of the server software,
or to an empty string if unknown.
<dt><a name="cgiServerName">char *cgiServerName</a>
<dd>Points to the name of the server,
or to an empty string if unknown.
<dt><a name="cgiGatewayInterface">char *cgiGatewayInterface</a>
<dd>Points to the name of the gateway interface (usually CGI/1.1),
or to an empty string if unknown.
<dt><a name="cgiServerProtocol">char *cgiServerProtocol</a>
<dd>Points to the protocol in use (usually HTTP/1.0),
or to an empty string if unknown.
<dt><a name="cgiServerPort">char *cgiServerPort</a>
<dd>Points to the port number on which the server is listening
for HTTP connections (usually 80), or an empty string if unknown.
<dt><a name="cgiRequestMethod">char *cgiRequestMethod</a>
<dd>Points to the method used in the request (usually GET or POST),
or an empty string if unknown (this should not happen).
<dt><a name="cgiPathInfo">char *cgiPathInfo</a>
<dd>Most web servers recognize any additional path information in 
the URL of the request beyond the name of the CGI program itself and
pass that information on to the program. cgiPathInfo points to this
additional path information.
<dt><a name="cgiPathTranslated">char *cgiPathTranslated</a>
<dd>Most web servers recognize any additional path information in 
the URL of the request beyond the name of the CGI program itself and
pass that information on to the program. cgiPathTranslated points
to this additional path information, translated by the server into a 
filesystem path on the local server.
<dt><a name="cgiScriptName">char *cgiScriptName</a>
<dd>Points to the name under which the program was invoked.
<dt><a name="cgiQueryString">char *cgiQueryString</a>
<dd>Contains any query information submitted by the user as a result
of a GET-method form or an &lt;ISINDEX&gt; tag. Note that this
information need not be parsed directly unless an &lt;ISINDEX&gt; tag
was used; normally it is parsed automatically by the cgic library. Use 
the cgiForm family of functions to retrieve the values associated
with form input fields. See <a href="#howto">how to write
a cgic application</a> for more information.
<dt><a name="cgiRemoteHost">char *cgiRemoteHost</a>
<dd>Points to the fully resolved hostname of the browser, if known,
or an empty string if unknown.
<dt><a name="cgiRemoteAddr">char *cgiRemoteAddr</a>
<dd>Points to the dotted-decimal IP address of the browser, if known,
or an empty string if unknown.
<dt><a name="cgiAuthType">char *cgiAuthType</a>
<dd>Points to the type of authorization used for the request,
if any, or an empty string if none or unknown.
<dt><a name="cgiRemoteUser">char *cgiRemoteUser</a>
<dd>Points to the user name under which the user has 
authenticated; an empty string if no authentication has
taken place. The certainty of this information depends on
the type of authorization in use; see
<a href="#cgiAuthType">cgiAuthType</a>.
<dt><a name="cgiRemoteIdent">char *cgiRemoteIdent</a>
<dd>Points to the user name volunteered by the user via
the user identification protocol; an empty
string if unknown. This information is not secure.
Identification demons can be installed by users on
insecure systems such as Windows machines.
<dt><a name="cgiContentType">char *cgiContentType</a>
<dd>Points to the MIME content type of the information
submitted by the user, if any; an empty string if no
information was submitted. If this string is equal to
<code>application/x-www-form-urlencoded</code>, the cgic
library will automatically examine the form data submitted.
If this string has any other non-empty value, a different
type of data has been submitted. This is currently very rare,
as most browsers can only submit forms,
but if it is of interest to your application, the submitted data can 
be read from the <a href="#cgiIn">cgiIn</a> file pointer.
<dt><a name="cgiAccept">char *cgiAccept</a>
<dd>Points to a space-separated list of MIME content types
acceptable to the browser (see <a href="#cgiHeaderContentType">
cgiHeaderContentType()</a> ), or an empty string. Unfortunately, this variable
is not supplied in a useful form by most current browsers. Programmers wishing
to make decisions based on the capabilities of the browser
are advised to check the <a href="#cgiUserAgent">cgiUserAgent</a>
variable against a list of browsers and capabilities instead.
<dt><a name="cgiUserAgent">char *cgiUserAgent</a>
<dd>
Points to the name of the browser in use, or an empty
string if this information is not available. 
<dt><a name="cgiReferrer">char *cgiReferrer</a>
<dd>
Points to the URL of the previous page visited by the user. This is
often the URL of the form that brought the user to your program.
Note that reporting this information is entirely up to the browser,
which may choose not do so, and may choose not to do so truthfully.
However, this variable is typically accurate. <strong>The frequently
used misspelling cgiReferer is also supplied as a macro.</strong>
<dt><a name="cgiContentLength">int cgiContentLength</a>
<dd>The number of bytes of form or query data received.
	Note that if the submission is a form or query submission
	the library will read and parse all the information
	directly from cgiIn and/or cgiQueryString. The programmer should
	not do so, and indeed the cgiIn pointer will be at end-of-file
	in such cases.
<dt><a name="cgiOut">FILE *cgiOut</a>
<dd>Pointer to CGI output. The cgiHeader functions, such as
	<a href="#cgiHeaderContentType">cgiHeaderContentType</a>, should 
	be used first to output the mime headers; the output HTML
	page, GIF image or other web document should then be written
	to cgiOut by the programmer using standard C I/O functions
	such as fprintf() and fwrite(). cgiOut is normally equivalent
	to stdout; however, it is recommended that cgiOut be used to
	ensure compatibility with future versions of cgic for
	specialized environments.
<dt><a name="cgiIn">FILE *cgiIn</a>
<dd>Pointer to CGI input. In 99% of cases, you will not 
	need this. However, in future applications, documents other than 
	form data are posted to the server, in which case this file 
	pointer may be read from in order to retrieve the contents. 
</dl>
<H3><a name="resultcodes">cgic result code reference</a></h3>
<p>
In most cases, cgic functions are designed to produce reasonable results
even when browsers and users do unreasonable things. However, it is sometimes
important to know precisely which unreasonable things took place, especially
when assigning a default value or bounding a value is an inadequate
solution. The following result codes are useful in making this determination.
<dl>
<dt><a name="cgiFormSuccess">cgiFormSuccess</a>
<dd>Indicates that the function successfully performed at least one
action (or retrieved at least one value, where applicable).
<dt><a name="cgiFormTruncated">cgiFormTruncated</a>
<dd>Indicates that a string value retrieved from the user was
cut short to avoid overwriting the end of a buffer.
<dt><a name="cgiFormBadType">cgiFormBadType</a>
<dd>Indicates that a "numeric" value submitted by the user was
in fact not a legal number.
<dt><a name="cgiFormEmpty">cgiFormEmpty</a>
<dd>Indicates that a field was retrieved but contained no data.
<dt><a name="cgiFormNotFound">cgiFormNotFound</a>
<dd>Indicates that no value was submitted for a particular field.
<dt><a name="cgiFormConstrained">cgiFormConstrained</a>
<dd>Indicates that a numeric value was beyond the specified bounds
and was forced to the lower or upper bound as appropriate.
<dt><a name="cgiFormNoSuchChoice">cgiFormNoSuchChoice</a>
<dd>Indicates that the value submitted for a single-choice field
(such as a radio-button group) was not one of the acceptable values.
This usually indicates a discrepancy between the form and the program.
<dt><a name="cgiEnvironmentIO">cgiEnvironmentIO</a>
<dd>Indicates that an attempt to read or write the CGI environment
to or from a capture file failed due to an I/O error.
<dt><a name="cgiEnvironmentMemory">cgiEnvironmentMemory</a>
<dd>Indicates that an attempt to read or write the CGI environment
to or from a capture file failed due to an out-of-memory error.
<dt><a name="cgiEnvironmentSuccess">cgiEnvironmentSuccess</a>
<dd>Indicates that an attempt to read or write the CGI environment
to or from a capture file was successful.
</dl>
<h3><a name="index">cgic quick index</a></h3>
<a href="#cgiAccept">cgiAccept</a> |
<a href="#cgiAuthType">cgiAuthType</a> |
<a href="#cgiContentLength">cgiContentLength</a> |
<a href="#cgiContentType">cgiContentType</a> |
<a href="#cgiEnvironmentIO">cgiEnvironmentIO</a> |
<a href="#cgiEnvironmentMemory">cgiEnvironmentMemory</a> |
<a href="#cgiEnvironmentSuccess">cgiEnvironmentSuccess</a> |
<a href="#cgiFormBadType">cgiFormBadType</a> |
<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a> |
<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle()</a> |
<a href="#cgiFormConstrained">cgiFormConstrained</a> |
<a href="#cgiFormDouble">cgiFormDouble()</a> |
<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a> |
<a href="#cgiFormEmpty">cgiFormEmpty</a> |
<a href="#cgiFormInteger">cgiFormInteger()</a> |
<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded()</a> |
<a href="#cgiFormNoSuchChoice">cgiFormNoSuchChoice</a> |
<a href="#cgiFormNotFound">cgiFormNotFound</a> |
<a href="#cgiFormRadio">cgiFormRadio()</a> |
<a href="#cgiFormSelectMultiple">cgiFormSelectMultiple()</a> |
<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> |
<a href="#cgiFormString">cgiFormString()</a> |
<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> |
<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a> |
<a href="#cgiFormStringSpaceNeeded">cgiFormStringSpaceNeeded()</a> |
<a href="#cgiFormSuccess">cgiFormSuccess</a> |
<a href="#cgiFormTruncated">cgiFormTruncated</a> |
<a href="#cgiGatewayInterface">cgiGatewayInterface</a> |
<a href="#cgiHeaderContentType">cgiHeaderContentType()</a> |
<a href="#cgiHeaderLocation">cgiHeaderLocation()</a> |
<a href="#cgiHeaderStatus">cgiHeaderStatus()</a> |
<a href="#cgiIn">cgiIn</a> |
<a href="#cgiMain">cgiMain()</a>
<a href="#cgiOut">cgiOut</a> |
<a href="#cgiPathInfo">cgiPathInfo</a> |
<a href="#cgiPathTranslated">cgiPathTranslated</a> |
<a href="#cgiQueryString">cgiQueryString</a> |
<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> |
<a href="#cgiReferrer">cgiReferrer()</a> |
<a href="#cgiRemoteAddr">cgiRemoteAddr</a> |
<a href="#cgiRemoteHost">cgiRemoteHost</a> |
<a href="#cgiRemoteIdent">cgiRemoteIdent</a> |
<a href="#cgiRemoteUser">cgiRemoteUser</a> |
<a href="#cgiRequestMethod">cgiRequestMethod</a> |
<a href="#cgiScriptName">cgiScriptName</a> |
<a href="#cgiServerName">cgiServerName</a> |
<a href="#cgiServerPort">cgiServerPort</a> |
<a href="#cgiServerProtocol">cgiServerProtocol</a> |
<a href="#cgiServerSoftware">cgiServerSoftware</a> |
<a href="#cgiStringArrayFree">cgiStringArrayFree()</a> |
<a href="#cgiUserAgent">cgiUserAgent</a> |
<a href="#cgiWriteEnvironment">cgiWriteEnvironment()</a>
<p>
<hr>
<em><a href="http://www.boutell.com/">Boutell.Com, Inc.</a></em>
</body>
</html>