📄 cgic.html
字号:
<html><head><title>cgic: an ANSI C library for CGI Programming</title></head><body><h1>cgic 2.02: 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="#whatsnew202">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>Anyone can mail questions about the gd and cgic libraries to <a href="mailto:support@boutell.com">support@boutell.com</a>. However, I receive a very large volume of email on many subjects, and while I do my best to respond to all queries this can take some time. Sometimes the response must take the form of an eventual new release or an addition to a FAQ or other document, as opposed to an detailed 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. Purchase orders are also accepted fromFortune 500 corporations and institutions in good standing.To make arrangements, contact <a href="mailto:support@boutell.com">support@boutell.com</a>, or useour <a href="https://www.boutell.com/freeform/">free-form securemessage page</a>. To avoid delay, be sure to specifically mention that you wish to purchase CGIC support at the hourly rate above.<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>cgic is distributed via the web in two forms: as a Windows-compatible.ZIP file, and as a gzipped tar file. Most users of Windows andrelated operating systems have access to 'unzip' or 'pkunzip'. All modern Unix systems come with 'gunzip' and 'tar' as standard equipment, and gzip/gunzipis not difficult to find if yours does not. Versionsof these programs for other operating systems are widelyavailable if you do not already have them.<p><strong>Important:</strong> to use cgic, you will need an ANSI-standardC compiler. Under Unix, just obtain and use gcc. Most Unix systems havestandardiszed on gcc. Users of Windows operating systems should not haveANSI C-related problems as all of the popular compilers follow the ANSI standard.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -