CGI-POSTIN(1)

NAME
cgi-postin - World-Wide Web CGI form data processor.

SYNTAX
cgi-postin [ -pTt ] [ -v name ]

DESCRIPTION
The cgi-postin utility processes data generated from a World-Wide Web form. It is a standalone processor that may be run easily from sh, perl, or tcl scripts.

By default, cgi-postin retrieves the form data and emits a short sh(1) script. If this script is evaluated, the shell will create a set of variables, one per form element. The variables will be named after the form element names, and they will be initialized to the associated form element values.

If, for instance, a simple form has two fields called ``name'' and ``address'', cgi-postin will emit the sh(1) commands to create variables called ``name'' and ``address'', and each variable will be initialized to the value given in the form. This can be done by simply saying:
	eval "`cgi-postin`" || exit 1

If an error occurs, cgi-postin emits a complete HTTP document (including a ``Content-type:'' header), and terminates with a non-zero exit status.

The following options are supported.

-p  The variable assignments will use perl(1) syntax. Recommended usage is something similar to:
    	eval `cgi-postin -p`;
    	exit 1 if $? != 0;

-T  The variable assignments will use tcl(1) syntax. Recommended usage is something similar to:
    	eval [exec cgi-postin -T]

-t  Selects ``terse diagnostics'' mode. When an error occurs, a typical Unix error message is emitted rather than an HTTP document.

-v name
    This option almost always should be specified. It is an option only for historical reasons. It is explained below.

The -v option affects how the variables are named. By default, its name argument is used as a prefix on all of the sh(1) variable names.

This is avoids a serious security problem. Without the prefix, hacked form data could manipulate arbitrary shell environment parameters. (Actually, cgi-postin has some built-in checks to prevent this. Still, always use this option to constrain the namespace that can be scribbled upon.)

When -p (perl mode) or -T (Tcl mode) are specified, then the -t option creates an associative array rather than individual (scaler) variables for each form element. The array has the specified name, and the data are stored one form element per array element.

The following table illustrates how this naming scheme works. It shows the variable name that would be associated with a form element called ``query'' for all the various command line invocations.

command | variable name
cgi-postin | $query
cgi-postin -v CGI | $CGI_query
cgi-postin -p | $query
cgi-postin -p -v CGI | $CGI{'query'}
cgi-postin -T | $query
cgi-postin -T -v CGI | $CGI(query)

SECURITY CONSIDERATIONS
It is dangerous to blindly run a sh(1) ``eval'' command on data provided by the client. This utility takes several precautions to mitigate the danger, and will abort with an error when problems are encountered. The following requirements are enforced:

•   Form element names must be composed of ``safe'' characters (letters, numbers, and underscores).

•   Form element values are quoted to inhibit all side effects in the assignment statement.

•   There are some simple consistency checks on the CGI data stream.

SEE ALSO
gn(8), wn(8), httpd(8)

BUGS
For historical reasons, the -v option is incredibly awkward. In some future release, the behavior when -v is not specified likely will change.

Each form element must have a unique name. Be careful of conflicts, particularly when using ``<INPUT TYPE=checkbox>''.

AUTHOR
Chip Rosenthal
Unicom Systems Development
<chip@unicom.com>
http://www.unicom.com/