<p><strong>Note for Windows Programmers:</strong> you must use a modern32-bit compiler. Visual C++ 2.0 or higher, Borland C++ and themingw32 gcc compiler are all appropriate, as is cygwin. Do <strong>NOT</strong> use an ancient 16-bit DOS executable compiler, please.<blockquote><h4>What Operating System Does Your WEB SERVER Run?</h4>Remember, the computer on your desk is usually NOT your web server.Compiling a Windows console executable will not give you a CGI program thatcan be installed on a Linux-based server. </blockquote>Your web browser should inquire whether to save the file to diskwhen you select one of the links below. Under Unix and compatibleoperating systems, save it, then issue the followingcommands to unpack it:<pre>gunzip cgic202.tar.gztar -xf cgic202.tar</pre>This should produce the subdirectory 'cgic202', which will containthe complete cgic distribution for version 2.02, including a copy of this documentation in the file cgic.html.<p>Under Windows and compatible operating systems, save it,open a console ("DOS") window, and issue the following commands to unpack it:<pre>unzip /d cgic202.zip</pre>Or use the unzip utility of your choice.<p>This command also produces the subdirectory 'cgic201', which will containthe complete cgic distribution for version 2.0, including a copy of this documentation in the file cgic.html.<p>cgic is available via the web from www.boutell.com:<ul><li><a href="http://www.boutell.com/cgic/cgic202.tar.gz">Obtain cgic: gzipped tar file</a><li><a href="http://www.boutell.com/cgic/cgic202.zip">Obtain cgic: .ZIP file</a></ul><h3><a name="build">Building cgic: a sample application</a></h3>The sample application 'cgictest.c' is provided as part of thecgic distribution. This CGI program accepts input submittedby the form cgictest.html. <p>On a Unix system, you can build cgictest simply by typing'make cgictest.cgi'. cgic.c and cgictest.c will be compiled and linkedtogether to produce the cgictest application. Under non-Unixoperating systems, you will need to create and compile an appropriateproject containing the files cgic.c and cgictest.c. <p><strong>IMPORTANT:</strong> after compiling cgictest.cgi, you willneed to place it in a location on your server system which isdesignated by your server administrator as an appropriate locationfor CGI scripts. Some servers are configured to recognize anyfile ending in .cgi as a CGI program when it is found in anysubdirectory of the server's web space, but this is not alwaysthe case! The right locations for CGIprograms vary greatly from one server to another. Resolvingthis issue is between you, your web server administrator,and your web server documentation. Before submitting a bugreport for cgic, make certain that the CGI example programswhich came with your server <em>do</em> work for you. Otherwiseit is very likely that you have a server configuration problem.<p>Once you have moved cgictest.cgi (or cgictest.exe, under Windows)to an appropriate cgi directory,use the web browser of your choice to access the URL at whichyou have installed it (for instance, <code>www.mysite.com/cgi-bin/cgictest.cgi</code>).Fill out the various fields in any manner you wish, thenselect the SUBMIT button.<p>If all goes well, cgictest.cgi will respond with a page whichindicates the various settings you submitted. If not,please reread the section above regarding the correct location inwhich to install your CGI program on your web server.<h3><a name="nocompile">What to do if it won't compile</a></h3><ul><li><strong>Are you using Visual C++ or Borland C++? Did you forget to addcgic.c to your project?</strong><li><strong>Make sure you are using an ANSI C or C++ compiler.</strong>(All of the Windows compilers are ANSI C compliant.)</ul>If none of the above proves effective, please see thesection regarding <a href="#support">support</a>.<h3><a name="howto">How to write a cgic application</a></h3><em>Note: </em> All cgic applications must be linked to the cgic.c moduleitself. How to do this depends on your operating system; under Unix,just use the provided Makefile as an example.<p>Since all CGI applications must perform certain initialtasks, such as parsing form data and examiningenvironment variables, the cgic library provides itsown main() function. When you write applications thatuse cgic, you will begin your own programs by writinga cgiMain() function, which cgic will invoke whenthe initial cgi work has been successfully completed. Yourprogram must also be sure to #include the file cgic.h.<p><strong>Important:</strong> if you write your own main()function, your program will not link properly. Your owncode should begin with cgiMain(). The libraryprovides main() for you. (Those who prefer different behaviorcan easily modify cgic.c.)<p>Consider the cgiMain function of cgictest.c:<p><PRE>int cgiMain() {#ifdef DEBUG	LoadEnvironment();#endif /* DEBUG */	/* Load a previously saved CGI scenario if that button		has been pressed. */	if (cgiFormSubmitClicked("loadenvironment") == cgiFormSuccess) {		LoadEnvironment();	}	/* Set any new cookie requested. Must be done *before*		outputting the content type. */	CookieSet();	/* Send the content type, letting the browser know this is HTML */	cgiHeaderContentType("text/html");	/* Top of the page */	fprintf(cgiOut, "&lt;HTML&gt;&lt;HEAD&gt;\n");	fprintf(cgiOut, "&lt;TITLE&gt;cgic test&lt;/TITLE&gt;&lt;/HEAD&gt;\n");	fprintf(cgiOut, "&lt;BODY&gt;&lt;H1&gt;cgic test&lt;/H1&gt;\n");	/* If a submit button has already been clicked, act on the 		submission of the form. */	if ((cgiFormSubmitClicked("testcgic") == cgiFormSuccess) ||		cgiFormSubmitClicked("saveenvironment") == cgiFormSuccess)	{		HandleSubmit();		fprintf(cgiOut, "&lt;hr&gt;\n");	}	/* Now show the form */	ShowForm();	/* Finish up the page */	fprintf(cgiOut, "&lt;/BODY&gt;&lt;/HTML&gt;\n");	return 0;}</PRE>Note the DEBUG #ifdef. If DEBUG is defined at compile time, either byinserting the line "#define DEBUG 1" into the program or by settingit in the Makefile or other development environment, then theLoadEnvironment function is invoked. This function calls <a href="#cgiReadEnvironment">cgiReadEnvironment()</a> to restore a captured CGI environment for debugging purposes. Seealso the discussion of the <a href="#debug">capture</a> program, which isprovided for use in CGI debugging. Because this is a test program,the <a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a> function isalso called to check for the use of a button that requests the reloadingof a saved CGI environment. A completed CGI program typically wouldnever allow the end user to make that decision.<h4>Setting Cookies</h4>Next, one of the cgiHeader functions should be called.This particular program demonstrates many features, includingthe setting of cookies. If the programmer wishes to set a cookie,the cookie-setting function must be calledfirst, before other headers are output. This is done by theCookieSet() function of cgictest.c:<pre>void CookieSet(){	char cname[1024];	char cvalue[1024];	/* Must set cookies BEFORE calling 		cgiHeaderContentType */	cgiFormString("cname", cname, sizeof(cname));		cgiFormString("cvalue", cvalue, sizeof(cvalue));		if (strlen(cname)) {		/* Cookie lives for one day (or until 			browser chooses to get rid of it, which 			may be immediately), and applies only to 			this script on this site. */			cgiHeaderCookieSetString(cname, cvalue,			86400, cgiScriptName, cgiServerName);	}}</pre>Since this is a test program, the <a href="#cgiFormString">cgiFormString</a> function is used to fetch the name and value from the form previously filledin by the user. Normally, cookie names and values are chosen to meet theneeds of the programmer and provide a means of identifying the sameuser again later.<p>The <a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>function sets the cookie by requesting that the web browser store it.<strong>There is never any guarantee that this will happen!</strong>Many browsers reject cookies completely; others do not necessarily keepthem as long as requested or return them with their values intact.Always code defensively when using cookies.<p>The cname and cvalue parameters are of course the namd and value forthe cookie. The third argument is the time, in seconds, that thecookie should "live" on the browser side before it expires; in thiscase it has been set to 86,400 seconds, which is exactly one day. <strong>The browser may or may not respect this setting, as with everythingelse about cookies.</strong><p>The fourth argument identifies the "path" within the web site for whichthe cookie is considered valid. A cookie that should be sent backfor every access to the site should be set with a path of <code>/</code>.In this case the cookie is relevant only to the CGI program itself, so<code><a href="#cgiScriptName">cgiScriptName</a></code> (the URL of the CGI program, not including thedomain name) is sent. Similarly, a cookie can be considered relevantto a single web site or to an entire domain, such as <code>www.boutell.com</code> or the entire <code>.boutell.com</code>domain. In this case, the current site on which the program is runningis the only relevant site, so <code><a href="#cgiServerName">cgiServerName</a></code> is usedas the domain.<h4>Outputting the Content Type Header</h4>Next, <a href="#cgiHeaderContentType">cgiHeaderContentType()</a> is called to indicate the MIME type of the document being output, in this case "text/html" (a normal HTML document). A few other common MIME types are"image/gif", "image/jpeg" and "audio/wav". <p>Note that <a href="#cgiHeaderStatus">cgiHeaderStatus()</a> or <a href="#cgiHeaderLocation">cgiHeaderLocation()</a> could havebeen invoked instead to output an error code or redirect therequest to a different URL. Only one of the cgiHeader functionsshould be called in a single execution of the program.<p><strong>Important:</strong> one of the cgiHeader functions,usually <a href="#cgiHeaderContentType">cgiHeaderContentType()</a>, <em>must</em> be invoked before outputting any otherresponse to the user. Otherwise, the result will not be a validdocument and the browser's behavior will be unpredictable.You may, of course, output your own ContentType and otherheader information to <a href="#cgiOut">cgiOut</a> if you prefer. The cgiHeader functionsare provided as a convenience.<h4>Handling Form Submissions</h4>Like many CGI programs, cgictest makes decisions about the way itshould behave based on whether various submit buttons have been clicked.When either the testcgic or saveenvironment button is present, cgictestinvokes the HandleSubmit function, which invokes additional functions tohandle various parts of the form:<pre>void HandleSubmit(){	Name();	Address();	Hungry();	Temperature();	Frogs();	Color();	Flavors();	NonExButtons();	RadioButtons();	File();	Entries();	Cookies();	/* The saveenvironment button, in addition to submitting 		the form, also saves the resulting CGI scenario to 		disk for later replay with the 'load saved environment' 		button. */	if (cgiFormSubmitClicked("saveenvironment") == cgiFormSuccess) {		SaveEnvironment();	}}</pre><h4>Handling Text Input</h4>The Name() function of cgictest is shown below, in its simplestpossible form:<PRE>void Name() {        char name[81];        <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>("name", name, 81);        fprintf(cgiOut, "Name: ");        cgicHtmlEscape(name);        fprintf(cgiOut, "<BR>\n");}</PRE>The purpose of this function is to retrieve and display the name that wasinput by the user. Since the programmer has decided that names shouldbe permitted to have up to 80 characters, a buffer of 81 charactershas been declared (allowing for the final null character). The <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>function is then invoked to retrieve the name and ensure thatcarriage returns are not present in the name (despite theincorrect behavior of some web browsers). The first argumentis the name of the input field in the form, the second argument