cgic.html

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

	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
		"value=\"2\">2\n");
	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
		"value=\"3\" checked>3\n");
	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
		"value=\"4\">4\n");
	fprintf(cgiOut, "<p>Nonexclusive Checkbox Group: "
		"Voting for Zero through Four Candidates\n");
	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
		"value=\"A\">A\n");
	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
		"value=\"B\">B\n");
	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
		"value=\"C\">C\n");
	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
		"value=\"D\">D\n");
	fprintf(cgiOut, "<p>File Upload:\n");
	fprintf(cgiOut, "<input type=\"file\" name=\"file\" "
		"value=\"\"> (Select A Local File)\n");
	fprintf(cgiOut, "<p>\n");
	fprintf(cgiOut, "<p>Set a Cookie<p>\n");
	fprintf(cgiOut, "<input name=\"cname\" "
		"value=\"\"> Cookie Name\n");
	fprintf(cgiOut, "<input name=\"cvalue\" "
		"value=\"\"> Cookie Value<p>\n");
	fprintf(cgiOut, "<input type=\"submit\" "
		"name=\"testcgic\" value=\"Submit Request\">\n");
	fprintf(cgiOut, "<input type=\"reset\" "
		"value=\"Reset Request\">\n");
	fprintf(cgiOut, "<p>Save the CGI Environment<p>\n");
	fprintf(cgiOut, "Pressing this button will submit the form, then "
		"save the CGI environment so that it can be replayed later "
		"by calling cgiReadEnvironment (in a debugger, for "
		"instance).<p>\n");
	fprintf(cgiOut, "<input type=\"submit\" name=\"saveenvironment\" "
		"value=\"Save Environment\">\n");
	fprintf(cgiOut, "</form>\n");
}
</pre>
Note the use of <code>enctype="multipart/form-data"</code> in the
<code>FORM</code> tag. This is absolutely required if the form
will contain file upload fields, as in the above example. Most
browsers will not even attempt file uploads without the
presence of this attribute.
<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://www.boutell.com/gd/">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 or set of form fields 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, including file uploads,
cookies and all other phenomena within the purview of cgic.
<p>
<strong>Important:</strong> Make sure you specify the full path, as 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>
<br><dt><strong><a name="cgiFormString">cgiFormResultType cgiFormString(
	char *name, char *result, int max)</a>
</strong><br><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, 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><br><dt><strong><a name="cgiFormStringNoNewlines">
cgiFormResultType cgiFormStringNoNewlines(
	char *name, char *result, int max)</a>
</strong><br><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><br><dt><strong><a name="cgiFormStringSpaceNeeded">
cgiFormResultType cgiFormStringSpaceNeeded(
	char *name, int *length)</a>
</strong><br><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><br><dt><strong><a name="cgiFormStringMultiple">cgiFormResultType cgiFormStringMultiple(
	char *name, char ***ptrToStringArray)</a>
</strong><br><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><br><dt><strong><a name="cgiFormEntries">cgiFormResultType cgiFormEntries(
	char *name, char ***ptrToStringArray)</a>
</strong><br><dd>cgiFormEntries is useful when the programmer cannot know the names
	of all relevant form fields in advance. 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. cgiFormEntries() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> except in the event of an out of memory error.
	On success, 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, and 
	<a href="#cgiFormOutOfMemory">cgiFormOutOfMemory</a> is returned.

<br><br><dt><strong><a name="cgiStringArrayFree">void cgiStringArrayFree(char **stringArray)
</a>
</strong><br><dd>
cgiStringArrayFree() is used to free the memory associated with
	a string array created by 
	<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>,
	<a href="#cgiFormEntries">cgiFormEntries()</a>, or
	<a href="#cgiFormCookies">cgiFormCookies()</a>.
<br><br><dt><strong><a name="cgiFormInteger">cgiFormResultType cgiFormInteger(
	char *name, int *result, int defaultV)</a>
</strong><br><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><br><dt><strong><a name="cgiFormIntegerBounded">
cgiFormResultType cgiFormIntegerBounded(
	char *name, int *result, int min, int max, int defaultV)</a>
</strong><br><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><br><dt><strong><a name="cgiFormDouble">cgiFormResultType cgiFormDouble(
	char *name, double *result, double defaultV)</a>
</strong><br><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><br><dt><strong><a name=