<em>"How do I know how many responses there are?"</em><p>After the call, the last entry in the string array will bea null pointer. Thus the simple loop:<PRE>int i = 0;while (responses[i]) {	/* Do something with the string responses[i] */	i++;}</PRE>can be used to walk through the array until the lastentry is encountered.<p><strong>Important:</strong> the <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a> functionreturns a pointer to <strong>allocated memory</strong>. Your codeshould not modify the strings in the responses array or the responsesarray itself; if modification is needed, the strings should becopied. When your code is done examining the responses array,you <strong>MUST</strong> call <a href="#cgiStringArrayFree">cgiStringArrayFree()</a> with the array as an argument to free the memory associated with the array. Otherwise, the memory will not be available again until the program exists. <strong>Don't</strong> just call the free() function; if you do, the individual strings will not be freed.<h4>Accessing Uploaded Files</h4>CGIC provides functions to access files that have been uploadedas part of a form submission. <strong>IMPORTANT: you MUST</strong> setthe <code>enctype</code> attribute of your <code>form</code> tagto <code>multipart/form-data</code> for this feature to work! For anexample, see the <a href="#ShowForm">ShowForm</a> function of cgictest.c, examined below.<p>The <code>File</code> function of cgictest.c takes care of receiving uploaded files:<pre>void File(){	cgiFilePtr file;	char name[1024];	char contentType[1024];	char buffer[1024];	int size;	int got;	if (cgiFormFileName("file", name, sizeof(name)) != 		cgiFormSuccess) 	{		printf("&lt;p&gt;No file was uploaded.&lt;p&gt;\n");		return;	}         fprintf(cgiOut, "The filename submitted was: ");        cgiHtmlEscape(name);        fprintf(cgiOut, "&lt;p&gt;\n");        cgiFormFileSize("file", &size);        fprintf(cgiOut, "The file size was: %d bytes&lt;p&gt;\n", size);        cgiFormFileContentType("file", contentType, sizeof(contentType));        fprintf(cgiOut, "The alleged content type of the file was: ");        cgiHtmlEscape(contentType);        fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Of course, this is only the claim the browser "		"made when uploading the file. Much like the filename, "		"it cannot be trusted.&lt;p&gt;\n");	fprintf(cgiOut, "The file's contents are shown here:&lt;p&gt;\n");	if (cgiFormFileOpen("file", &file) != cgiFormSuccess) {		fprintf(cgiOut, "Could not open the file.&lt;p&gt;\n");		return;	}	fprintf(cgiOut, "&lt;pre&gt;\n");	while (cgiFormFileRead(file, buffer, sizeof(buffer), &got) ==		cgiFormSuccess)	{		cgiHtmlEscapeData(buffer, got);	}	fprintf(cgiOut, "&lt;/pre&gt;\n");	cgiFormFileClose(file);}</pre>First, the File function checks to determine the filename that wassubmitted by the user. <strong>VERY IMPORTANT: this filename may ormay not bear any relation to the real name of the file on the user'scomputer, may be deliberately manipulated with malicious intent,</strong>and should not be used for <strong>any</strong> purpose unless you havedetermined that its content is safe for your intended use and will not,at the very least, overwrite another file of importance to you, especially ifyou intend to use it as a file name on the server side. The cgic libraryitself does not use this file name for temporary storage.<p>If the <a href="#cgiFormFileName">cgiFormFileName</a> function doesnot succeed, no file was uploaded.<p>Next, the <a href="#cgiFormFileSize">cgiFormFileSize</a> function is calledto determine the size of the uploaded file, in bytes.<p>The File function then proceeds to query the content type of the uploadedfile.  Files uploaded by the user have their own content type information, which may be useful in determining whether the file is an image, HTML document,word processing document, or other type of file. However,<strong>as with the filename and any other claim made by the browser,this information should not be blindly trusted.</strong> The browsermay upload a file with the name <code>picture.jpg</code> and thecontent type <code>image/jpeg</code>, but this does not guarantee that theactual file will contain a valid JPEG image suitable for display.<p>The content type submitted by the browser can be queried using the<a href="#cgiFormFileContentType">cgiFormFileContentType</a> function.<p>Of course, CGIC also provides access to the actual uploded file. First, the programmer calls <a href="#cgiFormFileOpen">cgiFormFileOpen</a>,passing the address of a <code>cgiFilePtr</code> object. If this functionsucceeds, the <code>cgiFilePtr</code> object becomes valid, and can beused in subsequent calls to <a href="#cgiFormFileRead">cgiFormFileRead</a>.Notice that the number of bytes read may be less than the number requested,in particular on the last successful call before cgiFormFileRead beginsto return <code>cgiFormEOF</code>. When cgiFormFileRead no longer returns cgiFormSuccess, the programmer calls <a href="#cgiFormClose">cgiFormFileClose</a> torelease the <code>cgiFilePtr</code> object.<p>The uploaded file data may contain anything, including binary data,null characters, and so on. The example program uses the <a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a> function to output thedata with any special characters that have meaning in HTML escaped.Most programs will save the uploaded information to a server-side file ordatabase.<h4>Fetching All Form Entries</h4>From time to time, the programmer may not know the names of allform fields in advance. In such situations it is convenient touse the <a href="#cgiFormEntries">cgiFormEntries</a> function.The Entries function of cgictest.c demonstrates the use ofcgiFormEntries:<pre>void Entries(){        char **array, **arrayStep;        fprintf(cgiOut, "List of All Submitted Form Field Names:&lt;p&gt;\n");        if (cgiFormEntries(&array) != cgiFormSuccess) {                return;        }        arrayStep = array;        fprintf(cgiOut, "&lt;ul&gt;\n");        while (*arrayStep) {                fprintf(cgiOut, "&lt;li&gt;");                cgiHtmlEscape(*arrayStep);                fprintf(cgiOut, "\n");                arrayStep++;        }        fprintf(cgiOut, "&lt;/ul&gt;\n");        cgiStringArrayFree(array);}</pre>The cgiFormEntries function retrieves an array of form field names.This array consists of pointers to strings, with a final null pointerto mark the end of the list. The above code illustrates one way oflooping through the returned strings. Note the final call to<a href="#cgiStringArrayFree">cgiStringArrayFree</a>, which isessential in order to return the memory used to store the stringsand the string array.<h4>Retrieving Cookies</h4>The Cookies function of cgictest.c displays a list of all cookiessubmitted by the browser with the current form submission, alongwith their values:<pre>void Cookies(){	char **array, **arrayStep;	char cname[1024], cvalue[1024];	fprintf(cgiOut, "Cookies Submitted On This Call, With Values "		"(Many Browsers NEVER Submit Cookies):&lt;p&gt;\n");	if (cgiCookies(&array) != cgiFormSuccess) {		return;	}	arrayStep = array;	fprintf(cgiOut, "&lt;table border=1&gt;\n");	fprintf(cgiOut, "&lt;tr&gt;&lt;th&gt;Cookie&lt;th&gt;Value&lt;/tr&gt;\n");	while (*arrayStep) {		char value[1024];		fprintf(cgiOut, "&lt;tr&gt;");		fprintf(cgiOut, "&lt;td&gt;");		cgiHtmlEscape(*arrayStep);		fprintf(cgiOut, "&lt;td&gt;");		cgiCookieString(*arrayStep, value, sizeof(value));		cgiHtmlEscape(value);		fprintf(cgiOut, "\n");		arrayStep++;	}	fprintf(cgiOut, "&lt;/table&gt;\n");	cgiFormString("cname", cname, sizeof(cname));		cgiFormString("cvalue", cvalue, sizeof(cvalue));		if (strlen(cname)) {		fprintf(cgiOut, "New Cookie Set On This Call:&lt;p&gt;\n");		fprintf(cgiOut, "Name: ");			cgiHtmlEscape(cname);		fprintf(cgiOut, "Value: ");			cgiHtmlEscape(cvalue);		fprintf(cgiOut, "&lt;p&gt;\n");		fprintf(cgiOut, "If your browser accepts cookies "			"(many do not), this new cookie should appear "			"in the above list the next time the form is "			"submitted.&lt;p&gt;\n"); 	}	cgiStringArrayFree(array);}</pre><strong>VERY IMPORTANT: YOUR BROWSER MIGHT NOT SUBMIT COOKIES,EVER, REGARDLESS OF WHAT VALUES YOU ENTER INTO THE TEST FORM.</strong>Many, many browsers are configured not to accept or send cookies;others are configured to send them as little as possible to meet thebare minimum requirements for entry into popular sites. Users will oftenrefuse your cookies; make sure your code still works in that situation!<p>The above code uses the <a href="#cgiCookies">cgiCookies</a> functionto retrieve a list of all currently set cookies as a null-terminatedarray of strings. The <a href="#cgiCookieString">cgiCookieString</a>function is then used to fetch the value associated with each cookie;this function works much like <a href="#cgiFormString">cgiFormString</a>,discussed earlier. Note that a cookie set as a part of the currentform submission process does not appear on this list immediately, asit has not yet been sent back by the browser. It should appear onfuture submissions, provided that the browser chooses to acceptand resend the cookie at all.<h4>Displaying a Form That Submits to the Current Program</h4>CGI programmers often need to display HTML pages as part of the outputof CGI programs; these HTML pages often contain forms which should submitfields back to the same program they came from. Provided that yourweb server is well-configured, this can be done conveniently usingthe cgiScriptName environment variable, as shown below. Here is thesource code of the ShowForm function of cgictest.c:<pre>void ShowForm(){	fprintf(cgiOut, "&lt;!-- 2.0: multipart/form-data is required 		"for file uploads. --&gt;");	fprintf(cgiOut, "&lt;form method=\"POST\" "		"enctype=\"multipart/form-data\" ");	fprintf(cgiOut, "	action=\"");	cgiValueEscape(cgiScriptName);	fprintf(cgiOut, "\"&gt;\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Text Field containing Plaintext\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "&lt;input type=\"text\" name=\"name\"&gt;Your Name\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Multiple-Line Text Field\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "&lt;textarea NAME=\"address\" ROWS=4 COLS=40&gt;\n");	fprintf(cgiOut, "Default contents go here. \n");	fprintf(cgiOut, "&lt;/textarea&gt;\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Checkbox\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"hungry\" checked&gt;Hungry\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Text Field containing a Numeric Value\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "&lt;input type=\"text\" name=\"temperature\" value=\"98.6\"&gt;\n");	fprintf(cgiOut, "Blood Temperature (80.0-120.0)\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Text Field containing an Integer Value\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "&lt;input type=\"text\" name=\"frogs\" value=\"1\"&gt;\n");	fprintf(cgiOut, "Frogs Eaten\n");	fprintf(cgiOut, "&lt;p&gt;\n");	fprintf(cgiOut, "Single-SELECT\n");	fprintf(cgiOut, "&lt;br&gt;\n");	fprintf(cgiOut, "&lt;select name=\"colors\"&gt;\n");	fprintf(cgiOut, "&lt;option value=\"Red\"&gt;Red\n");	fprintf(cgiOut, "&lt;option value=\"Green\"&gt;Green\n");	fprintf(cgiOut, "&lt;option value=\"Blue\"&gt;Blue\n");	fprintf(cgiOut, "&lt;/select&gt;\n");	fprintf(cgiOut, "&lt;br&gt;\n");	fprintf(cgiOut, "Multiple-SELECT\n");	fprintf(cgiOut, "&lt;br&gt;\n");	fprintf(cgiOut, "&lt;select name=\"flavors\" multiple&gt;\n");	fprintf(cgiOut, "&lt;option value=\"pistachio\"&gt;Pistachio\n");	fprintf(cgiOut, "&lt;option value=\"walnut\"&gt;Walnut\n");	fprintf(cgiOut, "&lt;option value=\"creme\"&gt;Creme\n");	fprintf(cgiOut, "&lt;/select&gt;\n");	fprintf(cgiOut, "&lt;p&gt;Exclusive Radio Button Group: Age of "		"Truck in Years\n");	fprintf(cgiOut, "&lt;input type=\"radio\" name=\"age\" "		"value=\"1\"&gt;1\n");