Using Un-CGI from C: an example

Step 1: Compile uncgi.c.

Compile it by hand to create a .o file, defining a macro LIBRARY on the command line (or, if necessary, by editing uncgi.c.) See your compiler's documentation to find out how to compile to an object file. This usually works:

cc -DLIBRARY -c uncgi.c

Step 2: Call uncgi() from your C program.

This is usually done right at the beginning of your program, the first thing in main() before anything else is done. See the example code below.

Step 3: Use environment variables to read the form results.

The getenv() library function is used to read an environment variable. You can find more documentation on it by reading the manual page (type man getenv to see the manual page.) The environment variables are called exactly the same thing they are when Un-CGI invokes a script for you.

Note that getenv() can return NULL if an environment variable isn't defined. It's good programming practice to always check getenv()'s return value to see if an error occurred. If a variable you expect to be defined isn't, it usually means that a user tried to invoke your program without going through your form, or there's a typo in your form or the variable name in your getenv() call.

Here's a small example program, that spits some numbers out at a user. If you don't understand what this is doing, please consult a programmer at your site; I'm not interested in teaching you how to use C. The example is called with a very simple form:

<form method=GET action="/cgi-bin/myprog">
How many numbers?
<input type=text size=4 name="count">
<input type=submit value=" Submit ">
</form>

And here's the program.

#include <stdio.h>
char *getenv();

main()
{
	char	*count_raw;
	int	count;

	/* Decode the form results. */
	uncgi();

	/* Always print a content type and a blank line. */
	printf("Content-type: text/html\n\n");

	/* Get the form value, which will be a string. */
	count_raw = getenv("WWW_count");
	if (count_raw == NULL)
	{
		printf("<h1>Type something!</h1>\n");
		exit(1);
	}

	/* Convert the form value to an integer. */
	count = atoi(count_raw);
	if (count == 0)
	{
		printf("<h1>Enter a number, 1 or higher</h1>\n");
		exit(1);
	}

	/* Now print some numbers. */
	while (count--)
		printf("%d<br>\n", count);

	printf("That's all!\n");
}

Step 4: Link your program with uncgi.o.

In this example we'll assume your program is in a file called "myprog.c". Once you've compiled your program, you can link it with the uncgi.o you created in step 1. You'll generally want to compile your program to a .o file as well, especially if it's split among multiple C source files. When you've done that, compiling your program is as simple as:

cc -o myprog myprog.o uncgi.o

If your program is in a single source file, you may prefer to compile it directly without generating a .o file:

cc -o myprog myprog.c uncgi.o

The two commands shown will work on most compilers; consult your system's compiler documentation for more details.

Step 5: Install in your HTTP server's cgi-bin directory.

Since your program isn't being run by Un-CGI, it needs to go in the server's script directory. You will usually need to have access to the superuser account ("root") to do this. On some systems, users can put CGI programs in their home directories. Please consult your system administrator if you want to do so. Do not ask me about it -- I don't have any control over your system configuration, and frankly I have better things to do than help you talk to your system administrator.

Step 6: Write a form to call your program.

This will often come before step 1 -- but regardless, you'll need a form that calls your program with the appropriate fields. This step is completely up to you.

That's all there is to it!

To the Un-CGI home page