📄 cgic.html
字号:
<html><head><title>cgic: an ANSI C library for CGI Programming</title></head><body><h1>cgic 2.05: an ANSI C library for CGI Programming</h1><h2>By <a href="http://www.boutell.com/boutell/">Thomas Boutell</a></h2><em><a href="http://www.boutell.com/cgic/">The LATEST documentation is available here. Check oftenfor new releases.</a></em><blockquote><strong>IMPORTANT NOTICES:</strong><p>If you have CGIC 1.05 or earlier, you should upgrade to CGIC 1.07,or to CGIC 2.02 or better, in order to obtain important security fixes.<p>If you have CGIC 2.0 or CGIC 2.01 and you use the cgiCookie routines, you should upgrade to CGIC 2.02 or better, in order to obtainimportant security fixes.</blockquote><h3>Table of Contents</h3><ul><li><a href="#credits">Credits and license terms</a><li><a href="#support">How to get support</a><li><a href="#whatsnew205">What's new in version XYZ of CGIC?</a><li><a href="#whatis">What is cgic?</a><li><a href="#obtain">Obtaining cgic</a><li><a href="#build">Building and testing cgic: a sample application</a><li><a href="#nocompile">What to do if it won't compile</a><li><a href="#howto">How to write a cgic application</a><li><a href="#images">How can I generate images from my cgic application?</a><li><a href="#debug">CGI debugging features: using capture</a><li><a href="#functions">cgic function reference</a><li><a href="#variables">cgic variable reference</a><li><a href="#resultcodes">cgic result code reference</a><li><a href="#index">cgic quick index</a></ul><h3><a name="credits">Credits and License Terms</a></h3>cgic can be used free of charge, <strong>provided that acredit notice is provided online.</strong> Alternatively,a nonexclusive Commercial License can be purchased, whichgrants the right to use cgic without a public credit notice.<p>Please see the file<code><a href="license.txt">license.txt</a></code>for the details of the Basic License and Commercial License,including ordering information for the Commercial License.<p>Thanks are due to Robert Gustavsson, Ken Holervich, Bob Nestor, Jon Ribbens, Thomas Strangert, Wu Yongwei, and other CGIC users who have corresponded over the years. Although the implementationof multipart/form-data file upload support in CGIC 2.x is my own, I particularly wish to thank those who submitted their own implementations of this feature.<h3><a name="support">How to Get Support</a></h3><blockquote><h4>STOP! READ THIS FIRST! REALLY!</h4> Are you getting a "server error," indicating that your web server "cannot allow POST to this URL," or a similar message? <strong>YOU MUST CONFIGURE YOUR WEB SERVER TO ALLOW CGI PROGRAMS, AND YOU MUST INSTALL CGI PROGRAMS IN THE LOCATION (OR WITH THE EXTENSION) THAT YOUR WEB SERVER EXPECTS TO SEE.</strong> Please don't send me email about this, unless you wish me to configure your web server for you; I can certainly do that for $50/hr, but you can probably straighten this out yourself or have your web server administrator do it.</blockquote><h4>Free Support</h4>Please submit support inquiries about CGIC via our <a href="http://www.boutell.com/contact/">contact page</a>.Please note that we receive a large volume of inquiries and cannot alwaysrespond personally. Sometimesthe response must take the form of an eventualnew release or an addition to a FAQ or other document, as opposed to andetailed individual response.<h4>Hourly Support</h4>Those requiring support in detail may arrange for direct supportfrom the author, Thomas Boutell, at the rate of $50/hr, billeddirectly by credit card. To make arrangements, contact us via ourour <a href="https://www.boutell.com/freeform/">securemessage page</a>. To avoid delay, be sure to specifically mentionthat you wish to purchase CGIC support at the hourly rate above.<h3><a name="whatsnew205">What's new in version 2.05?</a></h3>Uploaded files properly closed; corrects a resource leak and enablesfile uploads to work properly on platforms with particular filelocking semantics.<h3><a name="whatsnew204">What's new in version 2.04?</a></h3>Documentation fixes: the cgiHtmlEscape, cgiHtmlEscapeData,cgiValueEscape, and cgiValueEscapeData routines were namedincorrectly in the manual. No code changes in version 2.04.<h3><a name="whatsnew203">What's new in version 2.03?</a></h3><ul><li>Support for setting cookies has been reimplemented. The newcode closely follows the actual practice of web sites that successfullyuse cookies, rather than attempting to implement the specification.The new code can successfully set more than one cookie at a time intypical web browsers.</ul><h3><a name="whatsnew202">What's new in version 2.02?</a></h3><ul><li>In CGIC 2.0 and 2.01, if the HTTP_COOKIE environment variablewas exactly equal to the name of a cookie requested with cgiCookieString,with no value or equal sign or other characters present, a bufferoverrun could take place. This was not normal behavior and it isunknown whether any actual web server would allow it to occur, howeverwe have of course released a patch to correct it. Thanks to Nicolas Tomadakis.<li>cgiCookieString returned cgiFormTruncated when cgiFormSuccess wouldbe appropriate. Fixed; thanks to Mathieu Villeneuve-Belair.<li>Cookies are now set using a simpler Set-Cookie: header, and withone header line per cookie, based on data collected by Chunfu Lai. <li>Memory leaks in cgiReadEnvironment fixed by Merezko Oleg. Thesememory leaks were <em>not</em> experienced in a normal CGI situation, onlywhen reading a saved CGI environment.</ul><h3><a name="whatsnew201">What's new in version 2.01?</a></h3><ul><li>Makefile supports "make install"<li>Compiles without warnings under both C and C++ with strictwarnings and strict ANSI compliance enabled<li>Builds out of the box on Windows (#include <fcntl.h> was needed)<li>Rare problem in cgiReadEnvironment corrected; no impact onnormal CGI operations<li>cgiCookieString now sets the result to an empty stringwhen returning cgiFormNotFound<li>Minor code cleanups</ul><h3><a name="whatsnew200">What's new in version 2.0?</a></h3>1. CGIC 2.0 provides support for file upload fields. User-uploadedfiles are kept in temporary files, to avoid the use ofexcessive swap space (Solaris users may wish to change the<code>cgicTempDir</code> macro in cgic.c before compiling).The <code><a href="#cgiFormFileName">cgiFormFileName</a></code>, <code><a href="#cgiFormFileContentType">cgiFormFileContentType</a></code>, <code><a href="#cgiFormFileSize">cgiFormFileSize</a></code>, <code><a href="#cgiFormFileOpen">cgiFormFileOpen</a></code>, <code><a href="#cgiFormFileRead">cgiFormFileRead</a></code>, and<code><a href="#cgiFormFileClose">cgiFormFileClose</a></code> functionsprovide a complete interface to this new functionality. Remember,the <code>enctype</code> attribute of the <code>form</code> tagmust be set to <code>multipart/form-data</code> when<code><input type="file"></code> tags are used.<p>2. CGIC 2.0 provides support for setting and examining cookies(persistent data storage on the browser side).The <code><a href="#cgiCookieString">cgiCookieString</a></code>,and <code><a href="#cgiCookieInteger">cgiCookieInteger</a></code>and <code><a href="#cgiCookies">cgiCookies</a></code>functions retrieve cookies. The <code><a href="#cgiHeaderCookieSetString">cgiHeaderCookieSetString</a></code>and <code><a href="#cgiHeaderCookieSetInteger">cgiHeaderCookieSetInteger</a></code> functions set cookies.<p>3. CGIC 2.0 offers a convenient way to retrieve a list of all form fields.The new <code><a href="#cgiFormEntries">cgiFormEntries</a></code>function performs this operation.<p>4. CGIC 2.0 provides convenience functions to correctly escapetext before outputting it as part of HTML, or as part of the value of a tag attribute, such as the <code>HREF</code> or<code>VALUE</code> attribute. See <code><a href="#cgiHtmlEscape">cgiHtmlEscape</a></code>,<code><a href="#cgiHtmlEscapeData">cgiHtmlEscapeData</a></code>,<code><a href="#cgiValueEscape">cgiValueEscape</a></code> and<code><a href="#cgiValueEscapeData">cgiValueEscapeData</a></code>.<p>5. Users have often asked the correct way to determine which submitbutton was clicked. This could always be accomplished in previous versions,but CGIC 2.0 also provides <a href="#cgiFormSubmitClicked">cgiFormSubmitClicked</a>,a convenient alternate label for the <a href="#cgiFormCheckboxSingle">cgiFormCheckboxSingle</a> function.<h3><a name="whatsnew107">What's new in version 1.07?</a></h3>A problem with the cgiFormString and related functions has beencorrected. These functions were previously incorrectly returning cgiFormTruncatedin cases where the returned string fit the buffer exactly.<h3><a name="whatsnew106">What's new in version 1.06?</a></h3>1. A potentially significant buffer overflow problem has beencorrected. Jon Ribbens correctly pointed out to me (and to theInternet's bugtraq mailing list) that the cgiFormEntryStringfunction, which is used directly or indirectly by almost allCGIC programs, can potentially write past the buffer passedto it by the programmer. This bug has been corrected.Upgrading to version 1.06 is <strong>strongly recommended.</strong><P>2. The function <code>cgiSaferSystem()</code> has beenremoved entirely. This function escaped only a few metacharacters,while most shells have many, and there was no way to account forthe many different operating system shells that might be in useon different operating systems. Since this led to a false senseof security, the function has been removed. It is our recommendationthat user input should never be passed directly on the command lineunless it has been carefully shown to contain only charactersregarded as safe and appropriate by the programmer. Even then, it isbetter to design your utilities to accept their input from standardinput rather than the command line.<h3><a name="whatsnew105">What's new in version 1.05?</a></h3>Non-exclusive commercial license fee reduced to $200.<h3><a name="whatsnew104">What's new in version 1.04?</a></h3>For consistency with other packages, the standard Makefilenow produces a true library for cgic (libcgic.a). <h3><a name="whatsnew103">What's new in version 1.03?</a></h3>Version 1.03 sends line feeds only (ascii 10) to end Content-type:, Status:, and other HTTP protocol output lines,instead of CR/LF sequences. The standard specifies CR/LF.Unfortunately, too many servers reject CR/LF to makeimplementation of that standard practical. No servertested ever rejects LF alone in this context. <h3><a name="whatsnew102">What's new in version 1.02?</a></h3>Version 1.02 corrects bugs in previous versions:<ul><li><a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> specifiedits arguments in the wrong order, with surprising results.This bug has been corrected.<li>Many small changes have been made to increase compatibility.cgic now compiles with no warnings under the compilersavailable at boutell.com.</ul><h3><a name="whatsnew101">What's new in version 1.01?</a></h3>Version 1.01 adds no major functionality but corrects significant bugs and incompatibilities:<ul><li><a href="#cgiFormInteger">cgiFormInteger</a>,<a href="#cgiFormIntegerBounded">cgiFormIntegerBounded</a>,<a href="#cgiFormDouble">cgiFormDouble</a> and<a href="#cgiFormDoubleBounded">cgiFormDoubleBounded</a> nowaccept negative numbers properly. They also accept positivenumbers with an explicit + sign.<li>Hex values containing the digit <code>9</code> arenow properly decoded.<li><a href="#cgiFormString">cgiFormString</a> nowrepresents each newline as a single line feed (ascii 10 decimal)as described in the documentation, not a carriage return(ascii 13 decimal) as in version 1.0. The latter approachpleased no one.<li><a href="#cgiFormString">cgiFormString</a> and<a href="#cgiFormStringNoNewlines">cgiFormStringNoNewlines</a>no longer erroneously return cgiFormEmpty in place ofcgiFormSuccess.<li>The main() function of cgic now flushes standard outputand sleeps for one second before exiting in order to inhibitproblems with the completion of I/O on some platforms. This wasnot a cgic bug per se, but has been reported as a common problemwith CGI when used with the CERN server. This change shouldimprove compatibility.<li>The single selection example in the testform.htmlexample now works properly. This was an error in theform itself, not cgic.<li><a href="#cgiRemoteUser">cgiRemoteUser</a> and<a href="#cgiRemoteIdent">cgiRemoteIdent</a> are nowdocumented accurately. They were reversed earlier.</ul><h3><a name="whatis">What is cgic?</a></h3>cgic is an ANSI C-language library for the creation of CGI-basedWorld Wide Web applications. For basic information aboutthe CGI standard, see the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI documentation</a> at NCSA.<p>cgic performs the following tasks:<ul><li>Parses form data, correcting for defective and/or inconsistent browsers<li>Transparently accepts both GET and POST form data<li>Accepts uploaded files as well as regular form fields<li>Provides functions to set and retrieve "cookies"(browser-side persistent information)<li>Handles line breaks in form fields in a consistent manner<li>Provides string, integer, floating-point, and single- andmultiple-choice functions to retrieve form data<li>Provides bounds checking for numeric fields<li>Loads CGI environment variables into C strings which are always non-null<li>Provides a way to capture CGI situations for replay in a debuggingenvironment, including file uploads and cookies</ul><p>cgic is compatible with any CGI-compliant server environment, andcompiles without modification in Posix/Unix/Linux and Windowsenvironments.<h3><a name="obtain">Obtaining cgic</a></h3>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -