cgic.html

一般的UNIX系统都支持ANSI C,增加相应的库函数(和相应的h文件)就可以实现CGI,用于CGI编程的ANSI C库

is the buffer to which the data should be copied, 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>
The actual name submitted by the user may or may not contain
characters that have special meaning in HTML, specifically the
the <code>&lt;</code>, <code>&gt;</code>, and <code>&amp;</code> characters.
The <a href="#cgiHtmlEscape">cgiHtmlEscape</a> function is used to output
the user-entered name with any occurrences of these characters
correctly escaped as <code>&amp;lt;</code>, <code>&amp;gt;</code>, 
and <code>&amp;amp;</code>.
<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 modified 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>