is the buffer to which the data should be copied, and the thirdargument is the size of the buffer. cgic will never write beyondthe size of the buffer, and will always provide a null-terminatedstring in response; if the buffer is too small, the string willbe shortened. If this is not acceptable, the<a href="#cgiFormStringSpaceNeeded">cgiFormStringSpaceNeeded()</a>function can be used to check the amount of space needed; thereturn value of cgiFormStringNoNewlines() can also be checkedto determine whether truncation occurred. Seethe full description of <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>.<h4>Handling Output</h4>Note that Name() writes its HTML output to <a href="#cgiOut">cgiOut</a>, notto stdout.<p>The actual name submitted by the user may or may not containcharacters that have special meaning in HTML, specifically thethe <code>&lt;</code>, <code>&gt;</code>, and <code>&amp;</code> characters.The <a href="#cgiHtmlEscape">cgiHtmlEscape</a> function is used to outputthe user-entered name with any occurrences of these characterscorrectly escaped as <code>&amp;lt;</code>, <code>&amp;gt;</code>, and <code>&amp;amp;</code>.<p><strong>Important:</strong> <a href="#cgiOut">cgiOut</a> is normally equivalentto stdout, and there is no performance penalty for using it.It is recommended that you write output to <a href="#cgiOut">cgiOut</a> to ensure compatibilitywith modified versions of the cgic library for specialenvironments that do not provide stdin and stdout foreach cgi connection.<p>Note that, for text input areas in which carriage returns <em>are</em>desired, the function <a href="#cgiFormString">cgiFormString</a>should be used instead. cgiFormString ensures that line breaksare always represented by a single carriage return (ascii decimal 13),making life easier for the programmer. See the source code tothe Address() function of cgictest.c for an example.<h4>Handling Single Checkboxes</h4>Consider the Hungry() function, which determines whetherthe user has selected the "hungry" checkbox:<PRE>void Hungry() {        if (<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a>("hungry") == <a href="#cgiFormSuccess">cgiFormSuccess</a>) {                fprintf(cgiOut, "I'm Hungry!&lt;BR&gt;\n");        } else {                fprintf(cgiOut, "I'm Not Hungry!&lt;BR&gt;\n");        }}</PRE>This function takes advantage of the<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle()</a> function, whichdetermines whether a single checkbox has been selected. cgiFormCheckboxSingle() accepts the name attribute of the checkboxas its sole argument and returns <a href="#cgiFormSuccess">cgiFormSuccess</a> if the checkbox is selected, or <a href="#cgiFormNotFound">cgiFormNotFound</a> if it is not.If multiple checkboxes with the same name are in use,consider the <a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a> and <a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>functions.<h4>Handling Numeric Input</h4>Now consider the Temperature() function, which retrievesa temperature in degrees (a floating-point value) and ensuresthat it lies within particular bounds:<PRE>void Temperature() {        double temperature;        <a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a>("temperature", &amp;temperature, 80.0, 120.0, 98.6);        fprintf(<a href="#cgiOut">cgiOut</a>, "My temperature is %f.&lt;BR&gt;\n", temperature);}</PRE>The temperature is retrieved by the function <a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a>. The firstargument is the name of the temperature input field in the form;the second argument points to the address of the variable that will contain the result. The next two arguments are the lower and upperbounds, respectively. The final argument is the default value tobe returned if the user did not submit a value.<p>This function always retrieves a reasonable value within thespecified bounds; values above or below bounds are constrainedto fit the bounds. However, the return value ofcgiFormDoubleBounded can be checked to make sure theactual user entry was in bounds, not blank, and so forth;see the description of <a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a> for more details. If bounds checkingis not desired, consider using <a href="#cgiFormDouble">cgiFormDouble()</a> instead.<p>Note that, for integer input, the functions<a href="#cgiFormInteger">cgiFormInteger</a> and<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>are available. The behavior of these functions is similar tothat of their floating-point counterparts above.<h4>Handling Single-Choice Input</h4>The &lt;SELECT&gt; tag of HTML is used to provide the user withseveral choices. Radio buttons and checkboxes can also be usedwhen the number of choices is relatively small. Considerthe Color() function of cgictest.c:<PRE>char *colors[] = {        "Red",        "Green",        "Blue"};void Color() {        int colorChoice;        <a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("colors", colors, 3, &amp;colorChoice, 0);        fprintf(<a href="#cgiOut">cgiOut</a>, "I am: %s&lt;BR&gt;\n", colors[colorChoice]);}</PRE>This function determines which of several colors the user chosefrom a &lt;SELECT&gt; list in the form. An array of colors isdeclared; the <a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a>function is then invoked to determine which, if any, of those choiceswas selected. The first argument indicates the name of the inputfield in the form. The second argument points to the list ofacceptable colors. The third argument indicates the number ofentries in the color array. The fourth argument points to thevariable which will accept the chosen color, and the last argumentindicates the index of the default value to be set if noselection was submitted by the browser. <p><a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> willalways indicate a reasonable selection value. However, ifthe programmer wishes to know for certain that a value wasactually submitted, that the value submitted was a legalresponse, and so on, the return value of cgiFormSelectSingle()can be consulted. See the full description of<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> formore information.<p>Note that radio button groups and &lt;SELECT&gt; lists can bothbe handled by this function. If you are processing radiobutton groups, you may prefer to invoke <a href="#cgiFormRadio">cgiFormRadio()</a>, which functionsidentically. <p><em>"What if I won't know the acceptable choices at runtime?"</em><p>If the acceptable choices aren't known <em>until</em> runtime,one can simply load the choices from disk. But if the acceptablechoices aren't fixed at all (consider a list of country names;new names may be added to the form at any time and it isinconvenient to also update program code or a separate listof countries), simply invoke <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>instead to retrieve the string directly. Keep in mind that, ifyou do so, validating the response to make sure it issafe and legitimate becomes a problem for your ownprogram to solve. The advantage of cgiFormSelectSingle() is that invalid responses are never returned.<p>To handle multiple-selection &lt;SELECT&gt; lists andgroups of checkboxes with the same name, see thediscussion of the NonExButtons() function of cgictest.c, immediately below.<h4>Handling Multiple-Choice Input</h4>Consider the first half of the NonExButtons() function of cgictest.c:<PRE>char *votes[] = {	"A",	"B",	"C",	"D"};void NonExButtons() {	int voteChoices[4];	int i;	int result;		int invalid;	char **responses;	/* Method #1: check for valid votes. This is a good idea,		since votes for nonexistent candidates should probably		be discounted... */	fprintf(<a href="#cgiOut">cgiOut</a>, "Votes (method 1):&lt;BR&gt;\n");	result = <a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>("vote", votes, 4, 		voteChoices, &amp;invalid);	if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {		fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!&lt;p&gt;\n");	} else {			fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;ul&gt;\n");		for (i=0; (i &lt; 4); i++) {			if (voteChoices[i]) {				fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;li&gt;%s\n", votes[i]);			}		}		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/ul&gt;\n");	}</PRE>This function takes advantage of<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a>,which is used to identify one or more selected checkboxes with the same name. This function performs identically to<a href="#cgiFormSelectMultiple">cgiFormSelectMultiple()</a>.That is, &lt;SELECT&gt; tags with the MULTIPLE attribute are handledjust like a group of several checkboxes with the same name.<p>The first argument to <a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a> is the name given to allcheckbox input fields in the group. The second argumentpoints to an array of legitimate values; these shouldcorrespond to the VALUE attributes of the checkboxes(or OPTION tags in a &lt;SELECT&gt; list). The third argumentindicates the number of entries in the array oflegitimate values. The fourth argument points toan array of integers with the same number of entriesas the array of legitimate values; each entrywill be set true if that checkbox or option was selected,false otherwise.<p>The last argument points to an integer which will be set to the number of invalid responses (responses not in the array ofvalid responses) that were submitted. If this value is notof interest, the last argument may be a null pointer (0).<p>Note that the return value of cgiFormCheckboxMultiple isinspected to determine whether any choices at all wereset. See the full description of<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>for other possible return values. <p><em>"What if I won't know the acceptable choices at runtime?"</em><p>If the acceptable choices aren't known <em>until</em> runtime,one can simply load the choices from disk. But if the acceptablechoices aren't fixed at all (consider a list of ice cream flavors;new names may be added to the form at any time and it isinconvenient to also update program code or a separate listof countries), a more dynamic approach is needed. Considerthe second half of the NonExButtons() function of cgictest.c:<PRE>	/* Method #2: get all the names voted for and trust them.		This is good if the form will change more often		than the code and invented responses are not a danger		or can be checked in some other way. */	fprintf(<a href="#cgiOut">cgiOut</a>, "Votes (method 2):&lt;BR&gt;\n");	result = <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);	if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {			fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!&lt;p&gt;\n");	} else {		int i = 0;		fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;ul&gt;\n");		while (responses[i]) {			fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;li&gt;%s\n", responses[i]);			i++;		}		fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/ul&gt;\n");	}	/* We must be sure to free the string array or a memory		leak will occur. Simply calling free() would free		the array but not the individual strings. The		function cgiStringArrayFree() does the job completely. */		<A HREF="#cgiStringArrayFree">cgiStringArrayFree</a>(responses);}</PRE>This code excerpt demonstrates an alternate means of retrievinga list of choices. The function<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> is usedto retrieve an array consisting of all the strings submittedfor with a particular input field name. This works both for&lt;SELECT&gt; tags with the MULTIPLE attribute and for groups of checkboxes with the same name. <P>The first argument to <a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> is the name of the input field orgroup of input fields in question. The second argument shouldbe the address of a pointer to a pointer to a string, whichisn't as bad as it sounds. Consider the following simple callof the function:<PRE>/* An array of strings; each C string is an array of characters */char **responses; <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);</PRE>