The CGI-LIB Library

An ANSI C Library for CGI Programming

by

Noel V Aguilar

What is CGI-LIB?
- Description
- Files included in this package
Obtaining CGI-LIB
Installation
Using CGI-LIB
Functions
- cgi-lib.h
- html-lib.h
Example Programs
Miscellaneous

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.

Files Included in this Package

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.

Obtaining CGI-LIB

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:

unzip <filename.zip>

TAR Format

To uncompress files with a gz extension:

gunzip <filename.tar.gz>
tar -xvf <filename.tar>

Installation

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.

Using CGI-LIB

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;

Functions

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.

cgi-lib.h

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.

html-lib.h

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.

Example Programs

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)

Miscellaneous

Release Notes

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

What's New in Release 1.4

Fixed compililation errors with the Borland BCC32 Compiler.

What's New in Release 1.3

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.

What's New in Release 1.2

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.

Additional HTML functionality
File Upload Capability
Support for Creating Cookies
Support for Reading Cookies
Support for Encoding data (ie: urlencode)

For Comments and Reporting Bugs

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.

Credits

Thank you for supporting public domain software.