📄 readme.txt
字号:
README.txt for cgi-util 2.1.5by: Bill Kendrick <bill@newbreedsoftware.com> Mike Simons <msimons@moria.simons-clan.com>Other contributors listed in "CHANGES.txt"http://www.newbreedsoftware.com/cgi-util/June 16, 1999 - October 18, 2002WHAT IS IT?----------- "cgi-util" is a library which provides a set of C functions you can use to create Common Gateway Interface ("CGI") programs. Simply call cgi-util's initialization function and send HTML (or any other kind of data) out from your program and to the user's web browser. cgi-util allows you to grab data sent to your CGI program by way of forms or URL-encoded data. Both "POST" and "GET" methods are handled transparently. It also supports file-upload. (NOTE: UNDER DEVELOPMENT!) cgi-util is probably not the most feature-filled library, but it is fast, simple and takes virtually no time to learn how to use.INSTALLING IT------------- There are a number of ways you can install the cgi-util library. These are discussed in detail in the file "INSTALL".CREATING A CGI-------------- To create a CGI in C using cgi-util, simply follow these simple steps: 1. Include the cgi-util header file: #include "cgi-util.h" or, if you installed the header file in a shared place: #include <cgi-util.h> 2. Call cgi-util's initialization function: cgiinit(); Note: The "cgiinit()" function returns a status result. To be safe, you should make sure no errors occured: if (cgiinit() != CGIERR_NONE) exit(0); 3. Send a "Content-type" value to the webserver. Since your program's "stdout" stream is connected to your webserver, you can just use "printf()" or "write(0,...)": Since most CGI's generate an HTML page (versus plain text, graphics or some other format), you'll almost always specify the "text/html" content type: printf("Content-type: text/html\n\n"); Note: The two "\n"'s at the end produce a blank line, which ends the HTTP headers. If you want to specify other HTTP headers, you of course can. For example: printf("Content-type: text/html\n"); printf("Pragma: no-cache\n\n"); Simply remember to add that one extra "\n" character at the end to produce the blank line to end your HTTP headers. 4. Use the "cgi_getentry..." family of functions to grab data from the web browser. This data may be coming from an HTML form, or it may have been URL-encoded (in other words, the URL that the browser was directed to included the path to your CGI program, followed by data. For example: http://site.com/path/to/your.cgi?data...") The "cgi_getentry..." family includes: char * cgi_getentrystr() Returns the string value of a form field. int cgi_getentryint() Returns the integer value of a form field. double cgi_getentrydouble() Returns the double (floating point) value of a form field. int cgi_getentrybool() Returns the boolean value of a form field, depending on whether the form string value is "on" or "yes" (true, which returns 1), or "off" or "no" (false, which returns 0). 5. Send HTML data out to the browser based on the input you received. Most of the time, you'll probably be using "printf()" to send HTML to the browser: printf("<html><head><title>...</title></head>\n"); ... printf("</html>\n"); You may also wish to copy entire files to the resulting page. For example, rather than embeding your standard navigation links at the bottom of the CGI's page output, you can create a file and then use on of cgi-util's "cgi_dump..." functions: cgi_dump("file.html"); If you need to change something in the HTML later, you need only edit the HTML file, not the C file. No recompiling need take place. Most of the time, you'll be "dumping" HTML files which you know will be readable, since they are technically part of your CGI software. The standard "dump()" function will abort your CGI with an HTML error message in the rare case that the file can't be open. Hopefully, this will never happen except during development, at which point, you simply correct the problem and it should never break again. If, however, you're trying to open a file which may or may not be available, you can use the "cgi_dump_no_abort()" function call which does not abort the CGI or display any HTML error message, but instead returns an error value: if (cgi_dump_no_abort("file.html") != CGIERR_NONE) ... Finally, another function exists which lets you manually abort your CGI with an HTML error message, "cgi_error()": cgi_error("reason for error"); 6. When you're done, free up any memory used by this instance of your CGI. The "cgi_quit()" function frees any data allocated by the "cgi_init()" function: cgi_quit();FUNCTION DESCRIPTIONS--------------------- The following functions are available when using cgi-util: int cgi_init(void) ------------------ Receives form data. It does this by checking environment variables (which should be set by the webserver before the CGI process begins) to determine how to get the data, and then grabbing it and creating a list of name/value pairs. The following global cgi-util variables are set: int cgi_request_method ---------------------- CGIREQ_NONE if no request method was set (which should never happen), CGIREQ_POST if POST method was used, CGIREQ_GET if GET method was used, or CGIREQ_UNKNOWN if some other method was used. int cgi_num_entries ------------------- The number of name/value pairs received, or 0 if none or an error occured. int cgi_errno ------------- CGIERR_NONE if no errors occured, CGIERR_INCORRECT_TYPE if an incorrect "CONTENT_TYPE" was set by the server or browser, CGIERR_BAD_CONTENT_LENGTH if the "CONTENT_LENGTH" environment variable was not set to an integer value, CGIERR_CONTENT_LENGTH_DISCREPENCY if the "CONTENT_LENGTH" set does not match the amount of data actually received by the CGI, CGIERR_UNKNOWN_METHOD if the "REQUEST_METHOD" was not set to "POST" or "GET" (the two understood by cgi-util), or CGIERR_OUT_OF_MEMORY if space could not be allocated for the data being received. cgi_entry_type * cgi_entries ---------------------------- This will contain a collection of names/values/types/lengths (the number of which is stored in "cgi_num_entries"), or NULL if an error occured. int cgi_content_type -------------------- CGITYPE_UNKNOWN if an unknown "CONTENT_TYPE" was set, CGITYPE_APPLICATION_X_WWW_FORM_URLENCODED if the "CONTENT_TYPE" was set to "application/x-www-form-urlencoded" (the typical type), CGITYPE_MULTIPART_FORM_DATA if the "CONTENT_TYPE" was set to "multipart/form-data" (normal for file-upload). The return value of "cgi_init()" is the value of "cgi_errno". void cgi_quit(void) ------------------- Clears memory allocated by "cgi_init()". Since any pointers which may be freed are initially set to "NULL", and "free()" does nothing to NULL pointers, this can be safely called even if "cgi_init()" failed. The following variables are set: cgi_entry_type * cgi_entries ---------------------------- Set to NULL. int cgi_num_entries ------------------- Set to 0. int cgi_errno ------------- Set to CGIERR_NONE. int cgi_request_method ---------------------- Set to CGIREQ_NONE. char * query ------------ Set to NULL. int cgi_content_type -------------------- Set to CGITYPE_NONE. Since the function is void, nothing is returned. char * cgi_getentrystr(char * field_name) ----------------------------------------- This function looks up a name/value pair named by "field_name" (the name of some form field) and returns the value as a character string pointer. In other words, it goes through all "cgi_entries" (from 0 to "cgi_num_entries - 1") and checks the "name" of each of them. For the first one it finds (if any) that exactly matches the string sent to this function ("field_name"), it will return the "value". This function returns a "NULL" if no name/value pair was found that matched the "field_name" requested. Example: -------- If an HTML form has a text input box named "name": <input type="text" name="name"> ...and someone types "john doe" into it and submits it to your CGI, then the string you receive from the function call: cgi_getentrystr("name"); will be the text "john doe". char * cgi_getnentrystr(char * field_name, int n) ------------------------------------------------- Identical to "cgi_getentrystr()", but for forms with multiple fields with the same name. It returns the 'n'th field with the name 'field_name'. Use "cgi_numentries()" (see below) to determine how many (if any) fields have the name you're interested in. Example: -------- If an HTML form has a number of checkboxes named "choice": <input type="checkbox" name="choice" value="choc">Chocolate <input type="checkbox" name="choice" value="vani">Vanilla ...you can receive the values ("choc" and/or "vani") for the checked items using this in your C code:⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -