cgic.html @ 615

Last change on this file since 615 was 348, checked in by neteler, 13 years ago
set correctly svn propset
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id` Property svn:mime-type set to `text/html`
File size: 103.4 KB

Rev	Line
[1]	1	<html>
	2	<head>
	3	<title>cgic: an ANSI C library for CGI Programming</title>
	4	</head>
	5	<body>
	6	<h1>cgic 2.05: an ANSI C library for CGI Programming</h1>
	7	<h2>By <a href="http://www.boutell.com/boutell/">Thomas Boutell</a></h2>
	8	<em><a href="http://www.boutell.com/cgic/">
	9	The LATEST documentation is available here. Check often
	10	for new releases.</a></em>
	11	<blockquote>
	12	<strong>IMPORTANT NOTICES:</strong>
	13	<p>
	14	If you have CGIC 1.05 or earlier, you should upgrade to CGIC 1.07,
	15	or to CGIC 2.02 or better, in order to obtain important security fixes.
	16	<p>
	17	If you have CGIC 2.0 or CGIC 2.01 and you use the cgiCookie routines,
	18	you should upgrade to CGIC 2.02 or better, in order to obtain
	19	important security fixes.
	20	</blockquote>
	21	<h3>Table of Contents</h3>
	22	<ul>
	23	<li><a href="#credits">Credits and license terms</a>
	24	<li><a href="#support">How to get support</a>
	25	<li><a href="#whatsnew205">What's new in version XYZ of CGIC?</a>
	26	<li><a href="#whatis">What is cgic?</a>
	27	<li><a href="#obtain">Obtaining cgic</a>
	28	<li><a href="#build">Building and testing cgic: a sample application</a>
	29	<li><a href="#nocompile">What to do if it won't compile</a>
	30	<li><a href="#howto">How to write a cgic application</a>
	31	<li><a href="#images">How can I generate images from my cgic application?</a>
	32	<li><a href="#debug">CGI debugging features: using capture</a>
	33	<li><a href="#functions">cgic function reference</a>
	34	<li><a href="#variables">cgic variable reference</a>
	35	<li><a href="#resultcodes">cgic result code reference</a>
	36	<li><a href="#index">cgic quick index</a>
	37	</ul>
	38
	39	<h3><a name="credits">Credits and License Terms</a></h3>
	40
	41	cgic can be used free of charge, <strong>provided that a
	42	credit notice is provided online.</strong> Alternatively,
	43	a nonexclusive Commercial License can be purchased, which
	44	grants the right to use cgic without a public credit notice.
	45	<p>
	46	Please see the file
	47	<code><a href="license.txt">license.txt</a></code>
	48	for the details of the Basic License and Commercial License,
	49	including ordering information for the Commercial License.
	50	<p>
	51	Thanks are due to Robert Gustavsson, Ken Holervich, Bob Nestor,
	52	Jon Ribbens, Thomas Strangert, Wu Yongwei, and other CGIC users
	53	who have corresponded over the years. Although the implementation
	54	of multipart/form-data file upload support in CGIC 2.x is my own,
	55	I particularly wish to thank those who submitted their own
	56	implementations of this feature.
	57	<h3><a name="support">How to Get Support</a></h3>
	58	<blockquote>
	59	<h4>STOP! READ THIS FIRST! REALLY!</h4>
	60	Are you getting a "server error," indicating that your web server
	61	"cannot allow POST to this URL," or a similar message? <strong>YOU MUST
	62	CONFIGURE YOUR WEB SERVER TO ALLOW CGI PROGRAMS, AND YOU MUST
	63	INSTALL CGI PROGRAMS IN THE LOCATION (OR WITH THE EXTENSION) THAT
	64	YOUR WEB SERVER EXPECTS TO SEE.</strong> Please don't send me email about
	65	this, unless you wish me to configure your web server for you; I can
	66	certainly do that for $50/hr, but you can probably straighten this out
	67	yourself or have your web server administrator do it.
	68	</blockquote>
	69	<h4>Free Support</h4>
	70	Please submit support inquiries about CGIC via our <a href="http://www.boutell.com/contact/">contact page</a>.
	71	Please note that we receive a large volume of inquiries and cannot always
	72	respond personally. Sometimes
	73	the response must take the form of an eventual
	74	new release or an addition to a FAQ or other document, as opposed to an
	75	detailed individual response.
	76	<h4>Hourly Support</h4>
	77	Those requiring support in detail may arrange for direct support
	78	from the author, Thomas Boutell, at the rate of $50/hr, billed
	79	directly by credit card. To make arrangements, contact us via our
	80	our <a href="https://www.boutell.com/freeform/">secure
	81	message page</a>. To avoid delay, be sure to specifically mention
	82	that you wish to purchase CGIC support at the hourly rate above.
	83	<h3><a name="whatsnew205">What's new in version 2.05?</a></h3>
	84	Uploaded files properly closed; corrects a resource leak and enables
	85	file uploads to work properly on platforms with particular file
	86	locking semantics.
	87	<h3><a name="whatsnew204">What's new in version 2.04?</a></h3>
	88	Documentation fixes: the cgiHtmlEscape, cgiHtmlEscapeData,
	89	cgiValueEscape, and cgiValueEscapeData routines were named
	90	incorrectly in the manual. No code changes in version 2.04.
	91	<h3><a name="whatsnew203">What's new in version 2.03?</a></h3>
	92	<ul>
	93	<li>Support for setting cookies has been reimplemented. The new
	94	code closely follows the actual practice of web sites that successfully
	95	use cookies, rather than attempting to implement the specification.
	96	The new code can successfully set more than one cookie at a time in
	97	typical web browsers.
	98	</ul>
	99	<h3><a name="whatsnew202">What's new in version 2.02?</a></h3>
	100	<ul>
	101	<li>In CGIC 2.0 and 2.01, if the HTTP_COOKIE environment variable
	102	was exactly equal to the name of a cookie requested with cgiCookieString,
	103	with no value or equal sign or other characters present, a buffer
	104	overrun could take place. This was not normal behavior and it is
	105	unknown whether any actual web server would allow it to occur, however
	106	we have of course released a patch to correct it.
	107	Thanks to Nicolas Tomadakis.
	108	<li>cgiCookieString returned cgiFormTruncated when cgiFormSuccess would
	109	be appropriate. Fixed; thanks to Mathieu Villeneuve-Belair.
	110	<li>Cookies are now set using a simpler Set-Cookie: header, and with
	111	one header line per cookie, based on data collected by Chunfu Lai.
	112	<li>Memory leaks in cgiReadEnvironment fixed by Merezko Oleg. These
	113	memory leaks were <em>not</em> experienced in a normal CGI situation, only
	114	when reading a saved CGI environment.
	115	</ul>
	116	<h3><a name="whatsnew201">What's new in version 2.01?</a></h3>
	117	<ul>
	118	<li>Makefile supports "make install"
	119	<li>Compiles without warnings under both C and C++ with strict
	120	warnings and strict ANSI compliance enabled
	121	<li>Builds out of the box on Windows (#include <fcntl.h> was needed)
	122	<li>Rare problem in cgiReadEnvironment corrected; no impact on
	123	normal CGI operations
	124	<li>cgiCookieString now sets the result to an empty string
	125	when returning cgiFormNotFound
	126	<li>Minor code cleanups
	127	</ul>
	128	<h3><a name="whatsnew200">What's new in version 2.0?</a></h3>
	129	1. CGIC 2.0 provides support for file upload fields. User-uploaded
	130	files are kept in temporary files, to avoid the use of
	131	excessive swap space (Solaris users may wish to change the
	132	<code>cgicTempDir</code> macro in cgic.c before compiling).
	133	The <code><a href="#cgiFormFileName">cgiFormFileName</a></code>,
	134	<code><a href="#cgiFormFileContentType">cgiFormFileContentType</a></code>,
	135	<code><a href="#cgiFormFileSize">cgiFormFileSize</a></code>,
	136	<code><a href="#cgiFormFileOpen">cgiFormFileOpen</a></code>,
	137	<code><a href="#cgiFormFileRead">cgiFormFileRead</a></code>, and
	138	<code><a href="#cgiFormFileClose">cgiFormFileClose</a></code> functions
	139	provide a complete interface to this new functionality. Remember,
	140	the <code>enctype</code> attribute of the <code>form</code> tag
	141	must be set to <code>multipart/form-data</code> when
	142	<code><input type="file"></code> tags are used.
	143	<p>
	144	2. CGIC 2.0 provides support for setting and examining cookies
	145	(persistent data storage on the browser side).
	146	The <code><a href="#cgiCookieString">cgiCookieString</a></code>,
	147	and <code><a href="#cgiCookieInteger">cgiCookieInteger</a></code>
	148	and <code><a href="#cgiCookies">cgiCookies</a></code>
	149	functions retrieve cookies. The
	150	<code><a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a></code>
	151	and <code><a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a></code> functions set cookies.
	152	<p>
	153	3. CGIC 2.0 offers a convenient way to retrieve a list of all form fields.
	154	The new <code><a href="#cgiFormEntries">cgiFormEntries</a></code>
	155	function performs this operation.
	156	<p>
	157	4. CGIC 2.0 provides convenience functions to correctly escape
	158	text before outputting it as part of HTML, or as part of the
	159	value of a tag attribute, such as the <code>HREF</code> or
	160	<code>VALUE</code> attribute. See
	161	<code><a href="#cgiHtmlEscape">cgiHtmlEscape</a></code>,
	162	<code><a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a></code>,
	163	<code><a href="#cgiValueEscape">cgiValueEscape</a></code> and
	164	<code><a href="#cgiValueEscapeData">cgiValueEscapeData</a></code>.
	165	<p>
	166	5. Users have often asked the correct way to determine which submit
	167	button was clicked. This could always be accomplished in previous versions,
	168	but CGIC 2.0 also provides
	169	<a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a>,
	170	a convenient alternate label for the
	171	<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a> function.
	172	<h3><a name="whatsnew107">What's new in version 1.07?</a></h3>
	173	A problem with the cgiFormString and related functions has been
	174	corrected. These functions were previously incorrectly returning cgiFormTruncated
	175	in cases where the returned string fit the buffer exactly.
	176	<h3><a name="whatsnew106">What's new in version 1.06?</a></h3>
	177	1. A potentially significant buffer overflow problem has been
	178	corrected. Jon Ribbens correctly pointed out to me (and to the
	179	Internet's bugtraq mailing list) that the cgiFormEntryString
	180	function, which is used directly or indirectly by almost all
	181	CGIC programs, can potentially write past the buffer passed
	182	to it by the programmer. This bug has been corrected.
	183	Upgrading to version 1.06 is <strong>strongly recommended.</strong>
	184	<P>
	185	2. The function <code>cgiSaferSystem()</code> has been
	186	removed entirely. This function escaped only a few metacharacters,
	187	while most shells have many, and there was no way to account for
	188	the many different operating system shells that might be in use
	189	on different operating systems. Since this led to a false sense
	190	of security, the function has been removed. It is our recommendation
	191	that user input should never be passed directly on the command line
	192	unless it has been carefully shown to contain only characters
	193	regarded as safe and appropriate by the programmer. Even then, it is
	194	better to design your utilities to accept their input from standard
	195	input rather than the command line.
	196	<h3><a name="whatsnew105">What's new in version 1.05?</a></h3>
	197	Non-exclusive commercial license fee reduced to $200.
	198	<h3><a name="whatsnew104">What's new in version 1.04?</a></h3>
	199	For consistency with other packages, the standard Makefile
	200	now produces a true library for cgic (libcgic.a).
	201	<h3><a name="whatsnew103">What's new in version 1.03?</a></h3>
	202	Version 1.03 sends line feeds only (ascii 10) to end
	203	Content-type:, Status:, and other HTTP protocol output lines,
	204	instead of CR/LF sequences. The standard specifies CR/LF.
	205	Unfortunately, too many servers reject CR/LF to make
	206	implementation of that standard practical. No server
	207	tested ever rejects LF alone in this context.
	208	<h3><a name="whatsnew102">What's new in version 1.02?</a></h3>
	209	Version 1.02 corrects bugs in previous versions:
	210	<ul>
	211	<li>
	212	<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> specified
	213	its arguments in the wrong order, with surprising results.
	214	This bug has been corrected.
	215	<li>
	216	Many small changes have been made to increase compatibility.
	217	cgic now compiles with no warnings under the compilers
	218	available at boutell.com.
	219	</ul>
	220	<h3><a name="whatsnew101">What's new in version 1.01?</a></h3>
	221	Version 1.01 adds no major functionality but corrects
	222	significant bugs and incompatibilities:
	223	<ul>
	224	<li>
	225	<a href="#cgiFormInteger">cgiFormInteger</a>,
	226	<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>,
	227	<a href="#cgiFormDouble">cgiFormDouble</a> and
	228	<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> now
	229	accept negative numbers properly. They also accept positive
	230	numbers with an explicit + sign.
	231	<li>Hex values containing the digit <code>9</code> are
	232	now properly decoded.
	233	<li><a href="#cgiFormString">cgiFormString</a> now
	234	represents each newline as a single line feed (ascii 10 decimal)
	235	as described in the documentation, not a carriage return
	236	(ascii 13 decimal) as in version 1.0. The latter approach
	237	pleased no one.
	238	<li><a href="#cgiFormString">cgiFormString</a> and
	239	<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>
	240	no longer erroneously return cgiFormEmpty in place of
	241	cgiFormSuccess.
	242	<li>The main() function of cgic now flushes standard output
	243	and sleeps for one second before exiting in order to inhibit
	244	problems with the completion of I/O on some platforms. This was
	245	not a cgic bug per se, but has been reported as a common problem
	246	with CGI when used with the CERN server. This change should
	247	improve compatibility.
	248	<li>The single selection example in the testform.html
	249	example now works properly. This was an error in the
	250	form itself, not cgic.
	251	<li><a href="#cgiRemoteUser">cgiRemoteUser</a> and
	252	<a href="#cgiRemoteIdent">cgiRemoteIdent</a> are now
	253	documented accurately. They were reversed earlier.
	254	</ul>
	255	<h3><a name="whatis">What is cgic?</a></h3>
	256	cgic is an ANSI C-language library for the creation of CGI-based
	257	World Wide Web applications. For basic information about
	258	the CGI standard, see the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">
	259	CGI documentation</a> at NCSA.
	260	<p>
	261	cgic performs the following tasks:
	262	<ul>
	263	<li>Parses form data, correcting for defective and/or inconsistent browsers
	264	<li>Transparently accepts both GET and POST form data
	265	<li>Accepts uploaded files as well as regular form fields
	266	<li>Provides functions to set and retrieve "cookies"
	267	(browser-side persistent information)
	268	<li>Handles line breaks in form fields in a consistent manner
	269	<li>Provides string, integer, floating-point, and single- and
	270	multiple-choice functions to retrieve form data
	271	<li>Provides bounds checking for numeric fields
	272	<li>Loads CGI environment variables into C strings which are always non-null
	273	<li>Provides a way to capture CGI situations for replay in a debugging
	274	environment, including file uploads and cookies
	275	</ul>
	276	<p>
	277	cgic is compatible with any CGI-compliant server environment, and
	278	compiles without modification in Posix/Unix/Linux and Windows
	279	environments.
	280	<h3><a name="obtain">Obtaining cgic</a></h3>
	281	cgic is distributed via the web in two forms: as a Windows-compatible
	282	.ZIP file, and as a gzipped tar file. Most users of Windows and
	283	related operating systems have access to 'unzip' or 'pkunzip'. All modern Unix
	284	systems come with 'gunzip' and 'tar' as standard equipment, and gzip/gunzip
	285	is not difficult to find if yours does not. Versions
	286	of these programs for other operating systems are widely
	287	available if you do not already have them.
	288	<p>
	289	<strong>Important:</strong> to use cgic, you will need an ANSI-standard
	290	C compiler. Under Unix, just obtain and use gcc. Most Unix systems have
	291	standardiszed on gcc. Users of Windows operating systems should not have
	292	ANSI C-related problems as all of the popular compilers follow the ANSI
	293	standard.
	294	<p>
	295	<strong>Note for Windows Programmers:</strong> you must use a modern
	296	32-bit compiler. Visual C++ 2.0 or higher, Borland C++ and the
	297	mingw32 gcc compiler are all appropriate, as is cygwin. Do
	298	<strong>NOT</strong> use an ancient 16-bit DOS executable compiler, please.
	299	<blockquote>
	300	<h4>What Operating System Does Your WEB SERVER Run?</h4>
	301	Remember, the computer on your desk is usually NOT your web server.
	302	Compiling a Windows console executable will not give you a CGI program that
	303	can be installed on a Linux-based server.
	304	</blockquote>
	305	Your web browser should inquire whether to save the file to disk
	306	when you select one of the links below. Under Unix and compatible
	307	operating systems, save it, then issue the following
	308	commands to unpack it:
	309	<pre>
	310	gunzip cgic205.tar.gz
	311	tar -xf cgic205.tar
	312	</pre>
	313	This should produce the subdirectory 'cgic205', which will contain
	314	the complete cgic distribution for version 2.05, including a copy of this
	315	documentation in the file cgic.html.
	316	<p>
	317	Under Windows and compatible operating systems, save it,
	318	open a console ("DOS") window, and issue the following commands to unpack it:
	319	<pre>
	320	unzip /d cgic205.zip
	321	</pre>
	322	Or use the unzip utility of your choice.
	323	<p>
	324	This command also produces the subdirectory 'cgic205', which will contain
	325	the complete cgic distribution for version 2.0, including a copy of this
	326	documentation in the file cgic.html.
	327	<p>
	328	cgic is available via the web from www.boutell.com:
	329	<ul>
	330	<li><a href="http://www.boutell.com/cgic/cgic205.tar.gz">Obtain cgic: gzipped tar file</a>
	331	<li><a href="http://www.boutell.com/cgic/cgic205.zip">Obtain cgic: .ZIP file</a>
	332	</ul>
	333	<h3><a name="build">Building cgic: a sample application</a></h3>
	334	The sample application 'cgictest.c' is provided as part of the
	335	cgic distribution. This CGI program displays an input form,
	336	accepts a submission, and then displays what was submitted.
	337	In the process essentially all of cgic's features are tested.
	338	<p>
	339	On a Unix system, you can build cgictest simply by typing
	340	'make cgictest.cgi'. cgic.c and cgictest.c will be compiled and linked
	341	together to produce the cgictest application. Under non-Unix
	342	operating systems, you will need to create and compile an appropriate
	343	project containing the files cgic.c and cgictest.c.
	344	<p>
	345	<strong>IMPORTANT:</strong> after compiling cgictest.cgi, you will
	346	need to place it in a location on your server system which is
	347	designated by your server administrator as an appropriate location
	348	for CGI scripts. Some servers are configured to recognize any
	349	file ending in .cgi as a CGI program when it is found in any
	350	subdirectory of the server's web space, but this is not always
	351	the case! The right locations for CGI
	352	programs vary greatly from one server to another. Resolving
	353	this issue is between you, your web server administrator,
	354	and your web server documentation. Before submitting a bug
	355	report for cgic, make certain that the CGI example programs
	356	which came with your server <em>do</em> work for you. Otherwise
	357	it is very likely that you have a server configuration problem.
	358	<p>
	359	Once you have moved cgictest.cgi (or cgictest.exe, under Windows)
	360	to an appropriate cgi directory,
	361	use the web browser of your choice to access the URL at which
	362	you have installed it
	363	(for instance, <code>www.mysite.com/cgi-bin/cgictest.cgi</code>).
	364	Fill out the various fields in any manner you wish, then
	365	select the SUBMIT button.
	366	<p>
	367	If all goes well, cgictest.cgi will respond with a page which
	368	indicates the various settings you submitted. If not,
	369	please reread the section above regarding the correct location in
	370	which to install your CGI program on your web server.
	371	<h3><a name="nocompile">What to do if it won't compile</a></h3>
	372	<ul>
	373	<li><strong>Are you using Visual C++ or Borland C++? Did you forget to add
	374	cgic.c to your project?</strong>
	375	<li><strong>Make sure you are using an ANSI C or C++ compiler.</strong>
	376	(All of the Windows compilers are ANSI C compliant.)
	377	</ul>
	378	If none of the above proves effective, please see the
	379	section regarding <a href="#support">support</a>.
	380	<h3><a name="howto">How to write a cgic application</a></h3>
	381	<em>Note: </em> All cgic applications must be linked to the cgic.c module
	382	itself. How to do this depends on your operating system; under Unix,
	383	just use the provided Makefile as an example.
	384	<p>
	385	Since all CGI applications must perform certain initial
	386	tasks, such as parsing form data and examining
	387	environment variables, the cgic library provides its
	388	own main() function. When you write applications that
	389	use cgic, you will begin your own programs by writing
	390	a cgiMain() function, which cgic will invoke when
	391	the initial cgi work has been successfully completed. Your
	392	program must also be sure to #include the file cgic.h.
	393	<p>
	394	<strong>Important:</strong> if you write your own main()
	395	function, your program will not link properly. Your own
	396	code should begin with cgiMain(). The library
	397	provides main() for you. (Those who prefer different behavior
	398	can easily modify cgic.c.)
	399	<p>
	400	Consider the cgiMain function of cgictest.c:
	401	<p>
	402	<PRE>
	403	int cgiMain() {
	404	#ifdef DEBUG
	405	LoadEnvironment();
	406	#endif /* DEBUG */
	407	/* Load a previously saved CGI scenario if that button
	408	has been pressed. */
	409	if (cgiFormSubmitClicked("loadenvironment") == cgiFormSuccess) {
	410	LoadEnvironment();
	411	}
	412	/* Set any new cookie requested. Must be done before
	413	outputting the content type. */
	414	CookieSet();
	415	/* Send the content type, letting the browser know this is HTML */
	416	cgiHeaderContentType("text/html");
	417	/* Top of the page */
	418	fprintf(cgiOut, "<HTML><HEAD>\n");
	419	fprintf(cgiOut, "<TITLE>cgic test</TITLE></HEAD>\n");
	420	fprintf(cgiOut, "<BODY><H1>cgic test</H1>\n");
	421	/* If a submit button has already been clicked, act on the
	422	submission of the form. */
	423	if ((cgiFormSubmitClicked("testcgic") == cgiFormSuccess) \|\|
	424	cgiFormSubmitClicked("saveenvironment") == cgiFormSuccess)
	425	{
	426	HandleSubmit();
	427	fprintf(cgiOut, "<hr>\n");
	428	}
	429	/* Now show the form */
	430	ShowForm();
	431	/* Finish up the page */
	432	fprintf(cgiOut, "</BODY></HTML>\n");
	433	return 0;
	434	}
	435	</PRE>
	436	Note the DEBUG #ifdef. If DEBUG is defined at compile time, either by
	437	inserting the line "#define DEBUG 1" into the program or by setting
	438	it in the Makefile or other development environment, then the
	439	LoadEnvironment function is invoked. This function calls
	440	<a href="#cgiReadEnvironment">cgiReadEnvironment()</a>
	441	to restore a captured CGI environment for debugging purposes. See
	442	also the discussion of the <a href="#debug">capture</a> program, which is
	443	provided for use in CGI debugging. Because this is a test program,
	444	the <a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a> function is
	445	also called to check for the use of a button that requests the reloading
	446	of a saved CGI environment. A completed CGI program typically would
	447	never allow the end user to make that decision.
	448	<h4>Setting Cookies</h4>
	449	Next, one of the cgiHeader functions should be called.
	450	This particular program demonstrates many features, including
	451	the setting of cookies. If the programmer wishes to set a cookie,
	452	the cookie-setting function must be called
	453	first, before other headers are output. This is done by the
	454	CookieSet() function of cgictest.c:
	455	<pre>
	456	void CookieSet()
	457	{
	458	char cname[1024];
	459	char cvalue[1024];
	460	/* Must set cookies BEFORE calling
	461	cgiHeaderContentType */
	462	cgiFormString("cname", cname, sizeof(cname));
	463	cgiFormString("cvalue", cvalue, sizeof(cvalue));
	464	if (strlen(cname)) {
	465	/* Cookie lives for one day (or until
	466	browser chooses to get rid of it, which
	467	may be immediately), and applies only to
	468	this script on this site. */
	469	cgiHeaderCookieSetString(cname, cvalue,
	470	86400, cgiScriptName, cgiServerName);
	471	}
	472	}
	473	</pre>
	474	Since this is a test program, the <a href="#cgiFormString">cgiFormString</a>
	475	function is used to fetch the name and value from the form previously filled
	476	in by the user. Normally, cookie names and values are chosen to meet the
	477	needs of the programmer and provide a means of identifying the same
	478	user again later.
	479	<p>
	480	The <a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
	481	function sets the cookie by requesting that the web browser store it.
	482	<strong>There is never any guarantee that this will happen!</strong>
	483	Many browsers reject cookies completely; others do not necessarily keep
	484	them as long as requested or return them with their values intact.
	485	Always code defensively when using cookies.
	486	<p>
	487	The cname and cvalue parameters are of course the namd and value for
	488	the cookie. The third argument is the time, in seconds, that the
	489	cookie should "live" on the browser side before it expires; in this
	490	case it has been set to 86,400 seconds, which is exactly one day.
	491	<strong>The browser may or may not respect this setting, as with everything
	492	else about cookies.</strong>
	493	<p>
	494	The fourth argument identifies the "path" within the web site for which
	495	the cookie is considered valid. A cookie that should be sent back
	496	for every access to the site should be set with a path of <code>/</code>.
	497	In this case the cookie is relevant only to the CGI program itself, so
	498	<code><a href="#cgiScriptName">cgiScriptName</a></code> (the URL of the CGI program, not including the
	499	domain name) is sent. Similarly, a cookie can be considered relevant
	500	to a single web site or to an entire domain, such as
	501	<code>www.boutell.com</code> or the entire <code>.boutell.com</code>
	502	domain. In this case, the current site on which the program is running
	503	is the only relevant site, so <code><a href="#cgiServerName">cgiServerName</a></code> is used
	504	as the domain.
	505	<h4>Outputting the Content Type Header</h4>
	506	Next, <a href="#cgiHeaderContentType">cgiHeaderContentType()</a> is
	507	called to indicate the MIME type of the document being output, in this case
	508	"text/html" (a normal HTML document). A few other common MIME types are
	509	"image/gif", "image/jpeg" and "audio/wav".
	510	<p>
	511	Note that <a href="#cgiHeaderStatus">cgiHeaderStatus()</a> or
	512	<a href="#cgiHeaderLocation">cgiHeaderLocation()</a> could have
	513	been invoked instead to output an error code or redirect the
	514	request to a different URL. Only one of the cgiHeader functions
	515	should be called in a single execution of the program.
	516	<p>
	517	<strong>Important:</strong> one of the cgiHeader functions,
	518	usually <a href="#cgiHeaderContentType">cgiHeaderContentType()</a>,
	519	<em>must</em> be invoked before outputting any other
	520	response to the user. Otherwise, the result will not be a valid
	521	document and the browser's behavior will be unpredictable.
	522	You may, of course, output your own ContentType and other
	523	header information to <a href="#cgiOut">cgiOut</a> if you prefer. The cgiHeader functions
	524	are provided as a convenience.
	525	<h4>Handling Form Submissions</h4>
	526	Like many CGI programs, cgictest makes decisions about the way it
	527	should behave based on whether various submit buttons have been clicked.
	528	When either the testcgic or saveenvironment button is present, cgictest
	529	invokes the HandleSubmit function, which invokes additional functions to
	530	handle various parts of the form:
	531	<pre>
	532	void HandleSubmit()
	533	{
	534	Name();
	535	Address();
	536	Hungry();
	537	Temperature();
	538	Frogs();
	539	Color();
	540	Flavors();
	541	NonExButtons();
	542	RadioButtons();
	543	File();
	544	Entries();
	545	Cookies();
	546	/* The saveenvironment button, in addition to submitting
	547	the form, also saves the resulting CGI scenario to
	548	disk for later replay with the 'load saved environment'
	549	button. */
	550	if (cgiFormSubmitClicked("saveenvironment") == cgiFormSuccess) {
	551	SaveEnvironment();
	552	}
	553	}
	554	</pre>
	555	<h4>Handling Text Input</h4>
	556	The Name() function of cgictest is shown below, in its simplest
	557	possible form:
	558	<PRE>
	559	void Name() {
	560	char name[81];
	561	<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>("name", name, 81);
	562	fprintf(cgiOut, "Name: ");
	563	cgicHtmlEscape(name);
	564	fprintf(cgiOut, "<BR>\n");
	565	}
	566	</PRE>
	567	The purpose of this function is to retrieve and display the name that was
	568	input by the user. Since the programmer has decided that names should
	569	be permitted to have up to 80 characters, a buffer of 81 characters
	570	has been declared (allowing for the final null character).
	571	The <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>
	572	function is then invoked to retrieve the name and ensure that
	573	carriage returns are not present in the name (despite the
	574	incorrect behavior of some web browsers). The first argument
	575	is the name of the input field in the form, the second argument
	576	is the buffer to which the data should be copied, and the third
	577	argument is the size of the buffer. cgic will never write beyond
	578	the size of the buffer, and will always provide a null-terminated
	579	string in response; if the buffer is too small, the string will
	580	be shortened. If this is not acceptable, the
	581	<a href="#cgiFormStringSpaceNeeded">cgiFormStringSpaceNeeded()</a>
	582	function can be used to check the amount of space needed; the
	583	return value of cgiFormStringNoNewlines() can also be checked
	584	to determine whether truncation occurred. See
	585	the full description of <a href="#cgiFormStringNoNewlines">
	586	cgiFormStringNoNewlines()</a>.
	587	<h4>Handling Output</h4>
	588	Note that Name() writes its HTML output to <a href="#cgiOut">cgiOut</a>, not
	589	to stdout.
	590	<p>
	591	The actual name submitted by the user may or may not contain
	592	characters that have special meaning in HTML, specifically the
	593	the <code><</code>, <code>></code>, and <code>&</code> characters.
	594	The <a href="#cgiHtmlEscape">cgiHtmlEscape</a> function is used to output
	595	the user-entered name with any occurrences of these characters
	596	correctly escaped as <code>&lt;</code>, <code>&gt;</code>,
	597	and <code>&amp;</code>.
	598	<p>
	599	<strong>Important:</strong> <a href="#cgiOut">cgiOut</a> is normally equivalent
	600	to stdout, and there is no performance penalty for using it.
	601	It is recommended that you write output to <a href="#cgiOut">cgiOut</a> to ensure compatibility
	602	with modified versions of the cgic library for special
	603	environments that do not provide stdin and stdout for
	604	each cgi connection.
	605	<p>
	606	Note that, for text input areas in which carriage returns <em>are</em>
	607	desired, the function <a href="#cgiFormString">cgiFormString</a>
	608	should be used instead. cgiFormString ensures that line breaks
	609	are always represented by a single carriage return (ascii decimal 13),
	610	making life easier for the programmer. See the source code to
	611	the Address() function of cgictest.c for an example.
	612	<h4>Handling Single Checkboxes</h4>
	613	Consider the Hungry() function, which determines whether
	614	the user has selected the "hungry" checkbox:
	615	<PRE>
	616	void Hungry() {
	617	if (<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a>("hungry") == <a href="#cgiFormSuccess">cgiFormSuccess</a>) {
	618	fprintf(cgiOut, "I'm Hungry!<BR>\n");
	619	} else {
	620	fprintf(cgiOut, "I'm Not Hungry!<BR>\n");
	621	}
	622	}
	623	</PRE>
	624	This function takes advantage of the
	625	<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle()</a> function, which
	626	determines whether a single checkbox has been selected.
	627	cgiFormCheckboxSingle() accepts the name attribute of the checkbox
	628	as its sole argument and returns <a href="#cgiFormSuccess">
	629	cgiFormSuccess</a> if the checkbox is selected, or
	630	<a href="#cgiFormNotFound">cgiFormNotFound</a> if it is not.
	631	If multiple checkboxes with the same name are in use,
	632	consider the <a href="#cgiFormCheckboxMultiple">
	633	cgiFormCheckboxMultiple()</a> and
	634	<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>
	635	functions.
	636	<h4>Handling Numeric Input</h4>
	637	Now consider the Temperature() function, which retrieves
	638	a temperature in degrees (a floating-point value) and ensures
	639	that it lies within particular bounds:
	640	<PRE>
	641	void Temperature() {
	642	double temperature;
	643	<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a>("temperature", &temperature, 80.0, 120.0, 98.6);
	644	fprintf(<a href="#cgiOut">cgiOut</a>, "My temperature is %f.<BR>\n", temperature);
	645	}
	646	</PRE>
	647	The temperature is retrieved by the function
	648	<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a>. The first
	649	argument is the name of the temperature input field in the form;
	650	the second argument points to the address of the variable that will
	651	contain the result. The next two arguments are the lower and upper
	652	bounds, respectively. The final argument is the default value to
	653	be returned if the user did not submit a value.
	654	<p>
	655	This function always retrieves a reasonable value within the
	656	specified bounds; values above or below bounds are constrained
	657	to fit the bounds. However, the return value of
	658	cgiFormDoubleBounded can be checked to make sure the
	659	actual user entry was in bounds, not blank, and so forth;
	660	see the description of <a href="#cgiFormDoubleBounded">
	661	cgiFormDoubleBounded()</a> for more details. If bounds checking
	662	is not desired, consider using <a href="#cgiFormDouble">
	663	cgiFormDouble()</a> instead.
	664	<p>
	665	Note that, for integer input, the functions
	666	<a href="#cgiFormInteger">cgiFormInteger</a> and
	667	<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>
	668	are available. The behavior of these functions is similar to
	669	that of their floating-point counterparts above.
	670	<h4>Handling Single-Choice Input</h4>
	671	The <SELECT> tag of HTML is used to provide the user with
	672	several choices. Radio buttons and checkboxes can also be used
	673	when the number of choices is relatively small. Consider
	674	the Color() function of cgictest.c:
	675	<PRE>
	676	char *colors[] = {
	677	"Red",
	678	"Green",
	679	"Blue"
	680	};
	681
	682	void Color() {
	683	int colorChoice;
	684	<a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("colors", colors, 3, &colorChoice, 0);
	685	fprintf(<a href="#cgiOut">cgiOut</a>, "I am: %s<BR>\n", colors[colorChoice]);
	686	}
	687	</PRE>
	688	This function determines which of several colors the user chose
	689	from a <SELECT> list in the form. An array of colors is
	690	declared; the <a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a>
	691	function is then invoked to determine which, if any, of those choices
	692	was selected. The first argument indicates the name of the input
	693	field in the form. The second argument points to the list of
	694	acceptable colors. The third argument indicates the number of
	695	entries in the color array. The fourth argument points to the
	696	variable which will accept the chosen color, and the last argument
	697	indicates the index of the default value to be set if no
	698	selection was submitted by the browser.
	699	<p>
	700	<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> will
	701	always indicate a reasonable selection value. However, if
	702	the programmer wishes to know for certain that a value was
	703	actually submitted, that the value submitted was a legal
	704	response, and so on, the return value of cgiFormSelectSingle()
	705	can be consulted. See the full description of
	706	<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> for
	707	more information.
	708	<p>
	709	Note that radio button groups and <SELECT> lists can both
	710	be handled by this function. If you are processing radio
	711	button groups, you may prefer to invoke
	712	<a href="#cgiFormRadio">cgiFormRadio()</a>, which functions
	713	identically.
	714	<p>
	715	<em>"What if I won't know the acceptable choices at runtime?"</em>
	716	<p>
	717	If the acceptable choices aren't known <em>until</em> runtime,
	718	one can simply load the choices from disk. But if the acceptable
	719	choices aren't fixed at all (consider a list of country names;
	720	new names may be added to the form at any time and it is
	721	inconvenient to also update program code or a separate list
	722	of countries), simply invoke
	723	<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>
	724	instead to retrieve the string directly. Keep in mind that, if
	725	you do so, validating the response to make sure it is
	726	safe and legitimate becomes a problem for your own
	727	program to solve. The advantage of cgiFormSelectSingle() is that invalid
	728	responses are never returned.
	729	<p>
	730	To handle multiple-selection <SELECT> lists and
	731	groups of checkboxes with the same name, see the
	732	discussion of the NonExButtons() function of cgictest.c, immediately below.
	733	<h4>Handling Multiple-Choice Input</h4>
	734	Consider the first half of the NonExButtons() function of cgictest.c:
	735	<PRE>
	736	char *votes[] = {
	737	"A",
	738	"B",
	739	"C",
	740	"D"
	741	};
	742
	743	void NonExButtons() {
	744	int voteChoices[4];
	745	int i;
	746	int result;
	747	int invalid;
	748
	749	char **responses;
	750
	751	/* Method #1: check for valid votes. This is a good idea,
	752	since votes for nonexistent candidates should probably
	753	be discounted... */
	754	fprintf(<a href="#cgiOut">cgiOut</a>, "Votes (method 1):<BR>\n");
	755	result = <a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>("vote", votes, 4,
	756	voteChoices, &invalid);
	757	if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {
	758	fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!<p>\n");
	759	} else {
	760	fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");
	761	fprintf(<a href="#cgiOut">cgiOut</a>, "<ul>\n");
	762	for (i=0; (i < 4); i++) {
	763	if (voteChoices[i]) {
	764	fprintf(<a href="#cgiOut">cgiOut</a>, "<li>%s\n", votes[i]);
	765	}
	766	}
	767	fprintf(<a href="#cgiOut">cgiOut</a>, "</ul>\n");
	768	}
	769	</PRE>
	770	This function takes advantage of
	771	<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a>,
	772	which is used to identify one or more selected checkboxes with
	773	the same name. This function performs identically to
	774	<a href="#cgiFormSelectMultiple">cgiFormSelectMultiple()</a>.
	775	That is, <SELECT> tags with the MULTIPLE attribute are handled
	776	just like a group of several checkboxes with the same name.
	777	<p>
	778	The first argument to <a href="#cgiFormCheckboxMultiple">
	779	cgiFormCheckboxMultiple()</a> is the name given to all
	780	checkbox input fields in the group. The second argument
	781	points to an array of legitimate values; these should
	782	correspond to the VALUE attributes of the checkboxes
	783	(or OPTION tags in a <SELECT> list). The third argument
	784	indicates the number of entries in the array of
	785	legitimate values. The fourth argument points to
	786	an array of integers with the same number of entries
	787	as the array of legitimate values; each entry
	788	will be set true if that checkbox or option was selected,
	789	false otherwise.
	790	<p>
	791	The last argument points to an integer which will be set to the
	792	number of invalid responses (responses not in the array of
	793	valid responses) that were submitted. If this value is not
	794	of interest, the last argument may be a null pointer (0).
	795	<p>
	796	Note that the return value of cgiFormCheckboxMultiple is
	797	inspected to determine whether any choices at all were
	798	set. See the full description of
	799	<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>
	800	for other possible return values.
	801	<p>
	802	<em>"What if I won't know the acceptable choices at runtime?"</em>
	803	<p>
	804	If the acceptable choices aren't known <em>until</em> runtime,
	805	one can simply load the choices from disk. But if the acceptable
	806	choices aren't fixed at all (consider a list of ice cream flavors;
	807	new names may be added to the form at any time and it is
	808	inconvenient to also update program code or a separate list
	809	of countries), a more dynamic approach is needed. Consider
	810	the second half of the NonExButtons() function of cgictest.c:
	811	<PRE>
	812	/* Method #2: get all the names voted for and trust them.
	813	This is good if the form will change more often
	814	than the code and invented responses are not a danger
	815	or can be checked in some other way. */
	816	fprintf(<a href="#cgiOut">cgiOut</a>, "Votes (method 2):<BR>\n");
	817	result = <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &responses);
	818	if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {
	819	fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!<p>\n");
	820	} else {
	821	int i = 0;
	822	fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");
	823	fprintf(<a href="#cgiOut">cgiOut</a>, "<ul>\n");
	824	while (responses[i]) {
	825	fprintf(<a href="#cgiOut">cgiOut</a>, "<li>%s\n", responses[i]);
	826	i++;
	827	}
	828	fprintf(<a href="#cgiOut">cgiOut</a>, "</ul>\n");
	829	}
	830	/* We must be sure to free the string array or a memory
	831	leak will occur. Simply calling free() would free
	832	the array but not the individual strings. The
	833	function cgiStringArrayFree() does the job completely. */
	834	<A HREF="#cgiStringArrayFree">cgiStringArrayFree</a>(responses);
	835	}
	836	</PRE>
	837	This code excerpt demonstrates an alternate means of retrieving
	838	a list of choices. The function
	839	<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> is used
	840	to retrieve an array consisting of all the strings submitted
	841	for with a particular input field name. This works both for
	842	<SELECT> tags with the MULTIPLE attribute and for
	843	groups of checkboxes with the same name.
	844	<P>
	845	The first argument to <a href="#cgiFormStringMultiple">
	846	cgiFormStringMultiple()</a> is the name of the input field or
	847	group of input fields in question. The second argument should
	848	be the address of a pointer to a pointer to a string, which
	849	isn't as bad as it sounds. Consider the following simple call
	850	of the function:
	851	<PRE>
	852	/* An array of strings; each C string is an array of characters */
	853	char **responses;
	854
	855	<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &responses);
	856	</PRE>
	857	<em>"How do I know how many responses there are?"</em>
	858	<p>
	859	After the call, the last entry in the string array will be
	860	a null pointer. Thus the simple loop:
	861	<PRE>
	862	int i = 0;
	863	while (responses[i]) {
	864	/* Do something with the string responses[i] */
	865	i++;
	866	}
	867	</PRE>
	868	can be used to walk through the array until the last
	869	entry is encountered.
	870	<p>
	871	<strong>Important:</strong> the
	872	<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a> function
	873	returns a pointer to <strong>allocated memory</strong>. Your code
	874	should not modify the strings in the responses array or the responses
	875	array itself; if modification is needed, the strings should be
	876	copied. When your code is done examining the responses array,
	877	you <strong>MUST</strong> call <a href="#cgiStringArrayFree">
	878	cgiStringArrayFree()</a> with the array as an argument to free the memory
	879	associated with the array. Otherwise, the memory will not be available
	880	again until the program exists. <strong>Don't</strong> just call the
	881	free() function; if you do, the individual strings will not be freed.
	882	<h4>Accessing Uploaded Files</h4>
	883	CGIC provides functions to access files that have been uploaded
	884	as part of a form submission. <strong>IMPORTANT: you MUST</strong> set
	885	the <code>enctype</code> attribute of your <code>form</code> tag
	886	to <code>multipart/form-data</code> for this feature to work! For an
	887	example, see the <a href="#ShowForm">ShowForm</a> function of
	888	cgictest.c, examined below.
	889	<p>
	890	The <code>File</code> function of cgictest.c takes care of
	891	receiving uploaded files:
	892	<pre>
	893	void File()
	894	{
	895	cgiFilePtr file;
	896	char name[1024];
	897	char contentType[1024];
	898	char buffer[1024];
	899	int size;
	900	int got;
	901	if (cgiFormFileName("file", name, sizeof(name)) !=
	902	cgiFormSuccess)
	903	{
	904	printf("<p>No file was uploaded.<p>\n");
	905	return;
	906	}
	907	fprintf(cgiOut, "The filename submitted was: ");
	908	cgiHtmlEscape(name);
	909	fprintf(cgiOut, "<p>\n");
	910	cgiFormFileSize("file", &size);
	911	fprintf(cgiOut, "The file size was: %d bytes<p>\n", size);
	912	cgiFormFileContentType("file", contentType, sizeof(contentType));
	913	fprintf(cgiOut, "The alleged content type of the file was: ");
	914	cgiHtmlEscape(contentType);
	915	fprintf(cgiOut, "<p>\n");
	916	fprintf(cgiOut, "Of course, this is only the claim the browser "
	917	"made when uploading the file. Much like the filename, "
	918	"it cannot be trusted.<p>\n");
	919	fprintf(cgiOut, "The file's contents are shown here:<p>\n");
	920	if (cgiFormFileOpen("file", &file) != cgiFormSuccess) {
	921	fprintf(cgiOut, "Could not open the file.<p>\n");
	922	return;
	923	}
	924	fprintf(cgiOut, "<pre>\n");
	925	while (cgiFormFileRead(file, buffer, sizeof(buffer), &got) ==
	926	cgiFormSuccess)
	927	{
	928	cgiHtmlEscapeData(buffer, got);
	929	}
	930	fprintf(cgiOut, "</pre>\n");
	931	cgiFormFileClose(file);
	932	}
	933	</pre>
	934	First, the File function checks to determine the filename that was
	935	submitted by the user. <strong>VERY IMPORTANT: this filename may or
	936	may not bear any relation to the real name of the file on the user's
	937	computer, may be deliberately manipulated with malicious intent,</strong>
	938	and should not be used for <strong>any</strong> purpose unless you have
	939	determined that its content is safe for your intended use and will not,
	940	at the very least, overwrite another file of importance to you, especially if
	941	you intend to use it as a file name on the server side. The cgic library
	942	itself does not use this file name for temporary storage.
	943	<p>
	944	If the <a href="#cgiFormFileName">cgiFormFileName</a> function does
	945	not succeed, no file was uploaded.
	946	<p>
	947	Next, the <a href="#cgiFormFileSize">cgiFormFileSize</a> function is called
	948	to determine the size of the uploaded file, in bytes.
	949	<p>
	950	The File function then proceeds to query the content type of the uploaded
	951	file. Files uploaded by the user have their own content type information,
	952	which may be useful in determining whether the file is an image, HTML document,
	953	word processing document, or other type of file. However,
	954	<strong>as with the filename and any other claim made by the browser,
	955	this information should not be blindly trusted.</strong> The browser
	956	may upload a file with the name <code>picture.jpg</code> and the
	957	content type <code>image/jpeg</code>, but this does not guarantee that the
	958	actual file will contain a valid JPEG image suitable for display.
	959	<p>
	960	The content type submitted by the browser can be queried using the
	961	<a href="#cgiFormFileContentType">cgiFormFileContentType</a> function.
	962	<p>
	963	Of course, CGIC also provides access to the actual uploded file.
	964	First, the programmer calls <a href="#cgiFormFileOpen">cgiFormFileOpen</a>,
	965	passing the address of a <code>cgiFilePtr</code> object. If this function
	966	succeeds, the <code>cgiFilePtr</code> object becomes valid, and can be
	967	used in subsequent calls to <a href="#cgiFormFileRead">cgiFormFileRead</a>.
	968	Notice that the number of bytes read may be less than the number requested,
	969	in particular on the last successful call before cgiFormFileRead begins
	970	to return <code>cgiFormEOF</code>. When cgiFormFileRead no longer returns
	971	cgiFormSuccess,
	972	the programmer calls <a href="#cgiFormClose">cgiFormFileClose</a> to
	973	release the <code>cgiFilePtr</code> object.
	974	<p>
	975	The uploaded file data may contain anything, including binary data,
	976	null characters, and so on. The example program uses the
	977	<a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a> function to output the
	978	data with any special characters that have meaning in HTML escaped.
	979	Most programs will save the uploaded information to a server-side file or
	980	database.
	981	<h4>Fetching All Form Entries</h4>
	982	From time to time, the programmer may not know the names of all
	983	form fields in advance. In such situations it is convenient to
	984	use the <a href="#cgiFormEntries">cgiFormEntries</a> function.
	985	The Entries function of cgictest.c demonstrates the use of
	986	cgiFormEntries:
	987	<pre>
	988	void Entries()
	989	{
	990	char array, arrayStep;
	991	fprintf(cgiOut, "List of All Submitted Form Field Names:<p>\n");
	992	if (cgiFormEntries(&array) != cgiFormSuccess) {
	993	return;
	994	}
	995	arrayStep = array;
	996	fprintf(cgiOut, "<ul>\n");
	997	while (*arrayStep) {
	998	fprintf(cgiOut, "<li>");
	999	cgiHtmlEscape(*arrayStep);
	1000	fprintf(cgiOut, "\n");
	1001	arrayStep++;
	1002	}
	1003	fprintf(cgiOut, "</ul>\n");
	1004	cgiStringArrayFree(array);
	1005	}
	1006	</pre>
	1007	The cgiFormEntries function retrieves an array of form field names.
	1008	This array consists of pointers to strings, with a final null pointer
	1009	to mark the end of the list. The above code illustrates one way of
	1010	looping through the returned strings. Note the final call to
	1011	<a href="#cgiStringArrayFree">cgiStringArrayFree</a>, which is
	1012	essential in order to return the memory used to store the strings
	1013	and the string array.
	1014	<h4>Retrieving Cookies</h4>
	1015	The Cookies function of cgictest.c displays a list of all cookies
	1016	submitted by the browser with the current form submission, along
	1017	with their values:
	1018	<pre>
	1019	void Cookies()
	1020	{
	1021	char array, arrayStep;
	1022	char cname[1024], cvalue[1024];
	1023	fprintf(cgiOut, "Cookies Submitted On This Call, With Values "
	1024	"(Many Browsers NEVER Submit Cookies):<p>\n");
	1025	if (cgiCookies(&array) != cgiFormSuccess) {
	1026	return;
	1027	}
	1028	arrayStep = array;
	1029	fprintf(cgiOut, "<table border=1>\n");
	1030	fprintf(cgiOut, "<tr><th>Cookie<th>Value</tr>\n");
	1031	while (*arrayStep) {
	1032	char value[1024];
	1033	fprintf(cgiOut, "<tr>");
	1034	fprintf(cgiOut, "<td>");
	1035	cgiHtmlEscape(*arrayStep);
	1036	fprintf(cgiOut, "<td>");
	1037	cgiCookieString(*arrayStep, value, sizeof(value));
	1038	cgiHtmlEscape(value);
	1039	fprintf(cgiOut, "\n");
	1040	arrayStep++;
	1041	}
	1042	fprintf(cgiOut, "</table>\n");
	1043	cgiFormString("cname", cname, sizeof(cname));
	1044	cgiFormString("cvalue", cvalue, sizeof(cvalue));
	1045	if (strlen(cname)) {
	1046	fprintf(cgiOut, "New Cookie Set On This Call:<p>\n");
	1047	fprintf(cgiOut, "Name: ");
	1048	cgiHtmlEscape(cname);
	1049	fprintf(cgiOut, "Value: ");
	1050	cgiHtmlEscape(cvalue);
	1051	fprintf(cgiOut, "<p>\n");
	1052	fprintf(cgiOut, "If your browser accepts cookies "
	1053	"(many do not), this new cookie should appear "
	1054	"in the above list the next time the form is "
	1055	"submitted.<p>\n");
	1056	}
	1057	cgiStringArrayFree(array);
	1058	}
	1059	</pre>
	1060	<strong>VERY IMPORTANT: YOUR BROWSER MIGHT NOT SUBMIT COOKIES,
	1061	EVER, REGARDLESS OF WHAT VALUES YOU ENTER INTO THE TEST FORM.</strong>
	1062	Many, many browsers are configured not to accept or send cookies;
	1063	others are configured to send them as little as possible to meet the
	1064	bare minimum requirements for entry into popular sites. Users will often
	1065	refuse your cookies; make sure your code still works in that situation!
	1066	<p>
	1067	The above code uses the <a href="#cgiCookies">cgiCookies</a> function
	1068	to retrieve a list of all currently set cookies as a null-terminated
	1069	array of strings. The <a href="#cgiCookieString">cgiCookieString</a>
	1070	function is then used to fetch the value associated with each cookie;
	1071	this function works much like <a href="#cgiFormString">cgiFormString</a>,
	1072	discussed earlier. Note that a cookie set as a part of the current
	1073	form submission process does not appear on this list immediately, as
	1074	it has not yet been sent back by the browser. It should appear on
	1075	future submissions, provided that the browser chooses to accept
	1076	and resend the cookie at all.
	1077	<h4>Displaying a Form That Submits to the Current Program</h4>
	1078	CGI programmers often need to display HTML pages as part of the output
	1079	of CGI programs; these HTML pages often contain forms which should submit
	1080	fields back to the same program they came from. Provided that your
	1081	web server is well-configured, this can be done conveniently using
	1082	the cgiScriptName environment variable, as shown below. Here is the
	1083	source code of the ShowForm function of cgictest.c:
	1084	<pre>
	1085	void ShowForm()
	1086	{
	1087	fprintf(cgiOut, "<!-- 2.0: multipart/form-data is required
	1088	"for file uploads. -->");
	1089	fprintf(cgiOut, "<form method=\"POST\" "
	1090	"enctype=\"multipart/form-data\" ");
	1091	fprintf(cgiOut, " action=\"");
	1092	cgiValueEscape(cgiScriptName);
	1093	fprintf(cgiOut, "\">\n");
	1094	fprintf(cgiOut, "<p>\n");
	1095	fprintf(cgiOut, "Text Field containing Plaintext\n");
	1096	fprintf(cgiOut, "<p>\n");
	1097	fprintf(cgiOut, "<input type=\"text\" name=\"name\">Your Name\n");
	1098	fprintf(cgiOut, "<p>\n");
	1099	fprintf(cgiOut, "Multiple-Line Text Field\n");
	1100	fprintf(cgiOut, "<p>\n");
	1101	fprintf(cgiOut, "<textarea NAME=\"address\" ROWS=4 COLS=40>\n");
	1102	fprintf(cgiOut, "Default contents go here. \n");
	1103	fprintf(cgiOut, "</textarea>\n");
	1104	fprintf(cgiOut, "<p>\n");
	1105	fprintf(cgiOut, "Checkbox\n");
	1106	fprintf(cgiOut, "<p>\n");
	1107	fprintf(cgiOut, "<input type=\"checkbox\" name=\"hungry\" checked>Hungry\n");
	1108	fprintf(cgiOut, "<p>\n");
	1109	fprintf(cgiOut, "Text Field containing a Numeric Value\n");
	1110	fprintf(cgiOut, "<p>\n");
	1111	fprintf(cgiOut, "<input type=\"text\" name=\"temperature\" value=\"98.6\">\n");
	1112	fprintf(cgiOut, "Blood Temperature (80.0-120.0)\n");
	1113	fprintf(cgiOut, "<p>\n");
	1114	fprintf(cgiOut, "Text Field containing an Integer Value\n");
	1115	fprintf(cgiOut, "<p>\n");
	1116	fprintf(cgiOut, "<input type=\"text\" name=\"frogs\" value=\"1\">\n");
	1117	fprintf(cgiOut, "Frogs Eaten\n");
	1118	fprintf(cgiOut, "<p>\n");
	1119	fprintf(cgiOut, "Single-SELECT\n");
	1120	fprintf(cgiOut, "<br>\n");
	1121	fprintf(cgiOut, "<select name=\"colors\">\n");
	1122	fprintf(cgiOut, "<option value=\"Red\">Red\n");
	1123	fprintf(cgiOut, "<option value=\"Green\">Green\n");
	1124	fprintf(cgiOut, "<option value=\"Blue\">Blue\n");
	1125	fprintf(cgiOut, "</select>\n");
	1126	fprintf(cgiOut, "<br>\n");
	1127	fprintf(cgiOut, "Multiple-SELECT\n");
	1128	fprintf(cgiOut, "<br>\n");
	1129	fprintf(cgiOut, "<select name=\"flavors\" multiple>\n");
	1130	fprintf(cgiOut, "<option value=\"pistachio\">Pistachio\n");
	1131	fprintf(cgiOut, "<option value=\"walnut\">Walnut\n");
	1132	fprintf(cgiOut, "<option value=\"creme\">Creme\n");
	1133	fprintf(cgiOut, "</select>\n");
	1134	fprintf(cgiOut, "<p>Exclusive Radio Button Group: Age of "
	1135	"Truck in Years\n");
	1136	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
	1137	"value=\"1\">1\n");
	1138	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
	1139	"value=\"2\">2\n");
	1140	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
	1141	"value=\"3\" checked>3\n");
	1142	fprintf(cgiOut, "<input type=\"radio\" name=\"age\" "
	1143	"value=\"4\">4\n");
	1144	fprintf(cgiOut, "<p>Nonexclusive Checkbox Group: "
	1145	"Voting for Zero through Four Candidates\n");
	1146	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
	1147	"value=\"A\">A\n");
	1148	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
	1149	"value=\"B\">B\n");
	1150	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
	1151	"value=\"C\">C\n");
	1152	fprintf(cgiOut, "<input type=\"checkbox\" name=\"vote\" "
	1153	"value=\"D\">D\n");
	1154	fprintf(cgiOut, "<p>File Upload:\n");
	1155	fprintf(cgiOut, "<input type=\"file\" name=\"file\" "
	1156	"value=\"\"> (Select A Local File)\n");
	1157	fprintf(cgiOut, "<p>\n");
	1158	fprintf(cgiOut, "<p>Set a Cookie<p>\n");
	1159	fprintf(cgiOut, "<input name=\"cname\" "
	1160	"value=\"\"> Cookie Name\n");
	1161	fprintf(cgiOut, "<input name=\"cvalue\" "
	1162	"value=\"\"> Cookie Value<p>\n");
	1163	fprintf(cgiOut, "<input type=\"submit\" "
	1164	"name=\"testcgic\" value=\"Submit Request\">\n");
	1165	fprintf(cgiOut, "<input type=\"reset\" "
	1166	"value=\"Reset Request\">\n");
	1167	fprintf(cgiOut, "<p>Save the CGI Environment<p>\n");
	1168	fprintf(cgiOut, "Pressing this button will submit the form, then "
	1169	"save the CGI environment so that it can be replayed later "
	1170	"by calling cgiReadEnvironment (in a debugger, for "
	1171	"instance).<p>\n");
	1172	fprintf(cgiOut, "<input type=\"submit\" name=\"saveenvironment\" "
	1173	"value=\"Save Environment\">\n");
	1174	fprintf(cgiOut, "</form>\n");
	1175	}
	1176	</pre>
	1177	Note the use of <code>enctype="multipart/form-data"</code> in the
	1178	<code>FORM</code> tag. This is absolutely required if the form
	1179	will contain file upload fields, as in the above example. Most
	1180	browsers will not even attempt file uploads without the
	1181	presence of this attribute.
	1182	<h4>Examining CGI environment variables</h4>
	1183	The CGI standard specifies a number of environment variables
	1184	which are set by the server. However, servers are somewhat
	1185	unpredictable as to whether these variables will be null or
	1186	point to empty strings when an environment variable is not set.
	1187	Also, in order to allow the programmer to restore saved
	1188	CGI environments, the cgic library needs have a way of insulating
	1189	the programmer from the actual environment variables.
	1190	<p>
	1191	Instead of calling getenv() to determine the value of a
	1192	variable such as HTTP_USER_AGENT (the browser software being used),
	1193	always use the
	1194	<a href="#variables">cgic copies of the environment variables</a>,
	1195	which are always valid C strings (they are never null, although
	1196	they may point to an empty string). For instance, the cgic
	1197	variable containing the name of the browser software is
	1198	<a href="#cgiUserAgent">cgiUserAgent</a>. The referring URL appears
	1199	in the variable <a href="#cgiReferrer">cgiReferrer</a>.
	1200	<h3><a name="images">How can I generate images from my cgic application?</a></h3>
	1201	cgic can be used in conjunction with the
	1202	<a href="http://www.boutell.com/gd/">gd graphics library</a>, which
	1203	can produce GIF images on the fly.
	1204	<p>
	1205	The following short sample program hints at the possibilities:
	1206	<pre>
	1207	#include "cgic.h"
	1208	#include "gd.h"
	1209
	1210	char *colors[] = {
	1211	"red", "green", "blue"
	1212	};
	1213
	1214	#define colorsTotal 3
	1215
	1216	int cgiMain() {
	1217	int colorChosen;
	1218	gdImagePtr im;
	1219	int r, g, b;
	1220	/* Use gd to create an image */
	1221	im = gdImageCreate(64, 64);
	1222	r = gdImageColorAllocate(im, 255, 0, 0);
	1223	g = gdImageColorAllocate(im, 0, 255, 0);
	1224	b = gdImageColorAllocate(im, 0, 0, 255);
	1225	/* Now use cgic to find out what color the user requested */
	1226	<a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("color", 3, &colorChosen, 0);
	1227	/* Now fill with the desired color */
	1228	switch(colorChosen) {
	1229	case 0:
	1230	gdImageFill(im, 32, 32, r);
	1231	break;
	1232	case 1:
	1233	gdImageFill(im, 32, 32, g);
	1234	break;
	1235	case 2:
	1236	gdImageFill(im, 32, 32, b);
	1237	break;
	1238	}
	1239	/* Now output the image. Note the content type! */
	1240	cgiHeaderContentType("image/gif");
	1241	/* Send the image to cgiOut */
	1242	gdImageGif(im, cgiOut);
	1243	/* Free the gd image */
	1244	gdImageDestroy(im);
	1245	return 0;
	1246	}
	1247	</pre>
	1248	Note that this program would need to be linked with both cgic.o
	1249	and libgd.a. Often programs of this type respond to one
	1250	cgiPathInfo value or set of form fields by returning an HTML page
	1251	with an inline image reference that, in turn, generates a GIF image.
	1252	<h3><a name="debug">Debugging CGI applications: using capture</a></h3>
	1253	Debugging CGI applications can be a painful task. Since CGI applications
	1254	run in a special environment created by the web server, it is difficult
	1255	to execute them in a debugger. However, the cgic library provides a way
	1256	of capturing "live" CGI environments to a file, and also provides a way
	1257	to reload saved environments.
	1258	<p>
	1259	The provided program 'capture.c' can be used to capture CGI
	1260	environments. Just change the first line of the cgiMain() function
	1261	of capture.c to save the CGI environment to a filename appropriate
	1262	on your system and type 'make capture'. Then place capture in your
	1263	cgi directory and set the form action or other link you want to test
	1264	to point to it. When the form submission or other link takes place,
	1265	capture will write the CGI environment active at that time to
	1266	the filename you specified in the source. The
	1267	<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> function can then
	1268	be invoked on the same filename at the beginning of the cgiMain() function
	1269	of the application you want to test in order to restore the captured
	1270	environment. You can then execute your program in the debugger of your choice,
	1271	and it should perform exactly as it would have performed had
	1272	it been launched by the actual web server, including file uploads,
	1273	cookies and all other phenomena within the purview of cgic.
	1274	<p>
	1275	<strong>Important:</strong> Make sure you specify the full path, as the
	1276	current working directory of a CGI script may not be what you
	1277	think it is!
	1278	<p>
	1279	<strong>Even More Important:</strong> If you call getenv() yourself
	1280	in your code, instead of using the provided <a href="#variables">
	1281	cgic copies of the CGI environment variables</a>, you will
	1282	<em>not</em> get the values you expect when running with
	1283	a saved CGI environment. Always use the cgic variables instead
	1284	of calling getenv().
	1285	<h3><a name="functions">cgic function reference</a></h3>
	1286	<dl>
	1287	<br><dt><strong><a name="cgiFormString">cgiFormResultType cgiFormString(
	1288	char name, char result, int max)</a>
	1289	</strong><br><dd>cgiFormString attempts to retrieve the string sent for the
	1290	specified input field. The text will be copied into
	1291	the buffer specified by result, up to but not
	1292	exceeding max-1 bytes; a terminating null is then
	1293	added to complete the string. Regardless of the newline
	1294	format submitted by the browser, cgiFormString always
	1295	encodes each newline as a single line feed (ascii decimal 10); as
	1296	a result the final string may be slightly shorter than indicated
	1297	by a call to <a href="#cgiFormStringSpaceNeeded">
	1298	cgiFormStringSpaceNeeded</a> but will never be longer.
	1299	cgiFormString returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the string was
	1300	successfully retrieved,
	1301	<a href="#cgiFormTruncated">cgiFormTruncated</a> if the string was
	1302	retrieved but was truncated to fit the buffer,
	1303	cgiFormEmpty if the string was
	1304	retrieved but was empty, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no
	1305	such input field was submitted. In the last case,
	1306	an empty string is copied to result.
	1307	<br><br><dt><strong><a name="cgiFormStringNoNewlines">
	1308	cgiFormResultType cgiFormStringNoNewlines(
	1309	char name, char result, int max)</a>
	1310	</strong><br><dd>
	1311	cgiFormStringNoNewlines() is exactly equivalent to <a href="#cgiFormString">
	1312	cgiFormString()</a>, except
	1313	that any carriage returns or line feeds that occur in the input
	1314	will be stripped out. The use of this function is recommended
	1315	for single-line text input fields, as some browsers will submit
	1316	carriage returns and line feeds when they should not.
	1317	<br><br><dt><strong><a name="cgiFormStringSpaceNeeded">
	1318	cgiFormResultType cgiFormStringSpaceNeeded(
	1319	char name, int length)</a>
	1320	</strong><br><dd>
	1321	cgiFormStringSpaceNeeded() is used to determine the length of the input text
	1322	buffer needed to receive the contents of the specified input field.
	1323	This is useful if the programmer wishes to allocate sufficient memory
	1324	for input of arbitrary length. The actual length of the string
	1325	retrieved by a subsequent call to cgiFormString() may be slightly shorter
	1326	but will never be longer than *result. On success, cgiFormStringSpaceNeeded()
	1327	sets the value pointed to by length to the number of bytes of data,
	1328	including the terminating null, and returns <a href="#cgiFormSuccess">cgiFormSuccess</a>. If no
	1329	value was submitted for the specified field, cgiFormStringSpaceNeeded sets
	1330	the value pointed to by length to 1 and returns <a href="#cgiFormNotFound">cgiFormNotFound</a>. 1 is
	1331	set to ensure space for an empty string (a single null
	1332	character) if cgiFormString is called despite the return value.
	1333
	1334	<br><br><dt><strong><a name="cgiFormStringMultiple">cgiFormResultType cgiFormStringMultiple(
	1335	char name, char **ptrToStringArray)</a>
	1336	</strong><br><dd>cgiFormStringMultiple is useful in the unusual case in which several
	1337	input elements in the form have the same name and, for whatever
	1338	reason, the programmer does not wish to use the checkbox, radio
	1339	button and selection menu functions provided below. This is
	1340	occasionally needed if the programmer cannot know
	1341	in advance what values might appear in a multiple-selection list
	1342	or group of checkboxes on a form. The value pointed to
	1343	by result will be set to a pointer to an array of strings; the last
	1344	entry in the array will be a null pointer. This array is allocated
	1345	by the CGI library. Important: when done working with the array,
	1346	you must call cgiStringArrayFree() with the array pointer as the
	1347	argument. cgiFormStringMultiple() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if at least
	1348	one occurrence of the name is found, <a href="#cgiFormNotFound">cgiFormNotFound</a>
	1349	if no occurrences are found, or cgiFormMemory if not enough
	1350	memory is available to allocate the array to be returned.
	1351	In all cases except the last, ptrToStringArray is set to point to a
	1352	valid array of strings, with the last element in the array being a
	1353	null pointer; in the out-of-memory case ptrToStringArray is set to
	1354	a null pointer.
	1355
	1356	<br><br><dt><strong><a name="cgiFormEntries">cgiFormResultType cgiFormEntries(
	1357	char ***ptrToStringArray)</a>
	1358	</strong><br><dd>cgiFormEntries is useful when the programmer cannot know the names
	1359	of all relevant form fields in advance. The value pointed to
	1360	by result will be set to a pointer to an array of strings; the last
	1361	entry in the array will be a null pointer. This array is allocated
	1362	by the CGI library. Important: when done working with the array,
	1363	you must call cgiStringArrayFree() with the array pointer as the
	1364	argument. cgiFormEntries() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> except in the event of an out of memory error.
	1365	On success, ptrToStringArray is set to point to a
	1366	valid array of strings, with the last element in the array being a
	1367	null pointer; in the out-of-memory case ptrToStringArray is set to
	1368	a null pointer, and
	1369	<a href="#cgiFormOutOfMemory">cgiFormOutOfMemory</a> is returned.
	1370
	1371	<br><br><dt><strong><a name="cgiStringArrayFree">void cgiStringArrayFree(char **stringArray)
	1372	</a>
	1373	</strong><br><dd>
	1374	cgiStringArrayFree() is used to free the memory associated with
	1375	a string array created by
	1376	<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>,
	1377	<a href="#cgiFormEntries">cgiFormEntries()</a>, or
	1378	<a href="#cgiFormCookies">cgiFormCookies()</a>.
	1379	<br><br><dt><strong><a name="cgiFormInteger">cgiFormResultType cgiFormInteger(
	1380	char name, int result, int defaultV)</a>
	1381	</strong><br><dd>cgiFormInteger() attempts to retrieve the integer sent for the
	1382	specified input field. The value pointed to by result
	1383	will be set to the value submitted. cgiFormInteger() returns
	1384	cgiFormSuccess if the value was successfully retrieved,
	1385	cgiFormEmpty if the value submitted is an empty string,
	1386	cgiFormBadType if the value submitted is not an integer,
	1387	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted.
	1388	In the last three cases, the value pointed to by result
	1389	is set to the specified default.
	1390	<br><br><dt><strong><a name="cgiFormIntegerBounded">
	1391	cgiFormResultType cgiFormIntegerBounded(
	1392	char name, int result, int min, int max, int defaultV)</a>
	1393	</strong><br><dd>cgiFormIntegerBounded() attempts to retrieve the integer sent for the
	1394	specified input field, and constrains the result to be within
	1395	the specified bounds. The value pointed to by result
	1396	will be set to the value submitted. cgiFormIntegerBounded() returns
	1397	cgiFormSuccess if the value was successfully retrieved,
	1398	<a href="#cgiFormConstrained">cgiFormConstrained</a> if the value was out of bounds and result
	1399	was adjusted accordingly, <a href="#cgiFormEmpty">cgiFormEmpty</a> if the value submitted is
	1400	an empty string, <a href="#cgiFormBadType">cgiFormBadType</a> if the value submitted is not an
	1401	integer, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted.
	1402	In the last three cases, the value pointed to by result
	1403	is set to the specified default.
	1404
	1405	<br><br><dt><strong><a name="cgiFormDouble">cgiFormResultType cgiFormDouble(
	1406	char name, double result, double defaultV)</a>
	1407	</strong><br><dd>cgiFormDouble attempts to retrieve the floating-point value sent for
	1408	the specified input field. The value pointed to by result
	1409	will be set to the value submitted. cgiFormDouble returns
	1410	cgiFormSuccess if the value was successfully retrieved,
	1411	cgiFormEmpty if the value submitted is an empty string,
	1412	cgiFormBadType if the value submitted is not a number,
	1413	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted.
	1414	In the last three cases, the value pointed to by result
	1415	is set to the specified default.
	1416	<br><br><dt><strong><a name="cgiFormDoubleBounded">
	1417	cgiFormResultType cgiFormDoubleBounded(
	1418	char name, double result, double min, double max,
	1419	double defaultV)</a>
	1420	</strong><br><dd>
	1421	cgiFormDoubleBounded() attempts to retrieve the floating-point
	1422	value sent for the specified input field, and constrains the
	1423	result to be within the specified bounds. The value pointed to by
	1424	result will be set to the value submitted. cgiFormDoubleBounded() returns
	1425	cgiFormSuccess if the value was successfully retrieved,
	1426	<a href="#cgiFormConstrained">cgiFormConstrained</a> if the value was out of bounds and result
	1427	was adjusted accordingly, <a href="#cgiFormEmpty">cgiFormEmpty</a> if the value submitted is
	1428	an empty string, <a href="#cgiFormBadType">cgiFormBadType</a> if the value submitted is not a
	1429	number, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such input field was submitted.
	1430	In the last three cases, the value pointed to by result
	1431	is set to the specified default.
	1432
	1433	<br><br><dt><strong><a name="cgiFormSelectSingle">
	1434	cgiFormResultType cgiFormSelectSingle(
	1435	char name, char *choicesText, int choicesTotal,
	1436	int *result, int defaultV)</a>
	1437	</strong><br><dd>
	1438	cgiFormSelectSingle() retrieves the selection number associated with a
	1439	<SELECT> element that does not allow multiple selections. name
	1440	should identify the NAME attribute of the <SELECT> element. choicesText
	1441	should point to an array of strings identifying each choice;
	1442	choicesTotal should indicate the total number of choices. The value
	1443	pointed to by result will be set to the position of the actual choice
	1444	selected within the choicesText array, if any, or to the value of
	1445	default, if no selection was submitted or an invalid selection was
	1446	made. cgiFormSelectSingle() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the value was
	1447	successfully retrieved, <a href="#cgiFormNotFound">cgiFormNotFound</a> if no selection
	1448	was submitted, and <a href="#cgiFormNoSuchChoice">cgiFormNoSuchChoice</a> if the selection
	1449	does not match any of the possibilities in the choicesText array.
	1450	<br><dt><strong>
	1451	<a name="cgiFormSelectMultiple">
	1452	cgiFormResultType cgiFormSelectMultiple(
	1453	char name, char *choicesText, int choicesTotal,
	1454	int result, int invalid)</a>
	1455	</strong><br><dd>cgiFormSelectMultiple() retrieves the selection numbers associated with a
	1456	<SELECT> element that does allow multiple selections. name should
	1457	identify the NAME attribute of the <SELECT> element. choicesText
	1458	should point to an array of strings identifying each choice;
	1459	choicesTotal should indicate the total number of choices. result
	1460	should point to an array of integers with as many elements as there
	1461	are strings in the choicesText array. For each choice in the
	1462	choicesText array that is selected, the corresponding integer in
	1463	the result array will be set to one; other entries in the result
	1464	array will be set to zero. cgiFormSelectMultiple() returns <a href="#cgiFormSuccess">cgiFormSuccess</a>
	1465	if at least one valid selection was successfully retrieved or
	1466	cgiFormNotFound if no valid selections were submitted.
	1467	The integer pointed to by invalid is set to the number of
	1468	invalid selections that were submitted, which should be zero
	1469	unless the form and the choicesText array do not agree.
	1470
	1471	<br><br><dt><strong>
	1472	<a name="cgiFormSubmitClicked">
	1473	cgiFormResultType cgiFormSubmitClicked(
	1474	char *name)</a>
	1475	</strong><br><dd>
	1476	It is often desirable to know whether a particular submit button was clicked,
	1477	when multiple submit buttons with different name attributes exist.
	1478	cgiFormSubmitClicked is an alternative name for the
	1479	<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a> function,
	1480	which is suitable for testing whether a particular submit button
	1481	was used.
	1482	<br><br><dt><strong>
	1483	<a name="cgiFormCheckboxSingle">
	1484	cgiFormResultType cgiFormCheckboxSingle(
	1485	char *name)</a>
	1486	</strong><br><dd>
	1487	cgiFormCheckboxSingle determines whether the checkbox with the specified name
	1488	is checked. cgiFormCheckboxSingle returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the
	1489	button is checked, <a href="#cgiFormNotFound">cgiFormNotFound</a> if the checkbox is
	1490	not checked. cgiFormCheckboxSingle is intended for single
	1491	checkboxes with a unique name; see below for functions to
	1492	deal with multiple checkboxes with the same name, and
	1493	with radio buttons.
	1494
	1495	<br><br><dt><strong><a name="cgiFormCheckboxMultiple">
	1496	cgiFormResultType cgiFormCheckboxMultiple(
	1497	char name, char *valuesText, int valuesTotal,
	1498	int result, int invalid)</a>
	1499	</strong><br><dd>cgiFormCheckboxMultiple() determines which checkboxes among a group
	1500	of checkboxes with the same name are checked. This is distinct
	1501	from radio buttons (see <a href="#cgiFormRadio">cgiFormRadio</a>).
	1502	valuesText
	1503	should point to an array of strings identifying the VALUE
	1504	attribute of each checkbox; valuesTotal should indicate the total
	1505	number of checkboxes. result should point to an array of integers with
	1506	as many elements as there are strings in the valuesText array. For
	1507	each choice in the valuesText array that is selected, the corresponding
	1508	integer in the result array will be set to one; other entries in the
	1509	result array will be set to zero. cgiFormCheckboxMultiple returns
	1510	cgiFormSuccess if at least one valid checkbox was checked or
	1511	cgiFormNotFound if no valid checkboxes were checked.
	1512	The integer pointed to by invalid is set to the number of
	1513	invalid selections that were submitted, which should be zero
	1514	unless the form and the valuesText array do not agree.
	1515	<br><br><dt><strong><a name="cgiFormRadio">
	1516	cgiFormResultType cgiFormRadio(
	1517	char name, char *valuesText, int valuesTotal,
	1518	int *result, int defaultV)</a>
	1519	</strong><br><dd>cgiFormRadio() determines which, if any, of a group of radio boxes with
	1520	the same name was selected. valuesText should point to an array of
	1521	strings identifying the VALUE attribute of each radio box;
	1522	valuesTotal should indicate the total number of radio boxes. The value
	1523	pointed to by result will be set to the position of the actual choice
	1524	selected within the valuesText array, if any, or to the value of
	1525	default, if no radio box was checked or an invalid selection was
	1526	made. cgiFormRadio() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if a checked radio box was
	1527	found in the group, <a href="#cgiFormNotFound">cgiFormNotFound</a> if no box was checked, and
	1528	<a href="#cgiFormNoSuchChoice">cgiFormNoSuchChoice</a> if the radio box submitted does not match any of
	1529	the possibilities in the valuesText array.
	1530
	1531	<br><dt><strong><a name="cgiFormFileName">cgiFormResultType cgiFormFileName(
	1532	char name, char fileName, int max)</a>
	1533	</strong><br><dd>cgiFormFileName attempts to retrieve the file name uploaded by the
	1534	user for the specified form input field of type <code>file</code>.
	1535	<strong>NEVER, EVER TRUST THIS FILENAME TO BE REASONABLE AND
	1536	SAFE FOR DIRECT USE ON THE SERVER SIDE.</strong>
	1537	The text will be copied into
	1538	the buffer specified by fileName, up to but not
	1539	exceeding max-1 bytes; a terminating null is then
	1540	added to complete the string. cgiFormFileName returns
	1541	<a href="#cgiFormSuccess">cgiFormSuccess</a> if the string was
	1542	successfully retrieved and was not empty,
	1543	<a href="#cgiFormNoFileName">cgiFormNoFileName</a> if the string was
	1544	successfully retrieved but empty indicating that no file was uploaded,
	1545	<a href="#cgiFormTruncated">cgiFormTruncated</a> if the string was
	1546	retrieved but was truncated to fit the buffer,
	1547	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no
	1548	such input field was submitted. In the last case,
	1549	an empty string is copied to result.
	1550	<br><dt><strong><a name="cgiFormFileSize">cgiFormResultType cgiFormFileSize(
	1551	char name, int sizeP)</a>
	1552	</strong><br><dd>cgiFormFileSize attempts to retrieve the size, in bytes, of a
	1553	file uploaded by the browser in response to the
	1554	input field of type <code>file</code> specified by the
	1555	<code>name</code> parameter. On success, the size is stored
	1556	to *sizeP, and this function returns
	1557	<a href="#cgiFormSuccess">cgiFormSuccess</a>. If the form
	1558	field does not exist, this function returns
	1559	<a href="#cgiFormNotFound">cgiFormNotFound</a>.
	1560	If the form field exists but no file was uploaded, this function
	1561	returns <a href="#cgiFormNotAFile">cgiFormNotAFile</a>.
	1562	<br><dt><strong><a name="cgiFormFileContentType">cgiFormResultType cgiFormFileContentType(
	1563	char name, char contentType, int max)</a>
	1564	</strong><br><dd>cgiFormString attempts to retrieve the content name claimed by the
	1565	user for the specified form input field of type <code>file</code>.
	1566	<strong>THERE IS NO GUARANTEE THAT THE CONTENT TYPE WILL BE
	1567	ACCURATE.</strong>
	1568	The content type string will be copied into
	1569	the buffer specified by contentType, up to but not
	1570	exceeding max-1 bytes; a terminating null is then
	1571	added to complete the string. cgiFormFileContentType returns
	1572	<a href="#cgiFormSuccess">cgiFormSuccess</a> if the string was
	1573	successfully retrieved and was not empty,
	1574	<a href="#cgiFormNoContentType">cgiFormNoContentType</a> if the string was
	1575	successfully retrieved but empty indicating that no file was uploaded
	1576	or the browser did not know the content type,
	1577	<a href="#cgiFormTruncated">cgiFormTruncated</a> if the string was
	1578	retrieved but was truncated to fit the buffer,
	1579	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no
	1580	such input field was submitted. In the last case,
	1581	an empty string is copied to result.
	1582
	1583	<br><dt><strong><a name="cgiFormFileOpen">cgiFormResultType cgiFormFileOpen(
	1584	char name, cgiFilePtr cfpp)</a>
	1585	</strong><br><dd>cgiFormFileOpen attempts to open the actual uploaded file data for
	1586	the specified form field of type <code>file</code>. Upon success,
	1587	this function returns retrieve the content name claimed by the
	1588	user for the specified form input field of type <code>file</code>.
	1589	On success, this function sets *cfpp to a valid cgiFilePtr
	1590	object for use with <a href="#cgiFormFileRead</a>cgiFormFileRead</a>
	1591	and returns <a href="#cgiFormSuccess">cgiFormSuccess</a>.
	1592	On failure, this function sets *cfpp to a null pointer, and
	1593	returns <a href="#cgiFormNotFound">cgiFormNotFound</a>,
	1594	<a href="#cgiFormNotAFile">cgiFormNotAFile</a>,
	1595	<a href="#cgiFormMemory">cgiFormMemory</a> or
	1596	<a href="#cgiFormIO">cgiFormIO</a> as appropriate.
	1597	<p>
	1598	See also <a href="#cgiFormFileRead">cgiFormFileRead</a>
	1599	and <a href="#cgiFormFileClose">cgiFormFileClose</a>.
	1600	<br><dt><strong><a name="cgiFormFileRead">cgiFormResultType cgiFormFileRead(
	1601	cgiFilePtr cfp, char buffer, int bufferSize, int gotP)</a>
	1602	</strong><br><dd>cgiFormFileRead attempts to read up to <code>bufferSize</code>
	1603	bytes from a cgiFilePtr object previously opened with
	1604	<a href="#cgiFormFileOpen">cgiFormFileOpen</a>. If any data
	1605	is successfully read, it is copied to <code>buffer</code>,
	1606	and the number of bytes successfully read is stored
	1607	to <code>*gotP</code>. This function returns
	1608	<a href="#cgiFormSuccess">cgiFormSuccess</a> if any data
	1609	is successfully read. At end of file, this function
	1610	returns <a href="#cgiFormEOF">cgiFormEOF</a>. In the event
	1611	of an I/O error, this function returns
	1612	<a href="#cgiFormIO">cgiFormIO</a>. If cfp is a null pointer,
	1613	this function returns <a href="#cgiFormOpenFailed">cgiFormOpenFailed</a>.
	1614	<p>
	1615	See also <a href="#cgiFormFileOpen">cgiFormFileOpen</a>
	1616	and <a href="#cgiFormFileClose">cgiFormFileClose</a>.
	1617	<br><dt><strong><a name="cgiFormFileClose">cgiFormResultType cgiFormFileClose(
	1618	cgiFilePtr cfp)</a>
	1619	</strong><br><dd>cgiFormFileClose closes a cgiFilePtr object previously opened
	1620	with <a href="#cgiFormFileOpen">cgiFormFileOpen</a>, freeing
	1621	memory and other system resources. This
	1622	function returns <a href="#cgiFormSuccess">cgiFormSuccess</a>
	1623	unless cfp is null, in which case
	1624	<a href="#cgiFormOpenFailed">cgiFormOpenFailed</a> is returned.
	1625	<p>
	1626	See also <a href="#cgiFormFileOpen">cgiFormFileOpen</a>
	1627	and <a href="#cgiFormFileRead">cgiFormFileRead</a>.
	1628	<br><br><dt><strong><a name="cgiHeaderLocation">
	1629	void cgiHeaderLocation(char *redirectUrl)</a>
	1630	</strong><br><dd>
	1631	cgiHeaderLocation() should be called if the programmer wishes to
	1632	redirect the user to a different URL. No futher output
	1633	is needed in this case.
	1634	<p>
	1635	If you wish to set cookies,
	1636	<strong>you must make your calls to
	1637	<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
	1638	and
	1639	<a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>
	1640	</strong> BEFORE invoking cgiHeaderLocation.
	1641	<br><br><dt><strong><a name="cgiHeaderStatus">
	1642	void cgiHeaderStatus(int status, char *statusMessage)</a>
	1643	</strong><br><dd>
	1644	cgiHeaderStatus() should be called if the programmer wishes to
	1645	output an HTTP error status code instead of a document. The status
	1646	code is the first argument; the second argument is the status
	1647	message to be displayed to the user.
	1648	<p>
	1649	If you wish to set cookies,
	1650	<strong>you must make your calls to
	1651	<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
	1652	and
	1653	<a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>
	1654	</strong> BEFORE invoking cgiHeaderStatus.
	1655	<br><br><dt><strong><a name="cgiHeaderContentType">
	1656	void cgiHeaderContentType(char *mimeType)</a>
	1657	</strong><br><dd>
	1658	cgiHeaderContentType() should be called if the programmer wishes to
	1659	output a new document in response to the user's request. This is
	1660	the normal case. The single argument is the MIME document type
	1661	of the response; typical values are "text/html" for HTML documents,
	1662	"text/plain" for plain ASCII without HTML tags, "image/gif" for
	1663	a GIF image and "audio/basic" for .au-format audio.
	1664	<p>
	1665	If you wish to set cookies,
	1666	<strong>you must make your calls to
	1667	<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
	1668	and
	1669	<a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>
	1670	</strong> BEFORE invoking cgiHeaderContentType.
	1671	<br><br><dt><strong><a name="cgiHeaderCookieSetString">
	1672	void cgiHeaderCookieSetString(char name, char value,
	1673	int secondsToLive, char path, char domain)</a>
	1674	</strong><br><dd>
	1675	cgiHeaderCookieSetString() should be called when the programmer wishes
	1676	to store a piece of information in the user's browser, so that the
	1677	stored information is again presented to the server on subsequent
	1678	accesses to the relevant site. The first argument is the name of the
	1679	cookie to be stored; for best results in all browsers, use a short
	1680	name without spaces or unusual punctuation. The second argument is
	1681	the value of the cookie to be stored. Again, for best results, use
	1682	a short string; it is recommended that cookies be used to store a
	1683	unique identifier which is then used to look up more detailed
	1684	information in a database on the server side. Attempts to store
	1685	elaborate information on the browser side are much more likely to fail.
	1686	The third argument is the number of seconds that the cookie should
	1687	be kept by the browser; 86400 is a single full day, 365*86400 is
	1688	roughly one year. The fourth argument is the partial URL of the
	1689	web site within which the cookie is relevant. If the cookie should
	1690	be sent to the server for every access to the entire site,
	1691	set this argument to <code>/</code>. The final argument is the
	1692	web site name or entire domain for which this cookie should be
	1693	submitted; if you choose to have the cookie sent back for an
	1694	entire domain, this argument must begin with a dot, such as
	1695	<code>.boutell.com</code>. The cgic variables <a name="#cgiScriptName</a>
	1696	and <a name="#cgiServerName">cgiServerName</a> are convenient
	1697	values for the fourth and fifth arguments.
	1698	See also <a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>,
	1699	<a href="#cgiCookieString">cgiCookieString</a>,
	1700	<a href="#cgiCookieString">cgiCookieInteger</a> and
	1701	<a href="#cgiCookies">cgiCookies</a>.
	1702	<br><br><dt><strong><a name="cgiHeaderCookieSetInteger">
	1703	void cgiHeaderCookieSetInteger(char *name, int value,
	1704	int secondsToLive, char path, char domain)</a>
	1705	</strong><br><dd>
	1706	cgiHeaderCookieSetInteger() is identical to
	1707	<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>,
	1708	except that the value to be set is an integer rather than a string.
	1709	See <a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
	1710	for complete information.
	1711	<br>
	1712	<br><dt><strong><a name="cgiCookieString">cgiFormResultType cgiCookieString(
	1713	char name, char result, int max)</a>
	1714	</strong><br><dd>cgiFormString attempts to retrieve the string sent for the
	1715	specified cookie (browser-side persistent storage). The
	1716	text will be copied into
	1717	the buffer specified by result, up to but not
	1718	exceeding max-1 bytes; a terminating null is then
	1719	added to complete the string.
	1720	cgiCookieString returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the string was
	1721	successfully retrieved,
	1722	<a href="#cgiFormTruncated">cgiFormTruncated</a> if the string was
	1723	retrieved but was truncated to fit the buffer,
	1724	cgiFormEmpty if the string was
	1725	retrieved but was empty, and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no
	1726	such cookie was submitted. In the last case,
	1727	an empty string is copied to result.
	1728	<br><br><dt><strong><a name="cgiCookieInteger">cgiFormResultType cgiCookieInteger(
	1729	char name, int result, int defaultV)</a>
	1730	See also <a href="#cgiCookieString">cgiCookieInteger</a>,
	1731	<a href="#cgiCookies">cgiCookies</a>,
	1732	<a href="#cgiHeaderCookieSetString>cgiHeaderCookieSetString</a>, and
	1733	<a href="#cgiHeaderCookieSetInteger>cgiHeaderCookieSetInteger</a>.
	1734	</strong><br><dd>cgiCookieInteger() attempts to retrieve the integer sent for the
	1735	specified cookie (browser-side persistent storage). The value
	1736	pointed to by result will be set to the value submitted.
	1737	cgiCookieInteger() returns
	1738	cgiFormSuccess if the value was successfully retrieved,
	1739	cgiFormEmpty if the value submitted is an empty string,
	1740	cgiFormBadType if the value submitted is not an integer,
	1741	and <a href="#cgiFormNotFound">cgiFormNotFound</a> if no such
	1742	input field was submitted. In the last three cases, the value
	1743	pointed to by result is set to the specified default.
	1744	See also <a href="#cgiCookieString">cgiCookieString</a>,
	1745	<a href="#cgiCookies">cgiCookies</a>,
	1746	<a href="#cgiHeaderCookieSetString>cgiHeaderCookieSetString</a>, and
	1747	<a href="#cgiHeaderCookieSetInteger>cgiHeaderCookieSetInteger</a>.
	1748	<br><br><dt><strong><a name="cgiCookies">cgiFormResultType cgiCookies(
	1749	char name, char **ptrToStringArray)</a>
	1750	</strong><br><dd>cgiCookies is useful when the programmer cannot know the names
	1751	of all relevant cookies (browser-side persistent strings) in advance.
	1752	The value pointed to by result will be set to a pointer to an array
	1753	of strings; the last
	1754	entry in the array will be a null pointer. This array is allocated
	1755	by the CGI library. Important: when done working with the array,
	1756	you must call cgiStringArrayFree() with the array pointer as the
	1757	argument. cgiCookies() returns <a href="#cgiFormSuccess">cgiFormSuccess</a> except in the event of an out of memory error.
	1758	On success, ptrToStringArray is set to point to a
	1759	valid array of strings, with the last element in the array being a
	1760	null pointer; in the out-of-memory case ptrToStringArray is set to
	1761	a null pointer, and
	1762	<a href="#cgiFormOutOfMemory">cgiFormOutOfMemory</a> is returned.
	1763	<br><br><dt><strong><a name="cgiHtmlEscape">
	1764	cgiFormResultType cgiHtmlEscape(char *s)</a>
	1765	</strong><br><dd>
	1766	cgiHtmlEscape() outputs the specified null-terminated string to
	1767	<a href="#cgiOut">cgiOut</a>,
	1768	escaping any <, &, and > characters encountered correctly so that
	1769	they do not interfere with HTML markup. Returns
	1770	<a href="#cgiFormSuccess">cgiFormSuccess</a>, or
	1771	<a href="#cgiFormIO">cgiFormIO</a> in the event of an I/O error.
	1772	<p>
	1773	<br><br><dt><strong><a name="cgiHtmlEscapeData">
	1774	cgiFormResultType cgiHtmlEscapeData(char *data, int len)</a>
	1775	</strong><br><dd>
	1776	cgiHtmlEscapeData() is identical to <a href="#cgiHtmlEscape">cgiHtmlEscape</a>,
	1777	except that the data is not null-terminated. This version of the function
	1778	outputs <code>len</code> bytes. See <a href="#cgiHtmlEscape">cgiHtmlEscape</a>
	1779	for more information.
	1780	<br><br><dt><strong><a name="cgiValueEscape">
	1781	cgiFormResultType cgiValueEscape(char *s)</a>
	1782	</strong><br><dd>
	1783	cgiValueEscape() outputs the specified null-terminated string to
	1784	<a href="#cgiOut">cgiOut</a>,
	1785	escaping any " characters encountered correctly so that
	1786	they do not interfere with the quotation marks of HTML attribute
	1787	values. This is useful when outputting a string as part of the
	1788	value attribute of an input tag, or the href attribute of a link
	1789	or form tag. This function returns
	1790	<a href="#cgiFormSuccess">cgiFormSuccess</a>, or
	1791	<a href="#cgiFormIO">cgiFormIO</a> in the event of an I/O error.
	1792	<p>
	1793	<br><br><dt><strong><a name="cgiValueEscapeData">
	1794	cgiFormResultType cgiValueEscapeData(char *data, int len)</a>
	1795	</strong><br><dd>
	1796	cgiValueEscapeData() is identical to <a href="#cgiValueEscape">cgiValueEscape</a>,
	1797	except that the data is not null-terminated. This version of the function
	1798	outputs <code>len</code> bytes. See <a href="#cgiValueEscape">cgiValueEscape</a>
	1799	for more information.
	1800	<br><br><dt><strong><a name="cgiWriteEnvironment">
	1801	cgiEnvironmentResultType cgiWriteEnvironment(char *filename)</a>
	1802	</strong><br><dd>
	1803	cgiWriteEnvironment() can
	1804	be used to write the entire CGI environment, including
	1805	form data, to the specified output file; <a href="#cgiReadEnvironment">
	1806	cgiReadEnvironment()</a>
	1807	can then be used to restore that environment from the specified
	1808	input file for debugging. Of course, these will only work as expected
	1809	if you use the <a href="#variables">cgic copies of the CGI environment
	1810	variables</a> and <a href="#cgiIn">cgiIn</a> and
	1811	<a href="#cgiOut">cgiOut</a> rather than stdin and
	1812	stdout (also see above). These functions are useful in order
	1813	to capture real CGI situations while the web server is running, then
	1814	recreate them in a debugging environment. Both functions
	1815	return <a href="#cgiEnvironmentSuccess">cgiEnvironmentSuccess</a> on
	1816	success, <a href="#cgiEnvironmentIO">cgiEnvironmentIO</a> on an I/O
	1817	error, and <a href="#cgiEnvironmentMemory">cgiEnvironmentMemory</a>
	1818	on an out-of-memory error.
	1819	<br><br><dt><strong><a name="cgiReadEnvironment">
	1820	cgiEnvironmentResultType cgiReadEnvironment(char *filename)</a>
	1821	</strong><br><dd>
	1822	cgiReadEnvironment() restores a CGI environment saved to the specified file by
	1823	<a href="#cgiWriteEnvironment">cgiWriteEnvironment().</a>
	1824	Of course, these will only work as expected
	1825	if you use the <a href="#variables">cgic copies of the CGI environment
	1826	variables</a> and <a href="#cgiIn">cgiIn</a> and
	1827	<a href="#cgiOut">cgiOut</a> rather than stdin and
	1828	stdout (also see above). These functions are useful in order
	1829	to capture real CGI situations while the web server is running, then
	1830	recreate them in a debugging environment. Both functions
	1831	return <a href="#cgiEnvironmentSuccess">cgiEnvironmentSuccess</a> on success,
	1832	<a href="#cgiEnvironmentIO">cgiEnvironmentIO</a> on an I/O error, and
	1833	<a href="#cgiEnvironmentMemory">cgiEnvironmentMemory</a>
	1834	on an out-of-memory error.
	1835	<br><br><dt><strong><a name="cgiMain">int cgiMain()</a>
	1836	</strong><br><dd><strong>The programmer must write this function</strong>, which performs
	1837	the unique task of the program and is invoked by the true main()
	1838	function, found in the cgic library itself. The return value from
	1839	cgiMain will be the return value of the program. It is expected that
	1840	the user will make numerous calls to the cgiForm functions
	1841	from within this function. See <a href="#howto">how to write
	1842	a cgic application</a> for details.
	1843	</dl>
	1844	<h3><a name="variables">cgic variable reference</a></h3>
	1845	This section provides a reference guide to the various global
	1846	variables provided by cgic for the programmer to utilize.
	1847	These variables should always be used in preference to
	1848	stdin, stdout, and calls to getenv() in order to ensure
	1849	compatibility with the <a href="#debug">cgic CGI debugging features</a>.
	1850	<p>
	1851	Most of these variables are equivalent to various CGI environment
	1852	variables. The most important difference is that the cgic
	1853	environment string variables are never null pointers. They will always
	1854	point to valid C strings of zero or more characters.
	1855	<dl>
	1856	<br><dt><strong><a name="cgiServerSoftware">char *cgiServerSoftware</a>
	1857	</strong><br><dd>Points to the name of the server software,
	1858	or to an empty string if unknown.
	1859	<br><dt><strong><a name="cgiServerName">char *cgiServerName</a>
	1860	</strong><br><dd>Points to the name of the server,
	1861	or to an empty string if unknown.
	1862	<br><dt><strong><a name="cgiGatewayInterface">char *cgiGatewayInterface</a>
	1863	</strong><br><dd>Points to the name of the gateway interface (usually CGI/1.1),
	1864	or to an empty string if unknown.
	1865	<br><dt><strong><a name="cgiServerProtocol">char *cgiServerProtocol</a>
	1866	</strong><br><dd>Points to the protocol in use (usually HTTP/1.0),
	1867	or to an empty string if unknown.
	1868	<br><dt><strong><a name="cgiServerPort">char *cgiServerPort</a>
	1869	</strong><br><dd>Points to the port number on which the server is listening
	1870	for HTTP connections (usually 80), or an empty string if unknown.
	1871	<br><dt><strong><a name="cgiRequestMethod">char *cgiRequestMethod</a>
	1872	</strong><br><dd>Points to the method used in the request (usually GET or POST),
	1873	or an empty string if unknown (this should not happen).
	1874	<br><dt><strong><a name="cgiPathInfo">char *cgiPathInfo</a>
	1875	</strong><br><dd>Most web servers recognize any additional path information in
	1876	the URL of the request beyond the name of the CGI program itself and
	1877	pass that information on to the program. cgiPathInfo points to this
	1878	additional path information.
	1879	<br><dt><strong><a name="cgiPathTranslated">char *cgiPathTranslated</a>
	1880	</strong><br><dd>Most web servers recognize any additional path information in
	1881	the URL of the request beyond the name of the CGI program itself and
	1882	pass that information on to the program. cgiPathTranslated points
	1883	to this additional path information, translated by the server into a
	1884	filesystem path on the local server.
	1885	<br><dt><strong><a name="cgiScriptName">char *cgiScriptName</a>
	1886	</strong><br><dd>Points to the name under which the program was invoked.
	1887	<br><dt><strong><a name="cgiQueryString">char *cgiQueryString</a>
	1888	</strong><br><dd>Contains any query information submitted by the user as a result
	1889	of a GET-method form or an <ISINDEX> tag. Note that this
	1890	information need not be parsed directly unless an <ISINDEX> tag
	1891	was used; normally it is parsed automatically by the cgic library. Use
	1892	the cgiForm family of functions to retrieve the values associated
	1893	with form input fields. See <a href="#howto">how to write
	1894	a cgic application</a> for more information.
	1895	<br><dt><strong><a name="cgiRemoteHost">char *cgiRemoteHost</a>
	1896	</strong><br><dd>Points to the fully resolved hostname of the browser, if known,
	1897	or an empty string if unknown.
	1898	<br><dt><strong><a name="cgiRemoteAddr">char *cgiRemoteAddr</a>
	1899	</strong><br><dd>Points to the dotted-decimal IP address of the browser, if known,
	1900	or an empty string if unknown.
	1901	<br><dt><strong><a name="cgiAuthType">char *cgiAuthType</a>
	1902	</strong><br><dd>Points to the type of authorization used for the request,
	1903	if any, or an empty string if none or unknown.
	1904	<br><dt><strong><a name="cgiRemoteUser">char *cgiRemoteUser</a>
	1905	</strong><br><dd>Points to the user name under which the user has
	1906	authenticated; an empty string if no authentication has
	1907	taken place. The certainty of this information depends on
	1908	the type of authorization in use; see
	1909	<a href="#cgiAuthType">cgiAuthType</a>.
	1910	<br><dt><strong><a name="cgiRemoteIdent">char *cgiRemoteIdent</a>
	1911	</strong><br><dd>Points to the user name volunteered by the user via
	1912	the user identification protocol; an empty
	1913	string if unknown. This information is not secure.
	1914	Identification demons can be installed by users on
	1915	insecure systems such as Windows machines.
	1916	<br><dt><strong><a name="cgiContentType">char *cgiContentType</a>
	1917	</strong><br><dd>Points to the MIME content type of the information
	1918	submitted by the user, if any; an empty string if no
	1919	information was submitted. If this string is equal to
	1920	<code>application/x-www-form-urlencoded</code> or
	1921	<code>multipart/form-data</code>, the cgic
	1922	library will automatically examine the form data submitted.
	1923	If this string has any other non-empty value, a different
	1924	type of data has been submitted. This is currently very rare,
	1925	as most browsers can only submit forms and file uploads which
	1926	cgic parses directly.
	1927	<br><dt><strong><a name="cgiContentType">char *cgiCookie</a>
	1928	</strong><br><dd>Points to the raw cookie (browser-side persistent storage)
	1929	data submitted by the web browser.
	1930	Programmers should use the functions <a href="#cgiCookies">cgiCookies</a>,
	1931	<a href="#cgiCookieString">cgiCookieString</a> and
	1932	<a href="#cgiCookieInteger">cgiCookieInteger</a> instead of
	1933	examining this string directly.
	1934	<br><dt><strong><a name="cgiAccept">char *cgiAccept</a>
	1935	</strong><br><dd>Points to a space-separated list of MIME content types
	1936	acceptable to the browser (see <a href="#cgiHeaderContentType">
	1937	cgiHeaderContentType()</a> ), or an empty string. Unfortunately, this variable
	1938	is not supplied in a useful form by most current browsers. Programmers wishing
	1939	to make decisions based on the capabilities of the browser
	1940	are advised to check the <a href="#cgiUserAgent">cgiUserAgent</a>
	1941	variable against a list of browsers and capabilities instead.
	1942	<br><dt><strong><a name="cgiUserAgent">char *cgiUserAgent</a>
	1943	</strong><br><dd>
	1944	Points to the name of the browser in use, or an empty
	1945	string if this information is not available.
	1946	<br><dt><strong><a name="cgiReferrer">char *cgiReferrer</a>
	1947	</strong><br><dd>
	1948	Points to the URL of the previous page visited by the user. This is
	1949	often the URL of the form that brought the user to your program.
	1950	Note that reporting this information is entirely up to the browser,
	1951	which may choose not do so, and may choose not to do so truthfully.
	1952	However, this variable is typically accurate. <strong>The frequently
	1953	used misspelling cgiReferer is also supplied as a macro.</strong>
	1954	<br><dt><strong><a name="cgiContentLength">int cgiContentLength</a>
	1955	</strong><br><dd>The number of bytes of form or query data received.
	1956	Note that if the submission is a form or query submission
	1957	the library will read and parse all the information
	1958	directly from cgiIn and/or cgiQueryString. The programmer should
	1959	not do so, and indeed the cgiIn pointer will be at end-of-file
	1960	in such cases.
	1961	<br><dt><strong><a name="cgiOut">FILE *cgiOut</a>
	1962	</strong><br><dd>Pointer to CGI output. The cgiHeader functions, such as
	1963	<a href="#cgiHeaderContentType">cgiHeaderContentType</a>, should
	1964	be used first to output the mime headers; the output HTML
	1965	page, GIF image or other web document should then be written
	1966	to cgiOut by the programmer using standard C I/O functions
	1967	such as fprintf() and fwrite(). cgiOut is normally equivalent
	1968	to stdout; however, it is recommended that cgiOut be used to
	1969	ensure compatibility with future versions of cgic for
	1970	specialized environments.
	1971	<br><dt><strong><a name="cgiIn">FILE *cgiIn</a>
	1972	</strong><br><dd>Pointer to CGI input. In 99.99% of cases, you will not
	1973	need this. CGIC 2.0 supports both regular POST form submissions
	1974	and multipart/form-data file upload form submissions directly.
	1975	</dl>
	1976	<H3><a name="resultcodes">cgic result code reference</a></h3>
	1977	<p>
	1978	In most cases, cgic functions are designed to produce reasonable results
	1979	even when browsers and users do unreasonable things. However, it is sometimes
	1980	important to know precisely which unreasonable things took place, especially
	1981	when assigning a default value or bounding a value is an inadequate
	1982	solution. The following result codes are useful in making this determination.
	1983	<dl>
	1984	<br><dt><strong><a name="cgiFormSuccess">cgiFormSuccess</a>
	1985	</strong><br><dd>Indicates that the function successfully performed at least one
	1986	action (or retrieved at least one value, where applicable).
	1987	<br><dt><strong><a name="cgiFormTruncated">cgiFormTruncated</a>
	1988	</strong><br><dd>Indicates that a string value retrieved from the user was
	1989	cut short to avoid overwriting the end of a buffer.
	1990	<br><dt><strong><a name="cgiFormBadType">cgiFormBadType</a>
	1991	</strong><br><dd>Indicates that a "numeric" value submitted by the user was
	1992	in fact not a legal number.
	1993	<br><dt><strong><a name="cgiFormEmpty">cgiFormEmpty</a>
	1994	</strong><br><dd>Indicates that a field was retrieved but contained no data.
	1995	<br><dt><strong><a name="cgiFormNotFound">cgiFormNotFound</a>
	1996	</strong><br><dd>Indicates that no value was submitted for a particular field.
	1997	<br><dt><strong><a name="cgiFormConstrained">cgiFormConstrained</a>
	1998	</strong><br><dd>Indicates that a numeric value was beyond the specified bounds
	1999	and was forced to the lower or upper bound as appropriate.
	2000	<br><dt><strong><a name="cgiFormNoSuchChoice">cgiFormNoSuchChoice</a>
	2001	</strong><br><dd>Indicates that the value submitted for a single-choice field
	2002	(such as a radio-button group) was not one of the acceptable values.
	2003	This usually indicates a discrepancy between the form and the program.
	2004	<br><dt><strong><a name="cgiFormEOF">cgiFormEOF</a>
	2005	</strong><br><dd>Returned by <a href="#cgiFormFileRead">cgiFormFileRead</a>
	2006	when, at the start of the call, the cgiFilePtr object is already
	2007	positioned at the end of the uploaded file data.
	2008	<br><dt><strong><a name="cgiFormEOF">cgiFormIO</a>
	2009	</strong><br><dd>Returned by <a href="#cgiFormFileRead">cgiFormFileRead</a>
	2010	when an I/O error occurs while reading uploaded file data.
	2011	<br><dt><strong><a name="cgiFormNotAFile">cgiFormNotAFile</a>
	2012	</strong><br><dd>Returned in response to an attempt to manipulate a form field
	2013	that is not a file upload field using a file-related function.
	2014	<br><dt><strong><a name="cgiFormNoContentType">cgiFormNoContentType</a>
	2015	</strong><br><dd>Returned in response to an attempt to fetch the content type of
	2016	a file-upload field when the content type is not specified by the browser.
	2017	<br><dt><strong><a name="cgiFormNoFileName">cgiFormNoFileName</a>
	2018	</strong><br><dd>Returned in response to an attempt to fetch the file name of
	2019	a file-upload field when a file name is not specified by the browser.
	2020	<br><dt><strong><a name="cgiFormOpenFailed">cgiFormOpenFailed</a>
	2021	</strong><br><dd>Returned in response to an attempt to read from a null
	2022	cgiFilePtr object, typically when the programmer has failed to
	2023	check the result of a call to <a href="#cgiFormFileOpen">cgiFormFileOpen</a>.
	2024	<br><dt><strong><a name="cgiEnvironmentMemory">cgiEnvironmentMemory</a>
	2025	</strong><br><dd>Indicates that an attempt to read or write the CGI environment
	2026	to or from a capture file failed due to an out-of-memory error.
	2027	<br><dt><strong><a name="cgiEnvironmentSuccess">cgiEnvironmentSuccess</a>
	2028	</strong><br><dd>Indicates that an attempt to read or write the CGI environment
	2029	to or from a capture file was successful.
	2030	<br><dt><strong><a name="cgiEnvironmentIO">cgiEnvironmentIO</a>
	2031	</strong><br><dd>Indicates that an attempt to read or write the CGI environment
	2032	to or from a capture file failed due to an I/O error.
	2033	<br><dt><strong><a name="cgiEnvironmentWrongVersion">cgiEnvironmentWrongVersion</a>
	2034	</strong><br><dd>Indicates that an attempt to read from a saved debugging CGI environment
	2035	produced by a pre-2.0 version of CGIC was made.
	2036	</dl>
	2037	<h3><a name="index">cgic quick index</a></h3>
	2038	<a href="#cgiAccept">cgiAccept</a> \|
	2039	<a href="#cgiAuthType">cgiAuthType</a> \|
	2040	<a href="#cgiContentLength">cgiContentLength</a> \|
	2041	<a href="#cgiContentType">cgiContentType</a> \|
	2042	<a href="#cgiEnvironmentIO">cgiEnvironmentIO</a> \|
	2043	<a href="#cgiEnvironmentMemory">cgiEnvironmentMemory</a> \|
	2044	<a href="#cgiEnvironmentSuccess">cgiEnvironmentSuccess</a> \|
	2045	<a href="#cgiCookieInteger">cgiCookieInteger</a> \|
	2046	<a href="#cgiCookies">cgiCookies</a> \|
	2047	<a href="#cgiCookieSetInteger">cgiCookieSetInteger</a> \|
	2048	<a href="#cgiCookieSetString">cgiCookieSetString</a> \|
	2049	<a href="#cgiCookieString">cgiCookieString</a> \|
	2050	<a href="#cgiHtmlEscape">cgiHtmlEscape</a> \|
	2051	<a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a> \|
	2052	<a href="#cgiValueEscape">cgiValueEscape</a> \|
	2053	<a href="#cgiValueEscapeData">cgiValueEscapeData</a> \|
	2054	<a href="#cgiFormBadType">cgiFormBadType</a> \|
	2055	<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a> \|
	2056	<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle()</a> \|
	2057	<a href="#cgiFormConstrained">cgiFormConstrained</a> \|
	2058	<a href="#cgiFormDouble">cgiFormDouble()</a> \|
	2059	<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a> \|
	2060	<a href="#cgiFormEOF">cgiFormEOF</a> \|
	2061	<a href="#cgiFormEmpty">cgiFormEmpty</a> \|
	2062	<a href="#cgiFormEntries">cgiFormEntries</a> \|
	2063	<a href="#cgiFormFileClose">cgiFormFileClose</a> \|
	2064	<a href="#cgiFormFileContentType">cgiFormFileContentType</a> \|
	2065	<a href="#cgiFormFileName">cgiFormFileName</a> \|
	2066	<a href="#cgiFormFileOpen">cgiFormFileOpen</a> \|
	2067	<a href="#cgiFormFileRead">cgiFormFileRead</a> \|
	2068	<a href="#cgiFormFileSize">cgiFormFileSize</a> \|
	2069	<a href="#cgiFormInteger">cgiFormInteger()</a> \|
	2070	<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded()</a> \|
	2071	<a href="#cgiFormNoContentType>cgiFormNoContentType</a> \|
	2072	<a href="#cgiFormNoFileName>cgiFormNoFileName</a> \|
	2073	<a href="#cgiFormNoSuchChoice">cgiFormNoSuchChoice</a> \|
	2074	<a href="#cgiFormNotAFile>cgiFormNotAFile</a> \|
	2075	<a href="#cgiFormNotFound">cgiFormNotFound</a> \|
	2076	<a href="#cgiFormRadio">cgiFormRadio()</a> \|
	2077	<a href="#cgiFormSelectMultiple">cgiFormSelectMultiple()</a> \|
	2078	<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> \|
	2079	<a href="#cgiFormString">cgiFormString()</a> \|
	2080	<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> \|
	2081	<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a> \|
	2082	<a href="#cgiFormStringSpaceNeeded">cgiFormStringSpaceNeeded()</a> \|
	2083	<a href="#cgiFormSuccess">cgiFormSuccess</a> \|
	2084	<a href="#cgiFormTruncated">cgiFormTruncated</a> \|
	2085	<a href="#cgiGatewayInterface">cgiGatewayInterface</a> \|
	2086	<a href="#cgiHeaderContentType">cgiHeaderContentType()</a> \|
	2087	<a href="#cgiHeaderLocation">cgiHeaderLocation()</a> \|
	2088	<a href="#cgiHeaderStatus">cgiHeaderStatus()</a> \|
	2089	<a href="#cgiIn">cgiIn</a> \|
	2090	<a href="#cgiMain">cgiMain()</a>
	2091	<a href="#cgiOut">cgiOut</a> \|
	2092	<a href="#cgiPathInfo">cgiPathInfo</a> \|
	2093	<a href="#cgiPathTranslated">cgiPathTranslated</a> \|
	2094	<a href="#cgiQueryString">cgiQueryString</a> \|
	2095	<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> \|
	2096	<a href="#cgiReferrer">cgiReferrer()</a> \|
	2097	<a href="#cgiRemoteAddr">cgiRemoteAddr</a> \|
	2098	<a href="#cgiRemoteHost">cgiRemoteHost</a> \|
	2099	<a href="#cgiRemoteIdent">cgiRemoteIdent</a> \|
	2100	<a href="#cgiRemoteUser">cgiRemoteUser</a> \|
	2101	<a href="#cgiRequestMethod">cgiRequestMethod</a> \|
	2102	<a href="#cgiScriptName">cgiScriptName</a> \|
	2103	<a href="#cgiServerName">cgiServerName</a> \|
	2104	<a href="#cgiServerPort">cgiServerPort</a> \|
	2105	<a href="#cgiServerProtocol">cgiServerProtocol</a> \|
	2106	<a href="#cgiServerSoftware">cgiServerSoftware</a> \|
	2107	<a href="#cgiStringArrayFree">cgiStringArrayFree()</a> \|
	2108	<a href="#cgiUserAgent">cgiUserAgent</a> \|
	2109	<a href="#cgiWriteEnvironment">cgiWriteEnvironment()</a>
	2110	<p>
	2111	<hr>
	2112	<em><a href="http://www.boutell.com/">Boutell.Com, Inc.</a></em>
	2113	</body>
	2114	</html>
	2115
	2116

Note: See TracBrowser for help on using the repository browser.

Open WPS platform

source: trunk/thirds/cgic206/cgic.html @ 615

Download in other formats:

Download now !

Support ZOO-Project

Search

Context Navigation

Main Navigation

ZOO Sponsors

Knowledge partners

Related links