contrib/bsdinstaller-1.1.6/src/frontends/cgi/cgic.html

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