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

Last change on this file since 1 was 1, checked in by djay, 10 years ago

Initial ZOO SVN Repository Import.

File size: 103.4 KB
Line 
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/">
9The LATEST documentation is available here. Check often
10for new releases.</a></em>
11<blockquote>
12<strong>IMPORTANT NOTICES:</strong>
13<p>
14If you have CGIC 1.05 or earlier, you should upgrade to CGIC 1.07,
15or to CGIC 2.02 or better, in order to obtain important security fixes.
16<p>
17If you have CGIC 2.0 or CGIC 2.01 and you use the cgiCookie routines,
18you should upgrade to CGIC 2.02 or better, in order to obtain
19important 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
41cgic can be used free of charge, <strong>provided that a
42credit notice is provided online.</strong> Alternatively,
43a nonexclusive Commercial License can be purchased, which
44grants the right to use cgic without a public credit notice.
45<p>
46Please see the file
47<code><a href="license.txt">license.txt</a></code>
48for the details of the Basic License and Commercial License,
49including ordering information for the Commercial License.
50<p>
51Thanks are due to Robert Gustavsson, Ken Holervich, Bob Nestor,
52Jon Ribbens, Thomas Strangert, Wu Yongwei, and other CGIC users
53who have corresponded over the years. Although the implementation
54of multipart/form-data file upload support in CGIC 2.x is my own,
55I particularly wish to thank those who submitted their own
56implementations 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>
70Please submit support inquiries about CGIC via our                              <a href="http://www.boutell.com/contact/">contact page</a>.
71Please note that we receive a large volume of inquiries and cannot always
72respond personally. Sometimes
73the response must take the form of an eventual
74new release or an addition to a FAQ or other document, as opposed to an
75detailed individual response.
76<h4>Hourly Support</h4>
77Those requiring support in detail may arrange for direct support
78from the author, Thomas Boutell, at the rate of $50/hr, billed
79directly by credit card. To make arrangements, contact us via our
80our <a href="https://www.boutell.com/freeform/">secure
81message page</a>. To avoid delay, be sure to specifically mention
82that 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>
84Uploaded files properly closed; corrects a resource leak and enables
85file uploads to work properly on platforms with particular file
86locking semantics.
87<h3><a name="whatsnew204">What's new in version 2.04?</a></h3>
88Documentation fixes: the cgiHtmlEscape, cgiHtmlEscapeData,
89cgiValueEscape, and cgiValueEscapeData routines were named
90incorrectly 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
94code closely follows the actual practice of web sites that successfully
95use cookies, rather than attempting to implement the specification.
96The new code can successfully set more than one cookie at a time in
97typical 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
102was exactly equal to the name of a cookie requested with cgiCookieString,
103with no value or equal sign or other characters present, a buffer
104overrun could take place. This was not normal behavior and it is
105unknown whether any actual web server would allow it to occur, however
106we have of course released a patch to correct it.
107Thanks to Nicolas Tomadakis.
108<li>cgiCookieString returned cgiFormTruncated when cgiFormSuccess would
109be appropriate. Fixed; thanks to Mathieu Villeneuve-Belair.
110<li>Cookies are now set using a simpler Set-Cookie: header, and with
111one header line per cookie, based on data collected by Chunfu Lai.
112<li>Memory leaks in cgiReadEnvironment fixed by Merezko Oleg. These
113memory leaks were <em>not</em> experienced in a normal CGI situation, only
114when 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
120warnings and strict ANSI compliance enabled
121<li>Builds out of the box on Windows (#include &lt;fcntl.h&gt; was needed)
122<li>Rare problem in cgiReadEnvironment corrected; no impact on
123normal CGI operations
124<li>cgiCookieString now sets the result to an empty string
125when returning cgiFormNotFound
126<li>Minor code cleanups
127</ul>
128<h3><a name="whatsnew200">What's new in version 2.0?</a></h3>
1291. CGIC 2.0 provides support for file upload fields. User-uploaded
130files are kept in temporary files, to avoid the use of
131excessive swap space (Solaris users may wish to change the
132<code>cgicTempDir</code> macro in cgic.c before compiling).
133The <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
139provide a complete interface to this new functionality. Remember,
140the <code>enctype</code> attribute of the <code>form</code> tag
141must be set to <code>multipart/form-data</code> when
142<code>&lt;input type="file"&gt;</code> tags are used.
143<p>
1442. CGIC 2.0 provides support for setting and examining cookies
145(persistent data storage on the browser side).
146The <code><a href="#cgiCookieString">cgiCookieString</a></code>,
147and <code><a href="#cgiCookieInteger">cgiCookieInteger</a></code>
148and <code><a href="#cgiCookies">cgiCookies</a></code>
149functions retrieve cookies. The
150<code><a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a></code>
151and <code><a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a></code> functions set cookies.
152<p>
1533. CGIC 2.0 offers a convenient way to retrieve a list of all form fields.
154The new <code><a href="#cgiFormEntries">cgiFormEntries</a></code>
155function performs this operation.
156<p>
1574. CGIC 2.0 provides convenience functions to correctly escape
158text before outputting it as part of HTML, or as part of the
159value 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>
1665. Users have often asked the correct way to determine which submit
167button was clicked. This could always be accomplished in previous versions,
168but CGIC 2.0 also provides
169<a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a>,
170a 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>
173A problem with the cgiFormString and related functions has been
174corrected. These functions were previously incorrectly returning cgiFormTruncated
175in cases where the returned string fit the buffer exactly.
176<h3><a name="whatsnew106">What's new in version 1.06?</a></h3>
1771. A potentially significant buffer overflow problem has been
178corrected. Jon Ribbens correctly pointed out to me (and to the
179Internet's bugtraq mailing list) that the cgiFormEntryString
180function, which is used directly or indirectly by almost all
181CGIC programs, can potentially write past the buffer passed
182to it by the programmer. This bug has been corrected.
183Upgrading to version 1.06 is <strong>strongly recommended.</strong>
184<P>
1852. The function <code>cgiSaferSystem()</code> has been
186removed entirely. This function escaped only a few metacharacters,
187while most shells have many, and there was no way to account for
188the many different operating system shells that might be in use
189on different operating systems. Since this led to a false sense
190of security, the function has been removed. It is our recommendation
191that user input should never be passed directly on the command line
192unless it has been carefully shown to contain only characters
193regarded as safe and appropriate by the programmer. Even then, it is
194better to design your utilities to accept their input from standard
195input rather than the command line.
196<h3><a name="whatsnew105">What's new in version 1.05?</a></h3>
197Non-exclusive commercial license fee reduced to $200.
198<h3><a name="whatsnew104">What's new in version 1.04?</a></h3>
199For consistency with other packages, the standard Makefile
200now produces a true library for cgic (libcgic.a).
201<h3><a name="whatsnew103">What's new in version 1.03?</a></h3>
202Version 1.03 sends line feeds only (ascii 10) to end
203Content-type:, Status:, and other HTTP protocol output lines,
204instead of CR/LF sequences. The standard specifies CR/LF.
205Unfortunately, too many servers reject CR/LF to make
206implementation of that standard practical. No server
207tested ever rejects LF alone in this context.
208<h3><a name="whatsnew102">What's new in version 1.02?</a></h3>
209Version 1.02 corrects bugs in previous versions:
210<ul>
211<li>
212<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> specified
213its arguments in the wrong order, with surprising results.
214This bug has been corrected.
215<li>
216Many small changes have been made to increase compatibility.
217cgic now compiles with no warnings under the compilers
218available at boutell.com.
219</ul>
220<h3><a name="whatsnew101">What's new in version 1.01?</a></h3>
221Version 1.01 adds no major functionality but corrects
222significant 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
229accept negative numbers properly. They also accept positive
230numbers with an explicit + sign.
231<li>Hex values containing the digit <code>9</code> are
232now properly decoded.
233<li><a href="#cgiFormString">cgiFormString</a> now
234represents each newline as a single line feed (ascii 10 decimal)
235as described in the documentation, not a carriage return
236(ascii 13 decimal) as in version 1.0. The latter approach
237pleased no one.
238<li><a href="#cgiFormString">cgiFormString</a> and
239<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>
240no longer erroneously return cgiFormEmpty in place of
241cgiFormSuccess.
242<li>The main() function of cgic now flushes standard output
243and sleeps for one second before exiting in order to inhibit
244problems with the completion of I/O on some platforms. This was
245not a cgic bug per se, but has been reported as a common problem
246with CGI when used with the CERN server. This change should
247improve compatibility.
248<li>The single selection example in the testform.html
249example now works properly. This was an error in the
250form itself, not cgic.
251<li><a href="#cgiRemoteUser">cgiRemoteUser</a> and
252<a href="#cgiRemoteIdent">cgiRemoteIdent</a> are now
253documented accurately. They were reversed earlier.
254</ul>
255<h3><a name="whatis">What is cgic?</a></h3>
256cgic is an ANSI C-language library for the creation of CGI-based
257World Wide Web applications. For basic information about
258the CGI standard, see the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">
259CGI documentation</a> at NCSA.
260<p>
261cgic 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
270multiple-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
274environment, including file uploads and cookies
275</ul>
276<p>
277cgic is compatible with any CGI-compliant server environment, and
278compiles without modification in Posix/Unix/Linux and Windows
279environments.
280<h3><a name="obtain">Obtaining cgic</a></h3>
281cgic 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
283related operating systems have access to 'unzip' or 'pkunzip'. All modern Unix
284systems come with 'gunzip' and 'tar' as standard equipment, and gzip/gunzip
285is not difficult to find if yours does not. Versions
286of these programs for other operating systems are widely
287available if you do not already have them.
288<p>
289<strong>Important:</strong> to use cgic, you will need an ANSI-standard
290C compiler. Under Unix, just obtain and use gcc. Most Unix systems have
291standardiszed on gcc. Users of Windows operating systems should not have
292ANSI C-related problems as all of the popular compilers follow the ANSI
293standard.
294<p>
295<strong>Note for Windows Programmers:</strong> you must use a modern
29632-bit compiler. Visual C++ 2.0 or higher, Borland C++ and the
297mingw32 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>
301Remember, the computer on your desk is usually NOT your web server.
302Compiling a Windows console executable will not give you a CGI program that
303can be installed on a Linux-based server.
304</blockquote>
305Your web browser should inquire whether to save the file to disk
306when you select one of the links below. Under Unix and compatible
307operating systems, save it, then issue the following
308commands to unpack it:
309<pre>
310gunzip cgic205.tar.gz
311tar -xf cgic205.tar
312</pre>
313This should produce the subdirectory 'cgic205', which will contain
314the complete cgic distribution for version 2.05, including a copy of this
315documentation in the file cgic.html.
316<p>
317Under Windows and compatible operating systems, save it,
318open a console ("DOS") window, and issue the following commands to unpack it:
319<pre>
320unzip /d cgic205.zip
321</pre>
322Or use the unzip utility of your choice.
323<p>
324This command also produces the subdirectory 'cgic205', which will contain
325the complete cgic distribution for version 2.0, including a copy of this
326documentation in the file cgic.html.
327<p>
328cgic 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>
334The sample application 'cgictest.c' is provided as part of the
335cgic distribution. This CGI program displays an input form,
336accepts a submission, and then displays what was submitted.
337In the process essentially all of cgic's features are tested.
338<p>
339On a Unix system, you can build cgictest simply by typing
340'make cgictest.cgi'. cgic.c and cgictest.c will be compiled and linked
341together to produce the cgictest application. Under non-Unix
342operating systems, you will need to create and compile an appropriate
343project containing the files cgic.c and cgictest.c.
344<p>
345<strong>IMPORTANT:</strong> after compiling cgictest.cgi, you will
346need to place it in a location on your server system which is
347designated by your server administrator as an appropriate location
348for CGI scripts. Some servers are configured to recognize any
349file ending in .cgi as a CGI program when it is found in any
350subdirectory of the server's web space, but this is not always
351the case! The right locations for CGI
352programs vary greatly from one server to another. Resolving
353this issue is between you, your web server administrator,
354and your web server documentation. Before submitting a bug
355report for cgic, make certain that the CGI example programs
356which came with your server <em>do</em> work for you. Otherwise
357it is very likely that you have a server configuration problem.
358<p>
359Once you have moved cgictest.cgi (or cgictest.exe, under Windows)
360to an appropriate cgi directory,
361use the web browser of your choice to access the URL at which
362you have installed it
363(for instance, <code>www.mysite.com/cgi-bin/cgictest.cgi</code>).
364Fill out the various fields in any manner you wish, then
365select the SUBMIT button.
366<p>
367If all goes well, cgictest.cgi will respond with a page which
368indicates the various settings you submitted. If not,
369please reread the section above regarding the correct location in
370which 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
374cgic.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>
378If none of the above proves effective, please see the
379section 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
382itself. How to do this depends on your operating system; under Unix,
383just use the provided Makefile as an example.
384<p>
385Since all CGI applications must perform certain initial
386tasks, such as parsing form data and examining
387environment variables, the cgic library provides its
388own main() function. When you write applications that
389use cgic, you will begin your own programs by writing
390a cgiMain() function, which cgic will invoke when
391the initial cgi work has been successfully completed. Your
392program must also be sure to #include the file cgic.h.
393<p>
394<strong>Important:</strong> if you write your own main()
395function, your program will not link properly. Your own
396code should begin with cgiMain(). The library
397provides main() for you. (Those who prefer different behavior
398can easily modify cgic.c.)
399<p>
400Consider the cgiMain function of cgictest.c:
401<p>
402<PRE>
403int 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, "&lt;HTML&gt;&lt;HEAD&gt;\n");
419  fprintf(cgiOut, "&lt;TITLE&gt;cgic test&lt;/TITLE&gt;&lt;/HEAD&gt;\n");
420  fprintf(cgiOut, "&lt;BODY&gt;&lt;H1&gt;cgic test&lt;/H1&gt;\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, "&lt;hr&gt;\n");
428  }
429  /* Now show the form */
430  ShowForm();
431  /* Finish up the page */
432  fprintf(cgiOut, "&lt;/BODY&gt;&lt;/HTML&gt;\n");
433  return 0;
434}
435</PRE>
436Note the DEBUG #ifdef. If DEBUG is defined at compile time, either by
437inserting the line "#define DEBUG 1" into the program or by setting
438it in the Makefile or other development environment, then the
439LoadEnvironment function is invoked. This function calls
440<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> 
441to restore a captured CGI environment for debugging purposes. See
442also the discussion of the <a href="#debug">capture</a> program, which is
443provided for use in CGI debugging. Because this is a test program,
444the <a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a> function is
445also called to check for the use of a button that requests the reloading
446of a saved CGI environment. A completed CGI program typically would
447never allow the end user to make that decision.
448<h4>Setting Cookies</h4>
449Next, one of the cgiHeader functions should be called.
450This particular program demonstrates many features, including
451the setting of cookies. If the programmer wishes to set a cookie,
452the cookie-setting function must be called
453first, before other headers are output. This is done by the
454CookieSet() function of cgictest.c:
455<pre>
456void 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>
474Since this is a test program, the <a href="#cgiFormString">cgiFormString</a> 
475function is used to fetch the name and value from the form previously filled
476in by the user. Normally, cookie names and values are chosen to meet the
477needs of the programmer and provide a means of identifying the same
478user again later.
479<p>
480The <a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
481function sets the cookie by requesting that the web browser store it.
482<strong>There is never any guarantee that this will happen!</strong>
483Many browsers reject cookies completely; others do not necessarily keep
484them as long as requested or return them with their values intact.
485Always code defensively when using cookies.
486<p>
487The cname and cvalue parameters are of course the namd and value for
488the cookie. The third argument is the time, in seconds, that the
489cookie should "live" on the browser side before it expires; in this
490case 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
492else about cookies.</strong>
493<p>
494The fourth argument identifies the "path" within the web site for which
495the cookie is considered valid. A cookie that should be sent back
496for every access to the site should be set with a path of <code>/</code>.
497In 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
499domain name) is sent. Similarly, a cookie can be considered relevant
500to a single web site or to an entire domain, such as
501<code>www.boutell.com</code> or the entire <code>.boutell.com</code>
502domain. In this case, the current site on which the program is running
503is the only relevant site, so <code><a href="#cgiServerName">cgiServerName</a></code> is used
504as the domain.
505<h4>Outputting the Content Type Header</h4>
506Next, <a href="#cgiHeaderContentType">cgiHeaderContentType()</a> is
507called 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>
511Note that <a href="#cgiHeaderStatus">cgiHeaderStatus()</a> or
512<a href="#cgiHeaderLocation">cgiHeaderLocation()</a> could have
513been invoked instead to output an error code or redirect the
514request to a different URL. Only one of the cgiHeader functions
515should be called in a single execution of the program.
516<p>
517<strong>Important:</strong> one of the cgiHeader functions,
518usually <a href="#cgiHeaderContentType">cgiHeaderContentType()</a>,
519<em>must</em> be invoked before outputting any other
520response to the user. Otherwise, the result will not be a valid
521document and the browser's behavior will be unpredictable.
522You may, of course, output your own ContentType and other
523header information to <a href="#cgiOut">cgiOut</a> if you prefer. The cgiHeader functions
524are provided as a convenience.
525<h4>Handling Form Submissions</h4>
526Like many CGI programs, cgictest makes decisions about the way it
527should behave based on whether various submit buttons have been clicked.
528When either the testcgic or saveenvironment button is present, cgictest
529invokes the HandleSubmit function, which invokes additional functions to
530handle various parts of the form:
531<pre>
532void 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>
556The Name() function of cgictest is shown below, in its simplest
557possible form:
558<PRE>
559void 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>
567The purpose of this function is to retrieve and display the name that was
568input by the user. Since the programmer has decided that names should
569be permitted to have up to 80 characters, a buffer of 81 characters
570has been declared (allowing for the final null character).
571The <a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>
572function is then invoked to retrieve the name and ensure that
573carriage returns are not present in the name (despite the
574incorrect behavior of some web browsers). The first argument
575is the name of the input field in the form, the second argument
576is the buffer to which the data should be copied, and the third
577argument is the size of the buffer. cgic will never write beyond
578the size of the buffer, and will always provide a null-terminated
579string in response; if the buffer is too small, the string will
580be shortened. If this is not acceptable, the
581<a href="#cgiFormStringSpaceNeeded">cgiFormStringSpaceNeeded()</a>
582function can be used to check the amount of space needed; the
583return value of cgiFormStringNoNewlines() can also be checked
584to determine whether truncation occurred. See
585the full description of <a href="#cgiFormStringNoNewlines">
586cgiFormStringNoNewlines()</a>.
587<h4>Handling Output</h4>
588Note that Name() writes its HTML output to <a href="#cgiOut">cgiOut</a>, not
589to stdout.
590<p>
591The actual name submitted by the user may or may not contain
592characters that have special meaning in HTML, specifically the
593the <code>&lt;</code>, <code>&gt;</code>, and <code>&amp;</code> characters.
594The <a href="#cgiHtmlEscape">cgiHtmlEscape</a> function is used to output
595the user-entered name with any occurrences of these characters
596correctly escaped as <code>&amp;lt;</code>, <code>&amp;gt;</code>,
597and <code>&amp;amp;</code>.
598<p>
599<strong>Important:</strong> <a href="#cgiOut">cgiOut</a> is normally equivalent
600to stdout, and there is no performance penalty for using it.
601It is recommended that you write output to <a href="#cgiOut">cgiOut</a> to ensure compatibility
602with modified versions of the cgic library for special
603environments that do not provide stdin and stdout for
604each cgi connection.
605<p>
606Note that, for text input areas in which carriage returns <em>are</em>
607desired, the function <a href="#cgiFormString">cgiFormString</a>
608should be used instead. cgiFormString ensures that line breaks
609are always represented by a single carriage return (ascii decimal 13),
610making life easier for the programmer. See the source code to
611the Address() function of cgictest.c for an example.
612<h4>Handling Single Checkboxes</h4>
613Consider the Hungry() function, which determines whether
614the user has selected the "hungry" checkbox:
615<PRE>
616void Hungry() {
617        if (<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a>("hungry") == <a href="#cgiFormSuccess">cgiFormSuccess</a>) {
618                fprintf(cgiOut, "I'm Hungry!&lt;BR&gt;\n");
619        } else {
620                fprintf(cgiOut, "I'm Not Hungry!&lt;BR&gt;\n");
621        }
622}
623</PRE>
624This function takes advantage of the
625<a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle()</a> function, which
626determines whether a single checkbox has been selected.
627cgiFormCheckboxSingle() accepts the name attribute of the checkbox
628as its sole argument and returns <a href="#cgiFormSuccess">
629cgiFormSuccess</a> if the checkbox is selected, or
630<a href="#cgiFormNotFound">cgiFormNotFound</a> if it is not.
631If multiple checkboxes with the same name are in use,
632consider the <a href="#cgiFormCheckboxMultiple">
633cgiFormCheckboxMultiple()</a> and
634<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a>
635functions.
636<h4>Handling Numeric Input</h4>
637Now consider the Temperature() function, which retrieves
638a temperature in degrees (a floating-point value) and ensures
639that it lies within particular bounds:
640<PRE>
641void Temperature() {
642        double temperature;
643        <a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a>("temperature", &amp;temperature, 80.0, 120.0, 98.6);
644        fprintf(<a href="#cgiOut">cgiOut</a>, "My temperature is %f.&lt;BR&gt;\n", temperature);
645}
646</PRE>
647The temperature is retrieved by the function
648<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded()</a>. The first
649argument is the name of the temperature input field in the form;
650the second argument points to the address of the variable that will
651contain the result. The next two arguments are the lower and upper
652bounds, respectively. The final argument is the default value to
653be returned if the user did not submit a value.
654<p>
655This function always retrieves a reasonable value within the
656specified bounds; values above or below bounds are constrained
657to fit the bounds. However, the return value of
658cgiFormDoubleBounded can be checked to make sure the
659actual user entry was in bounds, not blank, and so forth;
660see the description of <a href="#cgiFormDoubleBounded">
661cgiFormDoubleBounded()</a> for more details. If bounds checking
662is not desired, consider using <a href="#cgiFormDouble">
663cgiFormDouble()</a> instead.
664<p>
665Note that, for integer input, the functions
666<a href="#cgiFormInteger">cgiFormInteger</a> and
667<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>
668are available. The behavior of these functions is similar to
669that of their floating-point counterparts above.
670<h4>Handling Single-Choice Input</h4>
671The &lt;SELECT&gt; tag of HTML is used to provide the user with
672several choices. Radio buttons and checkboxes can also be used
673when the number of choices is relatively small. Consider
674the Color() function of cgictest.c:
675<PRE>
676char *colors[] = {
677        "Red",
678        "Green",
679        "Blue"
680};
681
682void Color() {
683        int colorChoice;
684        <a href="#cgiFormSelectSingle">cgiFormSelectSingle</a>("colors", colors, 3, &amp;colorChoice, 0);
685        fprintf(<a href="#cgiOut">cgiOut</a>, "I am: %s&lt;BR&gt;\n", colors[colorChoice]);
686}
687</PRE>
688This function determines which of several colors the user chose
689from a &lt;SELECT&gt; list in the form. An array of colors is
690declared; the <a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a>
691function is then invoked to determine which, if any, of those choices
692was selected. The first argument indicates the name of the input
693field in the form. The second argument points to the list of
694acceptable colors. The third argument indicates the number of
695entries in the color array. The fourth argument points to the
696variable which will accept the chosen color, and the last argument
697indicates the index of the default value to be set if no
698selection was submitted by the browser.
699<p>
700<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> will
701always indicate a reasonable selection value. However, if
702the programmer wishes to know for certain that a value was
703actually submitted, that the value submitted was a legal
704response, and so on, the return value of cgiFormSelectSingle()
705can be consulted. See the full description of
706<a href="#cgiFormSelectSingle">cgiFormSelectSingle()</a> for
707more information.
708<p>
709Note that radio button groups and &lt;SELECT&gt; lists can both
710be handled by this function. If you are processing radio
711button groups, you may prefer to invoke
712<a href="#cgiFormRadio">cgiFormRadio()</a>, which functions
713identically.
714<p>
715<em>"What if I won't know the acceptable choices at runtime?"</em>
716<p>
717If the acceptable choices aren't known <em>until</em> runtime,
718one can simply load the choices from disk. But if the acceptable
719choices aren't fixed at all (consider a list of country names;
720new names may be added to the form at any time and it is
721inconvenient to also update program code or a separate list
722of countries), simply invoke
723<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines()</a>
724instead to retrieve the string directly. Keep in mind that, if
725you do so, validating the response to make sure it is
726safe and legitimate becomes a problem for your own
727program to solve. The advantage of cgiFormSelectSingle() is that invalid
728responses are never returned.
729<p>
730To handle multiple-selection &lt;SELECT&gt; lists and
731groups of checkboxes with the same name, see the
732discussion of the NonExButtons() function of cgictest.c, immediately below.
733<h4>Handling Multiple-Choice Input</h4>
734Consider the first half of the NonExButtons() function of cgictest.c:
735<PRE>
736char *votes[] = {
737  "A",
738  "B",
739  "C",
740  "D"
741};
742
743void 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):&lt;BR&gt;\n");
755  result = <a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>("vote", votes, 4,
756    voteChoices, &amp;invalid);
757  if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) {
758    fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!&lt;p&gt;\n");
759  } else { 
760    fprintf(<a href="#cgiOut">cgiOut</a>, "My preferred candidates are:\n");
761    fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;ul&gt;\n");
762    for (i=0; (i &lt; 4); i++) {
763      if (voteChoices[i]) {
764        fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;li&gt;%s\n", votes[i]);
765      }
766    }
767    fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/ul&gt;\n");
768  }
769</PRE>
770This function takes advantage of
771<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple()</a>,
772which is used to identify one or more selected checkboxes with
773the same name. This function performs identically to
774<a href="#cgiFormSelectMultiple">cgiFormSelectMultiple()</a>.
775That is, &lt;SELECT&gt; tags with the MULTIPLE attribute are handled
776just like a group of several checkboxes with the same name.
777<p>
778The first argument to <a href="#cgiFormCheckboxMultiple">
779cgiFormCheckboxMultiple()</a> is the name given to all
780checkbox input fields in the group. The second argument
781points to an array of legitimate values; these should
782correspond to the VALUE attributes of the checkboxes
783(or OPTION tags in a &lt;SELECT&gt; list). The third argument
784indicates the number of entries in the array of
785legitimate values. The fourth argument points to
786an array of integers with the same number of entries
787as the array of legitimate values; each entry
788will be set true if that checkbox or option was selected,
789false otherwise.
790<p>
791The last argument points to an integer which will be set to the
792number of invalid responses (responses not in the array of
793valid responses) that were submitted. If this value is not
794of interest, the last argument may be a null pointer (0).
795<p>
796Note that the return value of cgiFormCheckboxMultiple is
797inspected to determine whether any choices at all were
798set. See the full description of
799<a href="#cgiFormCheckboxMultiple">cgiFormCheckboxMultiple</a>
800for other possible return values.
801<p>
802<em>"What if I won't know the acceptable choices at runtime?"</em>
803<p>
804If the acceptable choices aren't known <em>until</em> runtime,
805one can simply load the choices from disk. But if the acceptable
806choices aren't fixed at all (consider a list of ice cream flavors;
807new names may be added to the form at any time and it is
808inconvenient to also update program code or a separate list
809of countries), a more dynamic approach is needed. Consider
810the 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):&lt;BR&gt;\n");
817  result = <a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);
818  if (result == <a href="#cgiFormNotFound">cgiFormNotFound</a>) { 
819    fprintf(<a href="#cgiOut">cgiOut</a>, "I hate them all!&lt;p&gt;\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>, "&lt;ul&gt;\n");
824    while (responses[i]) {
825      fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;li&gt;%s\n", responses[i]);
826      i++;
827    }
828    fprintf(<a href="#cgiOut">cgiOut</a>, "&lt;/ul&gt;\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>
837This code excerpt demonstrates an alternate means of retrieving
838a list of choices. The function
839<a href="#cgiFormStringMultiple">cgiFormStringMultiple()</a> is used
840to retrieve an array consisting of all the strings submitted
841for with a particular input field name. This works both for
842&lt;SELECT&gt; tags with the MULTIPLE attribute and for
843groups of checkboxes with the same name.
844<P>
845The first argument to <a href="#cgiFormStringMultiple">
846cgiFormStringMultiple()</a> is the name of the input field or
847group of input fields in question. The second argument should
848be the address of a pointer to a pointer to a string, which
849isn't as bad as it sounds. Consider the following simple call
850of the function:
851<PRE>
852/* An array of strings; each C string is an array of characters */
853char **responses;
854
855<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a>("vote", &amp;responses);
856</PRE>
857<em>"How do I know how many responses there are?"</em>
858<p>
859After the call, the last entry in the string array will be
860a null pointer. Thus the simple loop:
861<PRE>
862int i = 0;
863while (responses[i]) {
864  /* Do something with the string responses[i] */
865  i++;
866}
867</PRE>
868can be used to walk through the array until the last
869entry is encountered.
870<p>
871<strong>Important:</strong> the
872<a href="#cgiFormStringMultiple">cgiFormStringMultiple</a> function
873returns a pointer to <strong>allocated memory</strong>. Your code
874should not modify the strings in the responses array or the responses
875array itself; if modification is needed, the strings should be
876copied. When your code is done examining the responses array,
877you <strong>MUST</strong> call <a href="#cgiStringArrayFree">
878cgiStringArrayFree()</a> with the array as an argument to free the memory
879associated with the array. Otherwise, the memory will not be available
880again until the program exists. <strong>Don't</strong> just call the
881free() function; if you do, the individual strings will not be freed.
882<h4>Accessing Uploaded Files</h4>
883CGIC provides functions to access files that have been uploaded
884as part of a form submission. <strong>IMPORTANT: you MUST</strong> set
885the <code>enctype</code> attribute of your <code>form</code> tag
886to <code>multipart/form-data</code> for this feature to work! For an
887example, see the <a href="#ShowForm">ShowForm</a> function of
888cgictest.c, examined below.
889<p>
890The <code>File</code> function of cgictest.c takes care of
891receiving uploaded files:
892<pre>
893void 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("&lt;p&gt;No file was uploaded.&lt;p&gt;\n");
905    return;
906  }
907        fprintf(cgiOut, "The filename submitted was: ");
908        cgiHtmlEscape(name);
909        fprintf(cgiOut, "&lt;p&gt;\n");
910        cgiFormFileSize("file", &size);
911        fprintf(cgiOut, "The file size was: %d bytes&lt;p&gt;\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, "&lt;p&gt;\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.&lt;p&gt;\n");
919  fprintf(cgiOut, "The file's contents are shown here:&lt;p&gt;\n");
920  if (cgiFormFileOpen("file", &file) != cgiFormSuccess) {
921    fprintf(cgiOut, "Could not open the file.&lt;p&gt;\n");
922    return;
923  }
924  fprintf(cgiOut, "&lt;pre&gt;\n");
925  while (cgiFormFileRead(file, buffer, sizeof(buffer), &got) ==
926    cgiFormSuccess)
927  {
928    cgiHtmlEscapeData(buffer, got);
929  }
930  fprintf(cgiOut, "&lt;/pre&gt;\n");
931  cgiFormFileClose(file);
932}
933</pre>
934First, the File function checks to determine the filename that was
935submitted by the user. <strong>VERY IMPORTANT: this filename may or
936may not bear any relation to the real name of the file on the user's
937computer, may be deliberately manipulated with malicious intent,</strong>
938and should not be used for <strong>any</strong> purpose unless you have
939determined that its content is safe for your intended use and will not,
940at the very least, overwrite another file of importance to you, especially if
941you intend to use it as a file name on the server side. The cgic library
942itself does not use this file name for temporary storage.
943<p>
944If the <a href="#cgiFormFileName">cgiFormFileName</a> function does
945not succeed, no file was uploaded.
946<p>
947Next, the <a href="#cgiFormFileSize">cgiFormFileSize</a> function is called
948to determine the size of the uploaded file, in bytes.
949<p>
950The File function then proceeds to query the content type of the uploaded
951file.  Files uploaded by the user have their own content type information,
952which may be useful in determining whether the file is an image, HTML document,
953word processing document, or other type of file. However,
954<strong>as with the filename and any other claim made by the browser,
955this information should not be blindly trusted.</strong> The browser
956may upload a file with the name <code>picture.jpg</code> and the
957content type <code>image/jpeg</code>, but this does not guarantee that the
958actual file will contain a valid JPEG image suitable for display.
959<p>
960The content type submitted by the browser can be queried using the
961<a href="#cgiFormFileContentType">cgiFormFileContentType</a> function.
962<p>
963Of course, CGIC also provides access to the actual uploded file.
964First, the programmer calls <a href="#cgiFormFileOpen">cgiFormFileOpen</a>,
965passing the address of a <code>cgiFilePtr</code> object. If this function
966succeeds, the <code>cgiFilePtr</code> object becomes valid, and can be
967used in subsequent calls to <a href="#cgiFormFileRead">cgiFormFileRead</a>.
968Notice that the number of bytes read may be less than the number requested,
969in particular on the last successful call before cgiFormFileRead begins
970to return <code>cgiFormEOF</code>. When cgiFormFileRead no longer returns
971cgiFormSuccess,
972the programmer calls <a href="#cgiFormClose">cgiFormFileClose</a> to
973release the <code>cgiFilePtr</code> object.
974<p>
975The uploaded file data may contain anything, including binary data,
976null characters, and so on. The example program uses the
977<a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a> function to output the
978data with any special characters that have meaning in HTML escaped.
979Most programs will save the uploaded information to a server-side file or
980database.
981<h4>Fetching All Form Entries</h4>
982From time to time, the programmer may not know the names of all
983form fields in advance. In such situations it is convenient to
984use the <a href="#cgiFormEntries">cgiFormEntries</a> function.
985The Entries function of cgictest.c demonstrates the use of
986cgiFormEntries:
987<pre>
988void Entries()
989{
990        char **array, **arrayStep;
991        fprintf(cgiOut, "List of All Submitted Form Field Names:&lt;p&gt;\n");
992        if (cgiFormEntries(&array) != cgiFormSuccess) {
993                return;
994        }
995        arrayStep = array;
996        fprintf(cgiOut, "&lt;ul&gt;\n");
997        while (*arrayStep) {
998                fprintf(cgiOut, "&lt;li&gt;");
999                cgiHtmlEscape(*arrayStep);
1000                fprintf(cgiOut, "\n");
1001                arrayStep++;
1002        }
1003        fprintf(cgiOut, "&lt;/ul&gt;\n");
1004        cgiStringArrayFree(array);
1005}
1006</pre>
1007The cgiFormEntries function retrieves an array of form field names.
1008This array consists of pointers to strings, with a final null pointer
1009to mark the end of the list. The above code illustrates one way of
1010looping through the returned strings. Note the final call to
1011<a href="#cgiStringArrayFree">cgiStringArrayFree</a>, which is
1012essential in order to return the memory used to store the strings
1013and the string array.
1014<h4>Retrieving Cookies</h4>
1015The Cookies function of cgictest.c displays a list of all cookies
1016submitted by the browser with the current form submission, along
1017with their values:
1018<pre>
1019void 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):&lt;p&gt;\n");
1025  if (cgiCookies(&array) != cgiFormSuccess) {
1026    return;
1027  }
1028  arrayStep = array;
1029  fprintf(cgiOut, "&lt;table border=1&gt;\n");
1030  fprintf(cgiOut, "&lt;tr&gt;&lt;th&gt;Cookie&lt;th&gt;Value&lt;/tr&gt;\n");
1031  while (*arrayStep) {
1032    char value[1024];
1033    fprintf(cgiOut, "&lt;tr&gt;");
1034    fprintf(cgiOut, "&lt;td&gt;");
1035    cgiHtmlEscape(*arrayStep);
1036    fprintf(cgiOut, "&lt;td&gt;");
1037    cgiCookieString(*arrayStep, value, sizeof(value));
1038    cgiHtmlEscape(value);
1039    fprintf(cgiOut, "\n");
1040    arrayStep++;
1041  }
1042  fprintf(cgiOut, "&lt;/table&gt;\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:&lt;p&gt;\n");
1047    fprintf(cgiOut, "Name: "); 
1048    cgiHtmlEscape(cname);
1049    fprintf(cgiOut, "Value: "); 
1050    cgiHtmlEscape(cvalue);
1051    fprintf(cgiOut, "&lt;p&gt;\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.&lt;p&gt;\n");
1056  }
1057  cgiStringArrayFree(array);
1058}
1059</pre>
1060<strong>VERY IMPORTANT: YOUR BROWSER MIGHT NOT SUBMIT COOKIES,
1061EVER, REGARDLESS OF WHAT VALUES YOU ENTER INTO THE TEST FORM.</strong>
1062Many, many browsers are configured not to accept or send cookies;
1063others are configured to send them as little as possible to meet the
1064bare minimum requirements for entry into popular sites. Users will often
1065refuse your cookies; make sure your code still works in that situation!
1066<p>
1067The above code uses the <a href="#cgiCookies">cgiCookies</a> function
1068to retrieve a list of all currently set cookies as a null-terminated
1069array of strings. The <a href="#cgiCookieString">cgiCookieString</a>
1070function is then used to fetch the value associated with each cookie;
1071this function works much like <a href="#cgiFormString">cgiFormString</a>,
1072discussed earlier. Note that a cookie set as a part of the current
1073form submission process does not appear on this list immediately, as
1074it has not yet been sent back by the browser. It should appear on
1075future submissions, provided that the browser chooses to accept
1076and resend the cookie at all.
1077<h4>Displaying a Form That Submits to the Current Program</h4>
1078CGI programmers often need to display HTML pages as part of the output
1079of CGI programs; these HTML pages often contain forms which should submit
1080fields back to the same program they came from. Provided that your
1081web server is well-configured, this can be done conveniently using
1082the cgiScriptName environment variable, as shown below. Here is the
1083source code of the ShowForm function of cgictest.c:
1084<pre>
1085void ShowForm()
1086{
1087  fprintf(cgiOut, "&lt;!-- 2.0: multipart/form-data is required
1088    "for file uploads. --&gt;");
1089  fprintf(cgiOut, "&lt;form method=\"POST\" "
1090    "enctype=\"multipart/form-data\" ");
1091  fprintf(cgiOut, "  action=\"");
1092  cgiValueEscape(cgiScriptName);
1093  fprintf(cgiOut, "\"&gt;\n");
1094  fprintf(cgiOut, "&lt;p&gt;\n");
1095  fprintf(cgiOut, "Text Field containing Plaintext\n");
1096  fprintf(cgiOut, "&lt;p&gt;\n");
1097  fprintf(cgiOut, "&lt;input type=\"text\" name=\"name\"&gt;Your Name\n");
1098  fprintf(cgiOut, "&lt;p&gt;\n");
1099  fprintf(cgiOut, "Multiple-Line Text Field\n");
1100  fprintf(cgiOut, "&lt;p&gt;\n");
1101  fprintf(cgiOut, "&lt;textarea NAME=\"address\" ROWS=4 COLS=40&gt;\n");
1102  fprintf(cgiOut, "Default contents go here. \n");
1103  fprintf(cgiOut, "&lt;/textarea&gt;\n");
1104  fprintf(cgiOut, "&lt;p&gt;\n");
1105  fprintf(cgiOut, "Checkbox\n");
1106  fprintf(cgiOut, "&lt;p&gt;\n");
1107  fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"hungry\" checked&gt;Hungry\n");
1108  fprintf(cgiOut, "&lt;p&gt;\n");
1109  fprintf(cgiOut, "Text Field containing a Numeric Value\n");
1110  fprintf(cgiOut, "&lt;p&gt;\n");
1111  fprintf(cgiOut, "&lt;input type=\"text\" name=\"temperature\" value=\"98.6\"&gt;\n");
1112  fprintf(cgiOut, "Blood Temperature (80.0-120.0)\n");
1113  fprintf(cgiOut, "&lt;p&gt;\n");
1114  fprintf(cgiOut, "Text Field containing an Integer Value\n");
1115  fprintf(cgiOut, "&lt;p&gt;\n");
1116  fprintf(cgiOut, "&lt;input type=\"text\" name=\"frogs\" value=\"1\"&gt;\n");
1117  fprintf(cgiOut, "Frogs Eaten\n");
1118  fprintf(cgiOut, "&lt;p&gt;\n");
1119  fprintf(cgiOut, "Single-SELECT\n");
1120  fprintf(cgiOut, "&lt;br&gt;\n");
1121  fprintf(cgiOut, "&lt;select name=\"colors\"&gt;\n");
1122  fprintf(cgiOut, "&lt;option value=\"Red\"&gt;Red\n");
1123  fprintf(cgiOut, "&lt;option value=\"Green\"&gt;Green\n");
1124  fprintf(cgiOut, "&lt;option value=\"Blue\"&gt;Blue\n");
1125  fprintf(cgiOut, "&lt;/select&gt;\n");
1126  fprintf(cgiOut, "&lt;br&gt;\n");
1127  fprintf(cgiOut, "Multiple-SELECT\n");
1128  fprintf(cgiOut, "&lt;br&gt;\n");
1129  fprintf(cgiOut, "&lt;select name=\"flavors\" multiple&gt;\n");
1130  fprintf(cgiOut, "&lt;option value=\"pistachio\"&gt;Pistachio\n");
1131  fprintf(cgiOut, "&lt;option value=\"walnut\"&gt;Walnut\n");
1132  fprintf(cgiOut, "&lt;option value=\"creme\"&gt;Creme\n");
1133  fprintf(cgiOut, "&lt;/select&gt;\n");
1134  fprintf(cgiOut, "&lt;p&gt;Exclusive Radio Button Group: Age of "
1135    "Truck in Years\n");
1136  fprintf(cgiOut, "&lt;input type=\"radio\" name=\"age\" "
1137    "value=\"1\"&gt;1\n");
1138  fprintf(cgiOut, "&lt;input type=\"radio\" name=\"age\" "
1139    "value=\"2\"&gt;2\n");
1140  fprintf(cgiOut, "&lt;input type=\"radio\" name=\"age\" "
1141    "value=\"3\" checked&gt;3\n");
1142  fprintf(cgiOut, "&lt;input type=\"radio\" name=\"age\" "
1143    "value=\"4\"&gt;4\n");
1144  fprintf(cgiOut, "&lt;p&gt;Nonexclusive Checkbox Group: "
1145    "Voting for Zero through Four Candidates\n");
1146  fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"vote\" "
1147    "value=\"A\"&gt;A\n");
1148  fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"vote\" "
1149    "value=\"B\"&gt;B\n");
1150  fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"vote\" "
1151    "value=\"C\"&gt;C\n");
1152  fprintf(cgiOut, "&lt;input type=\"checkbox\" name=\"vote\" "
1153    "value=\"D\"&gt;D\n");
1154  fprintf(cgiOut, "&lt;p&gt;File Upload:\n");
1155  fprintf(cgiOut, "&lt;input type=\"file\" name=\"file\" "
1156    "value=\"\"&gt; (Select A Local File)\n");
1157  fprintf(cgiOut, "&lt;p&gt;\n");
1158  fprintf(cgiOut, "&lt;p&gt;Set a Cookie&lt;p&gt;\n");
1159  fprintf(cgiOut, "&lt;input name=\"cname\" "
1160    "value=\"\"&gt; Cookie Name\n");
1161  fprintf(cgiOut, "&lt;input name=\"cvalue\" "
1162    "value=\"\"&gt; Cookie Value&lt;p&gt;\n");
1163  fprintf(cgiOut, "&lt;input type=\"submit\" "
1164    "name=\"testcgic\" value=\"Submit Request\"&gt;\n");
1165  fprintf(cgiOut, "&lt;input type=\"reset\" "
1166    "value=\"Reset Request\"&gt;\n");
1167  fprintf(cgiOut, "&lt;p&gt;Save the CGI Environment&lt;p&gt;\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).&lt;p&gt;\n");
1172  fprintf(cgiOut, "&lt;input type=\"submit\" name=\"saveenvironment\" "
1173    "value=\"Save Environment\"&gt;\n");
1174  fprintf(cgiOut, "&lt;/form&gt;\n");
1175}
1176</pre>
1177Note the use of <code>enctype="multipart/form-data"</code> in the
1178<code>FORM</code> tag. This is absolutely required if the form
1179will contain file upload fields, as in the above example. Most
1180browsers will not even attempt file uploads without the
1181presence of this attribute.
1182<h4>Examining CGI environment variables</h4>
1183The CGI standard specifies a number of environment variables
1184which are set by the server. However, servers are somewhat
1185unpredictable as to whether these variables will be null or
1186point to empty strings when an environment variable is not set.
1187Also, in order to allow the programmer to restore saved
1188CGI environments, the cgic library needs have a way of insulating
1189the programmer from the actual environment variables.
1190<p>
1191Instead of calling getenv() to determine the value of a
1192variable such as HTTP_USER_AGENT (the browser software being used),
1193always use the
1194<a href="#variables">cgic copies of the environment variables</a>,
1195which are always valid C strings (they are never null, although
1196they may point to an empty string). For instance, the cgic
1197variable containing the name of the browser software is
1198<a href="#cgiUserAgent">cgiUserAgent</a>. The referring URL appears
1199in the variable <a href="#cgiReferrer">cgiReferrer</a>.
1200<h3><a name="images">How can I generate images from my cgic application?</a></h3>
1201cgic can be used in conjunction with the
1202<a href="http://www.boutell.com/gd/">gd graphics library</a>, which
1203can produce GIF images on the fly.
1204<p>
1205The following short sample program hints at the possibilities:
1206<pre>
1207#include "cgic.h"
1208#include "gd.h"
1209
1210char *colors[] = {
1211  "red", "green", "blue"
1212};
1213
1214#define colorsTotal 3
1215
1216int 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, &amp;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>
1248Note that this program would need to be linked with both cgic.o
1249and libgd.a. Often programs of this type respond to one
1250cgiPathInfo value or set of form fields by returning an HTML page
1251with an inline image reference that, in turn, generates a GIF image.
1252<h3><a name="debug">Debugging CGI applications: using capture</a></h3>
1253Debugging CGI applications can be a painful task. Since CGI applications
1254run in a special environment created by the web server, it is difficult
1255to execute them in a debugger. However, the cgic library provides a way
1256of capturing "live" CGI environments to a file, and also provides a way
1257to reload saved environments.
1258<p>
1259The provided program 'capture.c' can be used to capture CGI
1260environments. Just change the first line of the cgiMain() function
1261of capture.c to save the CGI environment to a filename appropriate
1262on your system and type 'make capture'. Then place capture in your
1263cgi directory and set the form action or other link you want to test
1264to point to it. When the form submission or other link takes place,
1265capture will write the CGI environment active at that time to
1266the filename you specified in the source. The
1267<a href="#cgiReadEnvironment">cgiReadEnvironment()</a> function can then
1268be invoked on the same filename at the beginning of the cgiMain() function
1269of the application you want to test in order to restore the captured
1270environment.  You can then execute your program in the debugger of your choice,
1271and it should perform exactly as it would have performed had
1272it been launched by the actual web server, including file uploads,
1273cookies and all other phenomena within the purview of cgic.
1274<p>
1275<strong>Important:</strong> Make sure you specify the full path, as the
1276current working directory of a CGI script may not be what you
1277think it is!
1278<p>
1279<strong>Even More Important:</strong> If you call getenv() yourself
1280in your code, instead of using the provided <a href="#variables">
1281cgic copies of the CGI environment variables</a>, you will
1282<em>not</em> get the values you expect when running with
1283a saved CGI environment. Always use the cgic variables instead
1284of 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">
1308cgiFormResultType cgiFormStringNoNewlines(
1309  char *name, char *result, int max)</a>
1310</strong><br><dd>
1311cgiFormStringNoNewlines() 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">
1318cgiFormResultType cgiFormStringSpaceNeeded(
1319  char *name, int *length)</a>
1320</strong><br><dd>
1321cgiFormStringSpaceNeeded() 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>
1374cgiStringArrayFree() 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">
1391cgiFormResultType 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">
1417cgiFormResultType cgiFormDoubleBounded(
1418  char *name, double *result, double min, double max,
1419  double defaultV)</a>
1420</strong><br><dd>
1421cgiFormDoubleBounded() 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">
1434cgiFormResultType cgiFormSelectSingle(
1435  char *name, char **choicesText, int choicesTotal,
1436  int *result, int defaultV)</a>
1437</strong><br><dd>
1438cgiFormSelectSingle() retrieves the selection number associated with a
1439  &lt;SELECT&gt; element that does not allow multiple selections. name
1440  should identify the NAME attribute of the &lt;SELECT&gt; 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">
1452cgiFormResultType 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  &lt;SELECT&gt; element that does allow multiple selections. name should
1457  identify the NAME attribute of the &lt;SELECT&gt; 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">
1473cgiFormResultType cgiFormSubmitClicked(
1474  char *name)</a>
1475</strong><br><dd>
1476It 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">
1484cgiFormResultType cgiFormCheckboxSingle(
1485  char *name)</a>
1486</strong><br><dd>
1487cgiFormCheckboxSingle 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">
1496cgiFormResultType 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">
1516cgiFormResultType 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> 
1599and <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> 
1616and <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> 
1627and <a href="#cgiFormFileRead">cgiFormFileRead</a>.
1628<br><br><dt><strong><a name="cgiHeaderLocation">
1629void cgiHeaderLocation(char *redirectUrl)</a>
1630</strong><br><dd>
1631cgiHeaderLocation() should be called if the programmer wishes to
1632redirect the user to a different URL. No futher output
1633is needed in this case.
1634<p>
1635If you wish to set cookies,
1636<strong>you must make your calls to
1637<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
1638and
1639<a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>
1640</strong> BEFORE invoking cgiHeaderLocation.
1641<br><br><dt><strong><a name="cgiHeaderStatus">
1642void cgiHeaderStatus(int status, char *statusMessage)</a>
1643</strong><br><dd>
1644cgiHeaderStatus() should be called if the programmer wishes to
1645output an HTTP error status code instead of a document. The status
1646code is the first argument; the second argument is the status
1647message to be displayed to the user.
1648<p>
1649If you wish to set cookies,
1650<strong>you must make your calls to
1651<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
1652and
1653<a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>
1654</strong> BEFORE invoking cgiHeaderStatus.
1655<br><br><dt><strong><a name="cgiHeaderContentType">
1656void cgiHeaderContentType(char *mimeType)</a>
1657</strong><br><dd>
1658cgiHeaderContentType() should be called if the programmer wishes to
1659output a new document in response to the user's request. This is
1660the normal case. The single argument is the MIME document type
1661of the response; typical values are "text/html" for HTML documents,
1662"text/plain" for plain ASCII without HTML tags, "image/gif" for
1663a GIF image and "audio/basic" for .au-format audio.
1664<p>
1665If you wish to set cookies,
1666<strong>you must make your calls to
1667<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
1668and
1669<a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a>
1670</strong> BEFORE invoking cgiHeaderContentType.
1671<br><br><dt><strong><a name="cgiHeaderCookieSetString">
1672void cgiHeaderCookieSetString(char *name, char *value,
1673  int secondsToLive, char *path, char *domain)</a>
1674</strong><br><dd>
1675cgiHeaderCookieSetString() should be called when the programmer wishes
1676to store a piece of information in the user's browser, so that the
1677stored information is again presented to the server on subsequent
1678accesses to the relevant site. The first argument is the name of the
1679cookie to be stored; for best results in all browsers, use a short
1680name without spaces or unusual punctuation. The second argument is
1681the value of the cookie to be stored. Again, for best results, use
1682a short string; it is recommended that cookies be used to store a
1683unique identifier which is then used to look up more detailed
1684information in a database on the server side. Attempts to store
1685elaborate information on the browser side are much more likely to fail.
1686The third argument is the number of seconds that the cookie should
1687be kept by the browser; 86400 is a single full day, 365*86400 is
1688roughly one year. The fourth argument is the partial URL of the
1689web site within which the cookie is relevant. If the cookie should
1690be sent to the server for every access to the entire site,
1691set this argument to <code>/</code>. The final argument is the
1692web site name or entire domain for which this cookie should be
1693submitted; if you choose to have the cookie sent back for an
1694entire domain, this argument must begin with a dot, such as
1695<code>.boutell.com</code>. The cgic variables <a name="#cgiScriptName</a>
1696and <a name="#cgiServerName">cgiServerName</a> are convenient
1697values for the fourth and fifth arguments.
1698See 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">
1703void cgiHeaderCookieSetInteger(char *name, int value,
1704  int secondsToLive, char *path, char *domain)</a>
1705</strong><br><dd>
1706cgiHeaderCookieSetInteger() is identical to
1707<a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>,
1708except that the value to be set is an integer rather than a string.
1709See <a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a>
1710for 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">
1764cgiFormResultType cgiHtmlEscape(char *s)</a>
1765</strong><br><dd>
1766cgiHtmlEscape() outputs the specified null-terminated string to
1767<a href="#cgiOut">cgiOut</a>,
1768escaping any &lt;, &amp;, and &gt; characters encountered correctly so that
1769they 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">
1774cgiFormResultType cgiHtmlEscapeData(char *data, int len)</a>
1775</strong><br><dd>
1776cgiHtmlEscapeData() is identical to <a href="#cgiHtmlEscape">cgiHtmlEscape</a>,
1777except that the data is not null-terminated. This version of the function
1778outputs <code>len</code> bytes. See <a href="#cgiHtmlEscape">cgiHtmlEscape</a>
1779for more information.
1780<br><br><dt><strong><a name="cgiValueEscape">
1781cgiFormResultType cgiValueEscape(char *s)</a>
1782</strong><br><dd>
1783cgiValueEscape() outputs the specified null-terminated string to
1784<a href="#cgiOut">cgiOut</a>,
1785escaping any " characters encountered correctly so that
1786they do not interfere with the quotation marks of HTML attribute
1787values. This is useful when outputting a string as part of the
1788value attribute of an input tag, or the href attribute of a link
1789or 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">
1794cgiFormResultType cgiValueEscapeData(char *data, int len)</a>
1795</strong><br><dd>
1796cgiValueEscapeData() is identical to <a href="#cgiValueEscape">cgiValueEscape</a>,
1797except that the data is not null-terminated. This version of the function
1798outputs <code>len</code> bytes. See <a href="#cgiValueEscape">cgiValueEscape</a>
1799for more information.
1800<br><br><dt><strong><a name="cgiWriteEnvironment">
1801cgiEnvironmentResultType cgiWriteEnvironment(char *filename)</a>
1802</strong><br><dd>
1803cgiWriteEnvironment() 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">
1820cgiEnvironmentResultType cgiReadEnvironment(char *filename)</a>
1821</strong><br><dd>
1822cgiReadEnvironment() 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>
1845This section provides a reference guide to the various global
1846variables provided by cgic for the programmer to utilize.
1847These variables should always be used in preference to
1848stdin, stdout, and calls to getenv() in order to ensure
1849compatibility with the <a href="#debug">cgic CGI debugging features</a>.
1850<p>
1851Most of these variables are equivalent to various CGI environment
1852variables. The most important difference is that the cgic
1853environment string variables are never null pointers. They will always
1854point 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,
1858or 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,
1861or 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),
1864or 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),
1867or 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
1870for 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),
1873or 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
1876the URL of the request beyond the name of the CGI program itself and
1877pass that information on to the program. cgiPathInfo points to this
1878additional 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
1881the URL of the request beyond the name of the CGI program itself and
1882pass that information on to the program. cgiPathTranslated points
1883to this additional path information, translated by the server into a
1884filesystem 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
1889of a GET-method form or an &lt;ISINDEX&gt; tag. Note that this
1890information need not be parsed directly unless an &lt;ISINDEX&gt; tag
1891was used; normally it is parsed automatically by the cgic library. Use
1892the cgiForm family of functions to retrieve the values associated
1893with form input fields. See <a href="#howto">how to write
1894a 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,
1897or 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,
1900or 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,
1903if 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
1906authenticated; an empty string if no authentication has
1907taken place. The certainty of this information depends on
1908the 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
1912the user identification protocol; an empty
1913string if unknown. This information is not secure.
1914Identification demons can be installed by users on
1915insecure 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
1918submitted by the user, if any; an empty string if no
1919information 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
1922library will automatically examine the form data submitted.
1923If this string has any other non-empty value, a different
1924type of data has been submitted. This is currently very rare,
1925as most browsers can only submit forms and file uploads which
1926cgic 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)
1929data submitted by the web browser.
1930Programmers should use the functions <a href="#cgiCookies">cgiCookies</a>,
1931<a href="#cgiCookieString">cgiCookieString</a> and
1932<a href="#cgiCookieInteger">cgiCookieInteger</a> instead of
1933examining 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
1936acceptable to the browser (see <a href="#cgiHeaderContentType">
1937cgiHeaderContentType()</a> ), or an empty string. Unfortunately, this variable
1938is not supplied in a useful form by most current browsers. Programmers wishing
1939to make decisions based on the capabilities of the browser
1940are advised to check the <a href="#cgiUserAgent">cgiUserAgent</a>
1941variable against a list of browsers and capabilities instead.
1942<br><dt><strong><a name="cgiUserAgent">char *cgiUserAgent</a>
1943</strong><br><dd>
1944Points to the name of the browser in use, or an empty
1945string if this information is not available.
1946<br><dt><strong><a name="cgiReferrer">char *cgiReferrer</a>
1947</strong><br><dd>
1948Points to the URL of the previous page visited by the user. This is
1949often the URL of the form that brought the user to your program.
1950Note that reporting this information is entirely up to the browser,
1951which may choose not do so, and may choose not to do so truthfully.
1952However, this variable is typically accurate. <strong>The frequently
1953used 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>
1978In most cases, cgic functions are designed to produce reasonable results
1979even when browsers and users do unreasonable things. However, it is sometimes
1980important to know precisely which unreasonable things took place, especially
1981when assigning a default value or bounding a value is an inadequate
1982solution. 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
1986action (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
1989cut 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
1992in 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
1999and 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.
2003This 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>
2006when, at the start of the call, the cgiFilePtr object is already
2007positioned 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>
2010when 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
2013that 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
2016a 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
2019a 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
2022cgiFilePtr object, typically when the programmer has failed to
2023check 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
2026to 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
2029to 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
2032to 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
2035produced 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.

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png