![](http://www.gnu-darwin.org/hexley-gd-sm.png)
|
The CGI-LIB Library
An ANSI C Library for CGI Programming
by
Noel V Aguilar
Table of Contents
CGI-LIB is a free ANSI C library that will facilitate the creation of CGI programs.
The library is written entirely in C using ANSI C functions. The functions are easy to use and
the source code is included.
This package contains several files. Below is a list of all these files with a brief description
of their purpose.
- makefile: File used to build the library.
- cgi-lib.h: A header file that contains the function declarations that will be used in
building a cgi program.
- html-lib.h: A header file that contains the function declarations that will be used in
buildiing the html part of a cgi program.
- html-priv.h: A private header file used by CGI-LIB
- lib-list.h: A header file that will help with the creation and maintenance of the linked list use
by CGI-LIB.
- cgi-lib.c: The functions that will assist in the creation and manipulation of CGI Data are here.
- html-lib.c: The functions that will assist in the creation of the html CGI routines are in this file
- list-lib.c: The functions that will create and maintain teh linked list are located in this file.
- cgi-lib.html: This documentation in an html format.
You may obtain the CGI-LIB library by clicking on any of the two links located below, all the source
code is included along with the makefile to compile the program.
ZIP Format
To unzip the file you:
TAR Format
To uncompress files with a gz extension:
- gunzip <filename.tar.gz>
- tar -xvf <filename.tar>
The library needs to be compiled, a makefile is included in the distribution. Please modify
the makefile accordingly and run make. The final output will be an archive file.
You may install the compiled archive file in your lib subdirectory and the corresponding header
files in your include subdirecory, or you may place in a directory and call them from there when
building your CGI program.
Once you have your archive file you may delete the rest of the files except the archive file,
cgi-lib.h, html-lib.h and list-lib.h.
In order to use the library all you will need is the archive file and to include the cgi-lib.h and
the html-lib.h file in your cgi program. As mentioned earlier, the html-lib.h file contains functions
that will help you in writing html. If you do not wish to use these functions you do not need to include
this header file in your program. You will need to include the cgi-lib.h file in order to make use of the
cgi data manipulation functions. You can find an example program below.
One of the important things that you must also do is to declare a variable of type pointer to LIST
in order to maintian track of the linked list the CGI-LIB library will create. ie: LIST *head;
The CGI-LIB library has a variety of functions that will assist you in generating html and
manipulating CGI data. The cgi-lib.h file has the declarations of the functions that can be used
to help create and manipulate CGI data, and the html-lib.h file has the declarations of the functions
that will help you generate html.
The following Environment Variables are declared and can be used:
- GATEWAY_INTERFACE
- SERVER_PROTOCOL
- PATH_INFO
- PATH_TRANSLATED
- QUERY_STRING
- CONTENT_TYPE
- CONTENT_LENGTH
- REQUEST_METHOD
- SERVER_SOFTWARE
- SERVER_NAME
- SERVER_ADMIN
- SERVER_PORT
- SCRIPT_NAME
- DOCUMENT_ROOT
- REMOTE_HOST
- REMOTE_ADDR
- REMOTE_USER
- REMOTE_GROUP
- AUTH_TYPE
- REMOTE_IDENT
- HTTP_ACCEPT
- HTTP_COOKIE
- HTTP_ACCEPT_LANGUAGE
- HTTP_REFERER
- HTTP_USER_AGENT
The following functions can be used to manipulate CGI data. When I refer to a True value
I am referring to a non-zero value (in the case of CGI-LIB: 1), and when I refer to a False
value, I am referring to zero value.
- int is_form_empty();
- The is_form_empty() function will return a True if the form is empty and no data exist, or it
will return False. This sub can be used to test to see if the form is empty so we don't waste time
by calling cgi_input_parse().
- void cgi_env(void);
- The cgi_env() function will print out the current environment variables mentioned above. They
are being sent out in a Definition List format and without any mime_types or other HTML tags.
- void cgi_err(char *msg1, char *msg2);
- The cgi_err() function will compose an error message for the application to display to the user. It
sends the proper mime types to the server when used and it terminates the CGI program. The *msg1 variable
is the text that will go between H1 tags and the *msg2 variable is the text that will go between H2 tags.
When this function is called, the text contained in *msg2 will also be sent to stderr.
- LIST *cgi_input_parse(void);
- The cgi_input_parse() function should be one of the first functions called in the CGI program. This
function will take the raw data passed from the browser to the server and converts it to an understandable
manner while adding it to a linked list which the user will be able to manipulate through the use
of different functions. The current methods supported are the GET and POST and method.
- This function should be initialized at the beginning of the calling program, in order to get
the data into the linked list and be able to use it. The value returned by the function will be
a pointer to the beginning of the list or a NULL if the list was not created (possible because there
was no data to add). The user needs only to create a pointer variable of type LIST and have the
function assign its value to this pointer variable.
- void list_print(LIST *head);
- This function will print out the key/value paris in the linked list. The data is formatted in
a Definition List format without any headers beign printed out. The LIST pointer variable is the
data that needs to be passed.
- void list_clear(LIST *head);
- The list_clear() function will clear the linked list and free up the memory. The LIST pointer
variable is the data that needs to be passed.
- long list_count(LIST *head);
- The list_count() function will return the number of items that exist in the linked list. The LIST
pointer variable is the data that needs to be passed.
- int list_delete_entry(LIST *head, char *key, char *value);
- The list_delete_entry() function will delete the specified entry in the list, if NULL is supplied
for the value then the first key found will be deleted, if NULL is supplied for the key then the first
matching value will be deleted, if the both the key and value are supplied then the key and value must
match in order for the node entry to be deleted. A false value will be returned if the deletion was
not successful and a non-zero value will be returned if it was successful. The LIST pointer variable,
as well as a key and value is the data that needs to be passed.
- int list_delete_key_multi(LIST *head, char *key);
- The list_delete_key_multi() function will delete the list of specified entries based on the key
passed. This function should be used when multiple entries with one named key exist. A False will
be returned if the deletion was not successful, and a True will be returned if it was successful at
deleting all the items, assuming any were found. The LIST pointer variable and a key is the data that
needs to be passed.
- int list_delete_val_multi(LIST *head, char *value);
- The list_delete_val_multi() function will delete the list of specified entries based on the value
passed. This function should be used when multiple entries with one named value exist. A False will
be returned if the deletion was not successful, and a True will be returned if it was successful at
deleting all the items, assuming any were found. The LIST pointer variable and a value is the data that
needs to be passed.
- char *find_val(LIST *head, char *key);
- The find_val() function will search the linked list and return the value string in the first node
that it finds that matches the specified key. If none are found then NULL will be returned. The LIST
pointer variable and a key is the data that needs to be passed.
- char *find_key(LIST *head, char *value);
- The find_key() function will search the linked list and return the key string in the first node
that it finds that matches the specified value. If none are found the NULL will be returned. The LIST
pointer variable and a value is the data that needs to be passed.
- long find_val_multi(LIST *head, char *key, char ***Vals);
- The find_val_multi() function will search the linked list and build a list of value strings that were
found that matched the specified key. The value returned will be the number of items found, if the return
value is 0 then no items were found, if the value is greater than 0 then items were found and the strings
are contained in ***Vals, this variable is one that is declared by the user of type "char **Vals"
and when it is being passed to the function it should be passed as "&Vals". So this function
takes three parameters, the LIST pointer variable, the key to search for, and a pointer to a pointer variable
of type char that will hold the data found.
- long find_key_multi(LIST *head, char *value, char ***Vals);
- The find_key_multi() function will search the linked list and build a list of key strings that were
found that matched the specified value. The value returned will be the number of items found, if the return
value is 0 then no items were found, if the value is greater than 0 then items were found and the strings
are contained in ***Vals, this variable is one that is declared by the user of type "char **Vals"
and when it is being passed to the function it should be passed as "&Vals". So this function
takes three parameters, the LIST pointer variable, the value to search for, and a pointer to a pointer variable
of type char that will hold the data found.
- void mime_header(char *mime)
- The mime_header() function will receive as a parameter the mime type that
should be sent out to the server. ie: text/html
- void html_begin(char *title, char *attributes);
- The html_begin() function will diplay the top part of an html page, meaning
everything in the HEAD tags. The title parameter is the title to be displayed between the TITLE tags
and the attributes parameter is being used to display embedded text in the BODY tag. Such as what the
background color should be or a gif to display as the background graphic. If you do not want a title or
have attributes to display then NULL should be passed for the specified parameter.
- void h1(char *str);
- The h1() function will displayed the text passed to it between the H1 tags.
- void h2(char *str);
- The h2() function will displayed the text passed to it between the H2 tags.
- void h3(char *str);
- The h3() function will displayed the text passed to it between the H3 tags.
- void h4(char *str);
- The h4() function will displayed the text passed to it between the H4 tags.
- void h5(char *str);
- The h5() function will displayed the text passed to it between the H5 tags.
- void h6(char *str);
- The h6() function will displayed the text passed to it between the H6 tags.
- void hidden(char *name, char *value);
- The hidden() function will receive two values as parameters, the name of the hidden field and
the value that should go along with the name, it will write out this hidden field with the corresponding
tags.
- void html_end(void);
- The html_end() function will not receive any parameters, all this function will do is
to close the bottom of the html page with the proper closing BODY and HTML tags.
- void location(char *loc);
- The location() function will receive a URL as a parameter, and it will redirect the browser
to the specified location.
Below is a sample program using some of the functions described above. Please look at the
program code in order to get a better understanding, the code is documented.
#include <stdio.h>
#include "cgi-lib.h" /* include the cgi-lib.h header file */
#include "html-lib.h" /* include the html-lib.h header file */
int main()
{
/* need to declare a pointer variable of type LIST to keep track of our list */
LIST *head;
/* need to call this function at the beginning to initiate and setup out list */
head = cgi_input_parse();
/* send the mime header to the server using our function in html-lib */
mime_header("text/html");
/* send the top of our html page to the server */
html_begin("CGI Sample Application",NULL);
/* send the text enclosed in the heading tags */
h1("CGI Sample Application");
/* send break lines */
printf("<BR><BR>\n");
/* send the text enclosed in the heading tags */
h2("Parsed Values");
/*
we need to check if head is NULL, this will tell us if we have
any data in our linked list, if it is NULL then we don't need to
call any other CGI-LIB functions because there is nothing to do.
*/
if(head == NULL)
h3("List Empty");
else
list_print(head);
printf("<HR>\n");
/* send text enclosed in heading tags */
h2("Environment Variables");
/* print out all the environment variables */
cgi_env();
/* send the html closing tags */
html_end();
return 0;
}
Below is a sample makefile that you can use in order to compile your application
# CGI-LIB Library Sample Makefile
#
# This is a sample makefile that will help you
# include the CGI-LIB library in your cgi script.
# The CGI-LIB library must already be compiled,
# before you you use it.
# CC is the variable that will contain your compiler
CC=gcc
CCFLAGS=-o
# CGI is the variable that contains the cgi file name
CGI=cgisamp.cgi
# CGI-LIB-ARCHIVE contains the path and name of CGI-LIB
CGI-LIB-ARCHIVE=cgi-lib.a
# CGI-LIB-HEADERS contains the path and names of your header files
CGI-LIB-HEADERS=html-lib.h cgi-lib.h list-lib.h
all:$(CGI)
$(CGI): cgisamp.c $(CGI-LIB-HEADERS)
$(CC) $(CCFLAGS) $@ cgisamp.c $(CGI-LIB-ARCHIVE)
CGI-LIB has been compiled and tested on unix (HP-UX and Linux) using the GNU compiler, and it
has also been compiled and tested on Windows NT 4.0 using Visual C++ 4.2, 5.0, and 6.0.
For Updates please check http://www.geocities.com/SiliconValley/Vista/6493/projects/cgi-lib.html
- Fixed compililation errors with the Borland BCC32 Compiler.
- Fixed another bug in the Compare function that is used to insert items into the linked list.
used to maintain the key/pair values. Thanks to Mark J. and Eric H. for this report.
- Fixed a bug in the is_form_empty() function. On some systems a the application
cgi library would cause the application to crash when testing from the command line and not
having the the environment variables set. Thanks to Oscar F. for this report.
- Fixed a bug in the Compare() function that is used to insert items into the linked list
used to maintain the key/pair values. The bug might not insert a value into the linked
list if the strcmp() result was not -1,0, 1. It was due to my misunderstanding of the
result of the strcmp() function. This problem has been fixed. Thanks to Euge for this
bug report.
- Fixed a bug in the cgi_input_parse() function that will cause a core dump on some systems
if you test a CGI that uses the library from the command line without first setting the
CGI environment variables. Mainly REQUEST_METHOD. Thanks to Bill F. for this bug report.
- Fixed a bug in the list_delete_entry() function that would not allow it to compile because
certain compilers do not allow non-constant initializers. Thanks to Georg and Marco for
this report.
- Added some return statements two a couple functions. These return statements do not affect
the function of the library. They are there so certain compilers will not issue warnings.
Fixed a bug in html_begin(), the attributes being passed for the body tag were not being displayed.
Updated documentation with a sample makefile and inform that list-lib.h should
not be deleted once the library has been created. Since it is declared in cgi-lib.h
Initial Release
- Additional HTML functionality
- File Upload Capability
- Support for Creating Cookies
- Support for Reading Cookies
- Support for Encoding data (ie: urlencode)
If you have any comments or suggestions please let me know by filling a comments form. If you
encounter a bug of any kind please fill out a comments form.
Thank you for supporting public domain software.
|