Check out the complete transcripts of Tom's online class, Programming 101 By Way of Java!
Have you created a masterpiece
with a Boutell.Com product?
Send
us your URL to be considered for the Boutell.Com Hall of Fame!
Please see the file
license.txt
for the details of the Basic License and Commercial License,
including ordering information for the Commercial License.
However, priority support is available. Priority support customers receive a special support email address from which a personal response within 24 hours (on working days) is provided. Of course, purchasing priority support also encourages further enhancement of cgic, gd and related free boutell.com software.
Priority support can be purchased at the rate of $50 per month, with up to 12 distinct queries per month (reasonable back-and-forth exchanges to resolve a single query are not charged against this limit). After the twelfth query, each additional query costs $5. Preparations to handle support purchases through First Virtual are being made; support may also be paid for by check or money order.
Alternatively, priority support may be purchased à la carte at a rate of $5 per query.
To purchase priority support, send mail to support-request@boutell.com indicating the time period (or number of queries) for which you wish to purchase support and the address to which boutell.com should send an invoice. Invoices may be sent by email or postal mail, at your option, although boutell.com supports resource conservation efforts and prefers to invoice via email when possible. Once you receive the invoice, boutell.com will expect payment within 30 days. You will begin to receive priority support as soon as you declare your intention to purchase said support.
Currently, priority support is intended only to resolve specific difficulties with the gd and cgic libraries. boutell.com priority support is not a budget consulting service. Other inquiries regarding boutell.com software, documentation and the like should be sent to boutell@boutell.com.
9 are
now properly decoded.
cgic performs the following tasks:
cgic should be compatible with any CGI-compliant server environment.
Important: to use cgic, you will need an ANSI-standard C compiler. The Sun cc distributed with SunOS 4.1.3 is not ANSI-standard. Unix users may wish to obtain gcc, which is free and widely available, or purchase Sun's development package, which also includes a proper compiler. Users of Windows-related operating systems should not have ANSI C-related problems as all of the popular compilers follow the ANSI standard.
Note for Windows Programmers: cgic should work in a 16-bit environment but is not designed to cater to such an environment. Form fields which require more than 64K individually will not work as expected unless the huge memory model is used. Using a 32-bit compiler is strongly recommended.
Your web browser should inquire whether to save the file to disk when you select one of the links below. Under Unix and compatible operating systems, save it, then issue the following commands to unpack it:
uncompress cgic105.tar.Z tar -xf cgic105.tarThis should produce the subdirectory 'cgic105', which will contain the complete cgic distribution for version 1.05, including a copy of this documentation in the file cgic.html.
Under Windows and compatible operating systems, save it, open a DOS window, and issue the following commands to unpack it:
pkunzip /d cgic105.zipThis command also produces the subdirectory 'cgic105', which will contain the complete cgic distribution for version 1.05, including a copy of this documentation in the file CGIC.HTM.
cgic is available via the web from www.boutell.com:
On a Unix system, you can build cgictest simply by typing 'make cgictest'. cgic.c and cgictest.c will be compiled and linked together to produce the cgictest application. Under non-Unix operating systems, you will need to create and compile an appropriate project containing the files cgic.c and cgictest.c.
IMPORTANT: after compiling cgictest, you will need to place it in a location on your server system which is designated by your server administrator as an appropriate location for CGI scripts. Also, the URL of the action of the sample form in testform.html must be changed to correctly indicate the location of cgictest on your web server. The right locations for CGI programs vary greatly from one server to another. Resolving this issue is between you, your web server administrator, and your web server documentation. Before submitting a bug report for cgic, make certain that the CGI example programs which came with your server do work for you. Otherwise it is very likely that you have a server configuration problem.
Once you have moved cgictest to an appropriate cgi directory and edited form.html to properly refer to its location, use the web browser of your choice to access form.html. Fill out the various fields in any manner you wish, then select the SUBMIT button.
If all goes well, cgictest will respond with a page which indicates the various settings you submitted. If not, please see the second paragraph above.
unistd.h,
define the preprocessor macro NO_UNISTD and recompile.
system(),
define the preprocessor macro NO_SYSTEM and recompile.
sleep(),
remove the call to that function from the main() function
of cgic.c and recompile.
Since all CGI applications must perform certain initial tasks, such as parsing form data and examining environment variables, the cgic library provides its own main() function. When you write applications that use cgic, you will begin your own programs by writing a cgiMain() function, which cgic will invoke when the initial cgi work has been successfully completed. Your program must also be sure to #include the file cgic.h.
Important: if you write your own main() function, your program will not link properly. Your own code should begin with cgiMain(). The library provides main() for you.
Consider the cgiMain function of cgictest.c:
int cgiMain() {
#if DEBUG
/* Load a saved CGI scenario if we're debugging */
cgiReadEnvironment("/path/to/capcgi.dat");
#endif
/* Important: we must indicate the type of document */
cgiHeaderContentType("text/html");
/* Now invoke other functions to handle each part of the form */
fprintf(cgiOut, "<HTML><HEAD>\n");
fprintf(cgiOut, "<TITLE>cgic test</TITLE></HEAD>\n"):
fprintf(cgiOut, "<BODY><H1>cgic test</H1>\n");
Name();
Address();
Hungry();
Temperature();
Frogs();
Color();
Flavors();
NonExButtons();
RadioButtons();
fprintf(cgiOut, "</BODY></HTML>\n");
/* This value will be the exit code of the program; 0
generally indicates success among Unix and DOS programs */
return 0;
}
Note the DEBUG #ifdef. If DEBUG is defined at compile time, either by
inserting the line "#define DEBUG 1" into the program or by setting
it in the Makefile or other development environment, then the
cgiReadEnvironment() function will be called
to restore a captured CGI environment for debugging purposes. See
the discussion of the capture program, which is
provided for use in CGI debugging.
Note that cgiHeaderStatus() or cgiHeaderLocation() could have been invoked instead to output an error code or redirect the request to a different URL. Only one of the cgiHeader functions should be called in a single execution of the program.
Important: one of the cgiHeader functions, usually cgiHeaderContentType(), must be invoked before outputting any other response to the user. Otherwise, the result will not be a valid document and the browser's behavior will be unpredictable. You may, of course, output your own ContentType and other header information to cgiOut if you prefer. The cgiHeader functions are provided as a convenience.
Next, cgiMain() invokes various functions to handle individual parts of the form. When the function is finished, it returns 0, the usual return code for a successful program.
void Name() {
char name[81];
cgiFormStringNoNewlines("name", name, 81);
fprintf(cgiOut, "Name: %s<BR>\n", name);
}
The purpose of this function is to retrieve and display the name that was
input by the user. Since the programmer has decided that names should
be permitted to have up to 80 characters, a buffer of 81 characters
has been declared (allowing for the final null character).
The cgiFormStringNoNewlines()
function is then invoked to retrieve the name and ensure that
carriage returns are not present in the name (despite the
incorrect behavior of some web browsers). The first argument
is the name of the input field in the form, the second argument
is the buffer to which the data should be copies, and the third
argument is the size of the buffer. cgic will never write beyond
the size of the buffer, and will always provide a null-terminated
string in response; if the buffer is too small, the string will
be shortened. If this is not acceptable, the
cgiFormStringSpaceNeeded()
function can be used to check the amount of space needed; the
return value of cgiFormStringNoNewlines() can also be checked
to determine whether truncation occurred. See
the full description of
cgiFormStringNoNewlines().
Important: cgiOut is normally equivalent to stdout, and there is no performance penalty for using it. It is recommended that you write output to cgiOut to ensure compatibility with future versions of the cgic library for special environments that do not provide stdin and stdout for each cgi connection.
Note that, for text input areas in which carriage returns are desired, the function cgiFormString should be used instead. cgiFormString ensures that line breaks are always represented by a single carriage return (ascii decimal 13), making life easier for the programmer. See the source code to the Address() function of cgictest.c for an example.
void Hungry() {
if (cgiFormCheckboxSingle("hungry") == cgiFormSuccess) {
fprintf(cgiOut, "I'm Hungry!<BR>\n");
} else {
fprintf(cgiOut, "I'm Not Hungry!<BR>\n");
}
}
This function takes advantage of the
cgiFormCheckboxSingle() function, which
determines whether a single checkbox has been selected.
cgiFormCheckboxSingle() accepts the name attribute of the checkbox
as its sole argument and returns
cgiFormSuccess if the checkbox is selected, or
cgiFormNotFound if it is not.
If multiple checkboxes with the same name are in use,
consider the
cgiFormCheckboxMultiple() and
cgiFormStringMultiple()
functions.
void Temperature() {
double temperature;
cgiFormDoubleBounded("temperature", &temperature, 80.0, 120.0, 98.6);
fprintf(cgiOut, "My temperature is %f.<BR>\n", temperature);
}
The temperature is retrieved by the function
cgiFormDoubleBounded(). The first
argument is the name of the temperature input field in the form;
the second argument points to the address of the variable that will
contain the result. The next two arguments are the lower and upper
bounds, respectively. The final argument is the default value to
be returned if the user did not submit a value.
This function always retrieves a reasonable value within the specified bounds; values above or below bounds are constrained to fit the bounds. However, the return value of cgiFormDoubleBounded can be checked to make sure the actual user entry was in bounds, not blank, and so forth; see the description of cgiFormDoubleBounded() for more details. If bounds checking is not desired, consider using cgiFormDouble() instead.
Note that, for integer input, the functions cgiFormInteger and cgiFormIntegerBounded are available. The behavior of these functions is similar to that of their floating-point counterparts above.
char *colors[] = {
"Red",
"Green",
"Blue"
};
void Color() {
int colorChoice;
cgiFormSelectSingle("colors", colors, 3, &colorChoice, 0);
fprintf(cgiOut, "I am: %s<BR>\n", colors[colorChoice]);
}
This function determines which of several colors the user chose
from a <SELECT> list in the form. An array of colors is
declared; the cgiFormSelectSingle()
function is then invoked to determine which, if any, of those choices
was selected. The first argument indicates the name of the input
field in the form. The second argument points to the list of
acceptable colors. The third argument indicates the number of
entries in the color array. The fourth argument points to the
variable which will accept the chosen color, and the last argument
indicates the index of the default value to be set if no
selection was submitted by the browser.
cgiFormSelectSingle() will always indicate a reasonable selection value. However, if the programmer wishes to know for certain that a value was actually submitted, that the value submitted was a legal response, and so on, the return value of cgiFormSelectSingle() can be consulted. See the full description of cgiFormSelectSingle() for more information.
Note that radio button groups and <SELECT> lists can both be handled by this function. If you are processing radio button groups, you may prefer to invoke cgiFormRadio(), which functions identically.
"What if I won't know the acceptable choices at runtime?"
If the acceptable choices aren't known until runtime, one can simply load the choices from disk. But if the acceptable choices aren't fixed at all (consider a list of country names; new names may be added to the form at any time and it is inconvenient to also update program code or a separate list of countries), simply invoke cgiFormStringNoNewlines() instead to retrieve the string directly. Keep in mind that, if you do so, validating the response to make sure it is safe and legitimate becomes a problem for your own program to solve. The advantage of cgiFormSelectSingle() is that invalid responses are never returned.
To handle multiple-selection <SELECT> lists and groups of checkboxes with the same name, see the discussion of the NonExButtons() function of cgictest.c, immediately below.
char *votes[] = {
"A",
"B",
"C",
"D"
};
void NonExButtons() {
int voteChoices[4];
int i;
int result;
int invalid;
char **responses;
/* Method #1: check for valid votes. This is a good idea,
since votes for nonexistent candidates should probably
be discounted... */
fprintf(cgiOut, "Votes (method 1):<BR>\n");
result = cgiFormCheckboxMultiple("vote", votes, 4,
voteChoices, &invalid);
if (result == cgiFormNotFound) {
fprintf(cgiOut, "I hate them all!<p>\n");
} else {
fprintf(cgiOut, "My preferred candidates are:\n");
fprintf(cgiOut, "<ul>\n");
for (i=0; (i < 4); i++) {
if (voteChoices[i]) {
fprintf(cgiOut, "<li>%s\n", votes[i]);
}
}
fprintf(cgiOut, "</ul>\n");
}
This function takes advantage of
cgiFormCheckboxMultiple(),
which is used to identify one or more selected checkboxes with
the same name. This function performs identically to
cgiFormSelectMultiple().
That is, <SELECT> tags with the MULTIPLE attribute are handled
just like a group of several checkboxes with the same name.
The first argument to cgiFormCheckboxMultiple() is the name given to all checkbox input fields in the group. The second argument points to an array of legitimate values; these should correspond to the VALUE attributes of the checkboxes (or OPTION tags in a <SELECT> list). The third argument indicates the number of entries in the array of legitimate values. The fourth argument points to an array of integers with the same number of entries as the array of legitimate values; each entry will be set true if that checkbox or option was selected, false otherwise.
The last argument points to an integer which will be set to the number of invalid responses (responses not in the array of valid responses) that were submitted. If this value is not of interest, the last argument may be a null pointer (0).
Note that the return value of cgiFormCheckboxMultiple is inspected to determine whether any choices at all were set. See the full description of cgiFormCheckboxMultiple for other possible return values.
"What if I won't know the acceptable choices at runtime?"
If the acceptable choices aren't known until runtime, one can simply load the choices from disk. But if the acceptable choices aren't fixed at all (consider a list of ice cream flavors; new names may be added to the form at any time and it is inconvenient to also update program code or a separate list of countries), a more dynamic approach is needed. Consider the second half of the NonExButtons() function of cgictest.c:
/* Method #2: get all the names voted for and trust them.
This is good if the form will change more often
than the code and invented responses are not a danger
or can be checked in some other way. */
fprintf(cgiOut, "Votes (method 2):<BR>\n");
result = cgiFormStringMultiple("vote", &responses);
if (result == cgiFormNotFound) {
fprintf(cgiOut, "I hate them all!<p>\n");
} else {
int i = 0;
fprintf(cgiOut, "My preferred candidates are:\n");
fprintf(cgiOut, "<ul>\n");
while (responses[i]) {
fprintf(cgiOut, "<li>%s\n", responses[i]);
i++;
}
fprintf(cgiOut, "</ul>\n");
}
/* We must be sure to free the string array or a memory
leak will occur. Simply calling free() would free
the array but not the individual strings. The
function cgiStringArrayFree() does the job completely. */
cgiStringArrayFree(responses);
}
This code excerpt demonstrates an alternate means of retrieving
a list of choices. The function
cgiFormStringMultiple() is used
to retrieve an array consisting of all the strings submitted
for with a particular input field name. This works both for
<SELECT> tags with the MULTIPLE attribute and for
groups of checkboxes with the same name.
The first argument to cgiFormStringMultiple() is the name of the input field or group of input fields in question. The second argument should be the address of a pointer to a pointer to a string, which isn't as bad as it sounds. Consider the following simple call of the function:
/* An array of strings; each C string is an array of characters */
char **responses;
cgiFormStringMultiple("vote", &responses);
"How do I know how many responses there are?"
After the call, the last entry in the string array will be a null pointer. Thus the simple loop:
int i = 0;
while (responses[i]) {
/* Do something with the string responses[i] */
i++;
}
can be used to walk through the array until the last
entry is encountered.
Important: unlike other functions in the cgic library, the cgiFormStringMultiple function returns a pointer to allocated memory. Your code should not modify the strings in the responses array or the responses array itself; if modification is needed, the strings should be copied. When your code is done examining the responses array, you MUST call cgiStringArrayFree() with the array as an argument to free the memory associated with the array. Otherwise, the memory may be lost permanently (under some operating systems), or will not be available again until the program exists. Don't just call the free() function; if you do, the individual strings will not be freed.
Instead of calling getenv() to determine the value of a variable such as HTTP_USER_AGENT (the browser software being used), always use the cgic copies of the environment variables, which are always valid C strings (they are never null, although they may point to an empty string). For instance, the cgic variable containing the name of the browser software is cgiUserAgent.
The following short sample program hints at the possibilities:
#include "cgic.h"
#include "gd.h"
char *colors[] = {
"red", "green", "blue"
};
#define colorsTotal 3
int cgiMain() {
int colorChosen;
gdImagePtr im;
int r, g, b;
/* Use gd to create an image */
im = gdImageCreate(64, 64);
r = gdImageColorAllocate(im, 255, 0, 0);
g = gdImageColorAllocate(im, 0, 255, 0);
b = gdImageColorAllocate(im, 0, 0, 255);
/* Now use cgic to find out what color the user requested */
cgiFormSelectSingle("color", 3, &colorChosen, 0);
/* Now fill with the desired color */
switch(colorChosen) {
case 0:
gdImageFill(im, 32, 32, r);
break;
case 1:
gdImageFill(im, 32, 32, g);
break;
case 2:
gdImageFill(im, 32, 32, b);
break;
}
/* Now output the image. Note the content type! */
cgiHeaderContentType("image/gif");
/* Send the image to cgiOut */
gdImageGif(im, cgiOut);
/* Free the gd image */
gdImageDestroy(im);
return 0;
}
Note that this program would need to be linked with both cgic.o
and libgd.a. Often programs of this type respond to one
cgiPathInfo value by returning an HTML page with an inline image
reference that, in turn, generates a GIF image.
The provided program 'capture.c' can be used to capture CGI environments. Just change the first line of the cgiMain() function of capture.c to save the CGI environment to a filename appropriate on your system and type 'make capture'. Then place capture in your cgi directory and set the form action or other link you want to test to point to it. When the form submission or other link takes place, capture will write the CGI environment active at that time to the filename you specified in the source. The cgiReadEnvironment() function can then be invoked on the same filename at the beginning of the cgiMain() function of the application you want to test in order to restore the captured environment. You can then execute your program in the debugger of your choice, and it should perform exactly as it would have performed had it been launched by the actual web server.
Important: Make sure you specify the full path, as the the current working directory of a CGI script may not be what you think it is.
Even More Important: If you call getenv() yourself in your code, instead of using the provided cgic copies of the CGI environment variables, you will not get the values you expect when running with a saved CGI environment. Always use the cgic variables instead of calling getenv().
The provided program 'capture.c' can be used to capture CGI environments. Just change the first line of the cgiMain() function of capture.c to save the CGI environment to a filename appropriate on your system and type 'make capture'. Then place capture in your cgi directory and set the form action or other link you want to test to point to it. When the form submission or other link takes place, capture will write the CGI environment active at that time to the filename you specified in the source. The cgiReadEnvironment() function can then be invoked on the same filename at the beginning of the cgiMain() function of the application you want to test in order to restore the captured environment. You can then execute your program in the debugger of your choice, and it should perform exactly as it would have performed had it been launched by the actual web server.
Important: Make sure you specify the full path, as the the current working directory of a CGI script may not be what you think it is.
Even More Important: If you call getenv() yourself in your code, instead of using the provided cgic copies of the CGI environment variables, you will not get the values you expect when running with a saved CGI environment. Always use the cgic variables instead of calling getenv().