Your virtual Web server has an "uncgi" script installed by default; the file is /cgi-bin/uncgi, and has been adapted from version 1.9 of the public-domain program of the same name maintained by Steven Grimm. The documentation below is largely extracted from the uncgi documentation provided with Steven's source code distribution.
The uncgi script must be used in conjunction with LiveZone's mycgi CGI-wrapper program, which is described in the LiveZone SupportZone pages.
The uncgi script documentation is outlined below:
This is uncgi, a frontend for processing queries and forms from the Web on UNIX systems.
Without this program, if you wanted to process a form, you'd have to either write or dig up routines to translate the values of the form's fields from "URL encoding" to whatever your program required. This was a hassle in C, and a real pain in the shell, and you had do things differently for GET and POST queries.
Which is where uncgi comes in. It decodes all the form fields and sticks them into environment variables for easy perusal by a shell script, a C program, a Perl script, or whatever you like, then executes whatever other program you specify. (Actually, "uncgi" is something of a misnomer, as the weird URL syntax is from the HTML forms specification, not from CGI itself.)
Un-CGI will look for your programs in your Web site's /uncgi-bin directory. You can also put your programs in subdirectories of /uncgi-bin if you like.
Make sure the file permissions on Un-CGI (and the directory it's in) are set so the HTTP server can execute it. On LiveZone systems the HTTP server runs as the same username and in the same directory tree you use for FTP access to your Web site.
An example is the easiest way to demonstrate uncgi's use. Suppose you have the following in an HTML file:
<form method=POST action="/cgi-bin/mycgi/uncgi/myscript">
What's your name?
<input type=text size=30 name=name>
<p>
Type some comments.
<br>
<textarea name=_comments rows=10 cols=60></textarea>
What problem are you having? <select name=problem multiple>
<option> Sleeplessness
<option> Unruly goat
<option> Limousine overcrowding
</select>
<p>
<input type=submit value=" Send 'em in! ">
</form>
When the user selects the "Send 'em in!" button, the HTTP server will run uncgi. Uncgi will set three environment variables, WWW_name, WWW_comments and WWW_problem, to the values of the "name", "comments", and "problem" fields in the form, respectively. Then it will execute myscript in the /mycgi-bin directory.
All the usual CGI environment variables (PATH_INFO, QUERY_STRING, etc.) are available to the script or program you tell uncgi to run. A couple of them (PATH_INFO and PATH_TRANSLATED) are tweaked by uncgi to the values they'd have if your program were being executed directly by the server. PATH_INFO is, in case you haven't read up on CGI, set to all the path elements after the script name in your URL, if any. This is an easy way to specify additional parameters to your script without resorting to hidden fields.
Myscript might be as simple as this:
#!/bin/sh
echo 'Content-type: text/html'
echo ''
cat /my/home/directory/htmlfiles/thanks.html
(
echo "$WWW_name is having $WWW_problem problems and said:"
echo "$WWW_comments"
) | mail webmaster@domain.com
With uncgi, that's all you need to do to write a script to send you mail from a form and print a prewritten file as a response. And it's the same whether you want to use GET or POST queries.
If you're using Perl, $ENV{"WWW_xyz"} will look up the value of the "xyz" form field.
If more than one "problem" is selected in the example above, the values will all be placed in WWW_comments, separated by hash marks ('#'). You can use the library function strtok() to separate the values in a C program; in a shell script, your best bet is probably to replace the hash marks with newlines using "tr", something like:
echo $WWW_problem | tr '#' \\012 | while read value; do
echo $value 'selected.'
done
A useful debugging tool is to point your form at a script that just prints the contents of the environment. On most systems there is a program to do that, called either env or printenv; you can write a little script that runs it:
#!/bin/sh
echo 'Content-type: text/plain'
echo ''
env
That'll show you exactly what your script can expect from a form.
Eagle-eyed readers noticed that the text area in the above example had an underscore ("_") at the beginning of its name. When Un-CGI sees a form field whose name begins with an underscore, it strips whitespace from the beginning and end of the value and makes sure that all end-of-line characters in the value are UNIX-style newlines (as opposed to DOS-style CR-LF pairs, or Macintosh-style CRs, both of which are sent by some browsers.) This makes processing text easier, since your program doesn't have to worry about the browser's end-of-line conventions. Note that if a form field is named _xyz, you still get an environment variable called WWW_xyz (i.e., the extra underscore doesn't show up in the environment variable name.)
Un-CGI also modifies variable names containing periods, the major source of which is <input type=image>. Shell scripts have trouble coping with periods in environment variable names, so Un-CGI converts periods to underscores. This is only done to variable _names_ and periods in values will remain untouched.
Uncgi will handle hybrid GET/POST requests. Specify a method of POST
in the form, and add a GET-style query string to the action, for example:
<form method=POST action="/cgi-bin/uncgi/myscript?form_id=feedback">
When your script is run, WWW_form_id will be set to "feedback".
This will only work if your HTTP server supports it (NCSA's does, for now
anyway.)
See the NCSA documentation on forms. It includes several examples.
First, make sure your script is in your /uncgi-bin directory; see the preceding section.
Second, make sure your script can be executed by the server. Remember, Un-CGI is run by the server, which is using your username. You need to set the permissions on your script such that it can be run by any user. Usually, you can say "chmod 755 scriptname" (replacing scriptname with the name of your script) to set the permissions properly. More details can also be found in the discussion of the LiveZone mycgi CGI wrapper program, which can also provide additional debugging information at execution time.
The <form> tag has two attributes, METHOD and ACTION. METHOD must be set to either GET or POST; uncgi will handle either one, but POST is preferred if you have textarea fields or are expecting a lot of information from the client. Note that the attribute name (METHOD) can be upper or lower case, but the value must be all caps.
So, if you wanted to tell uncgi to run sendmemail with no additional parameters, you'd put sendmemail in the directory you specified as the value of CGI_BIN in uncgi's makefile, and use the following tag to begin your form:
<form method=POST action="/cgi-bin/mycgi/uncgi/sendmemail">
The usual cause of this is that your server requires a special filename extension on CGI programs. (Most often it's ".cgi".) You need to give uncgi a name that will identify it as a CGI program to the Web server. There is nothing special about uncgi from the Web server's point of view; it's just another program that gets run like any other, and your installation of it has to obey the same rules as other programs'.
This usually means your script isn't specifying a content type to the
server. The first thing your script needs to output is:
Content-type: text/html
followed by a blank line. Note that the blank line is not optional,
and it has to be completely empty -- no whitespace. If you're writing a
shell script, for instance, you'll need:
echo "Content-type: text/html"
echo ""
The empty quotes on the second line are necessary; otherwise echo won't print anything, not even a blank line. (Of course, if your script is outputting something other than HTML, adjust the content type accordingly.)
Another cause of this is passing in form fields whose names contain special characters that confuse the shell you're using, if any. Some shells (notably /bin/sh) won't allow you to have certain characters in environment variable names, and will often refuse to run a script if they're present. If you stick to alphanumeric characters in your form's field names, you should be safe.
If your HTTP server outputs CGI scripts' standard error streams to a logfile (often called "error_log") you should look there to see if your script, or its shell, is outputting any diagnostic information.
There are a few common causes for this:
The most common cause of hangs like that is trying to convert an old CGI-compliant program or script to run under Un-CGI. Your script is detecting that the form was submitted with the POST method, and is trying to read form results from the browser. Unfortunately, by the time your script is run, Un-CGI has already read the results, so your program sits there waiting forever for bytes that've already been consumed.
Remove the part of your code that reads a query from the standardinput -- it'll generally be located somewhere around the word "POST", which is easy to search for -- and replace it with code that fills your program's internal variables via getenv() calls (assuming your program is in C) on the WWW_ variables defined by Un-CGI.
How do I parse checkbox results?
Un-CGI puts hash marks ("#") between checkbox selections if
there are several of them. How you parse that depends entirely on what language
you're using. In C, use strtok(). In Python, use string.splitfields(). In
Perl, use split(). In Bourne shell, do something like
echo $WWW_whatever | tr \# \\012 | while read result; do
echo User picked $result
done
No. You're probably assuming that since your form has an ACTION like /cgi-bin/uncgi/xyz, there must be an uncgi directory under cgi-bin. That's not how it works.
The parts of a URL between the slashes are not directory names. They are symbols to tell the server where to find a particular document. In most cases, the server will look for a directory of the same name as the symbol in question, and if there is one, go into that directory and proceed to the next symbol. But that isn't always what happens. If the server sees that a particular symbol matches the name of a program, it will typically run that program and pass the rest of the URL to the program as an argument. And that's exactly what's happening here.
There's no uncgi directory. You can think of /cgi-bin/uncgi/xyz as /cgi-bin/uncgi xyz if that helps (it's not strictly speaking accurate, but that's the concept.) Uncgi sees the "xyz" argument and looks in your /uncgi-bin directory to find a program by that name.
If you're still not sure what all this means, just try it out and see what happens!
No, for the simple reason that uncgi isn't tied to any one shell, or any shell at all, for that matter. It sits in front of C programs just as easily as Bourne shell scripts, just as easily as Perl scripts or Python scripts.
In most of those languages, there _aren't_ any special characters that'd inherently be security problems, so having uncgi strip characters that cause problems for a particular shell would just end up pointlessly mangling the input to other kinds of scripts and programs. And people using shells with different special characters would still have to specially handle them anyway.
On most UNIXes, you can use the "tr -d" command to strip out
characters your shell processes specially. For example, to strip out dollar
signs from a Bourne shell variable, you'd do:
WWW_puppycount="`echo $WWW_puppy | tr -d \$`"
 www.livezone.com |
Last Updated January 2007 |