CGIPARSE(8)						     DACS Web Services Manual						       CGIPARSE(8)

NAME

       cgiparse - CGI argument parsing utility

SYNOPSIS

       cgiparse [mode] [-enc {none | url | mime | dacs}] [-in filename] [-d] [-nonewline]
		[-qs query-string] [-copy filename] [[-n name filename]...]

DESCRIPTION

       This program is part of the DACS suite. It is a stand-alone program that neither accepts the usual DACS command line options (dacsoptions)
       nor accesses any DACS configuration files.

       This utility is used by web-based scripts (shell scripts in particular) to obtain their CGI arguments, which can be obtained from a URI's
       query component or in an encoded entity-body read from the standard input (as with the POST method). The form content types[1]
       application/x-www-form-urlencoded and multipart/form-data are both understood.

       The program has several different modes of operation, one of which may be specified by the first command line argument.

       cgiparse combines query arguments found in the QUERY_STRING environment variable with arguments found in the message body it reads from the
       standard input. If an argument name is duplicated the result is indeterminate.

OPTIONS

       The mode may be one of the following:

       -arg variable-name
	   Emit the value of the CGI argument variable-name, then exit. If there is no such argument, the exit status will be 1 instead of 0.

       -targ variable-name
	   Test if the CGI argument variable-name exists. If there is no such argument, the exit status will be 1, otherwise it will be 0.

       -html
	   Emit an HTML document that lists the CGI argument names and their values.

       -one
	   Emit a listing of the CGI argument values (without the names).

       -sh
	   Emit CGI arguments as a single line in the format:

	       variable-name='variable-value'; [...]

	   It is an error if any variable-name or variable-value is syntactically unsuitable for this format. The returned string can be used as
	   the argument to eval to set the CGI arguments as shell variables.

       -text
	   Like -html except emit text. This is the default. With this mode, the program's stdout is usually written to a file. Each line of the
	   file has the format:

	       variable-name variable-value

	   (a space separates the name from the corresponding value). The file is typically read by a script to obtain the arguments, or cgiparse
	   can be run with the -in flag to retrieve an argument.

       Additionally, cgiparse recognizes these options:

	   If writing the parsed CGI arguments (-text), encode the argument value using the specified method: url means URL encoding, mime means
	   MIME base-64 encoding, and dacs means DACS base-64 encoding. For details about these encodings, please see dacs.exprs(5)[2]. The
	   default is none, which means that no encoding is performed (use this only when you are sure this cannot cause a problem). If reading
	   the parsed CGI arguments (-in), decode the argument values using the specified method. The default is none, which means that no
	   decoding is performed; if the arguments were encoded, they will be returned in that encoding, but other than this case the decoding
	   method must match the encoding method previously used or an error is likely to occur.

       -qs query-string
	   Instead of using the environment variable QUERY_STRING to get a query component, use query-string.

       -nonewline
	   With -arg, do not emit a newline after printing an argument value.

       -d
	   Enable debugging output.

       -copy filename
	   Append the input stream to filename. This can be useful for debugging purposes.

       -in filename
	   Instead of parsing CGI arguments, read variable name/value pairs (as produced by the -text flag) from filename. If filename is "-",
	   stdin is read.

       -n name filename
	   If parsing succeeds, and there is a MIME body part with a name exactly matching name, then:

	   o   if the content disposition is multipart/form-data, write the content as quoted-printable text to filename;

	   o   if the content disposition is base64, write the decoded content to filename;

	   o   otherwise the content is written verbatim to filename.

	   If the output file exists it is truncated.

EXAMPLES

       The following shell script demonstrates one way of using cgiparse.

	   #! /bin/sh

	   tmpfile=/tmp/cgiparse.$$

	   cgiparse > ${tmpfile}
	   chmod 0600 ${tmpfile}

	   echo "Context-Type: text/plain"
	   echo ""

	   done=
	   while [ "${done}x" = x ]
	   do
	     a=
	     b=
	     read a b
	     if [ $? = 1 ]
	     then
	       done=1
	       break
	     else
	       echo "Arg: ${a}"
	       echo "Is: ${b}"
	     fi
	   done < ${tmpfile}

	   rm -f ${tmpfile}
	   exit 0

       The following code fragment uses cgiparse to save and then look up its CGI arguments:

	   #! /bin/sh

	   tmpfile=/tmp/cgiparse.$$
	   trap 'rm -f ${tmpfile}; exit 1' EXIT 1 2 3 13 15

	   cgiparse -enc mime > ${tmpfile}
	   chmod 0600 ${tmpfile}

	   mode=`cgiparse -in ${tmpfile} -enc mime -arg MODE`
	   target=`cgiparse -in ${tmpfile} -enc mime -arg TARGET`

       The following script will print "1 2 3" to its standard output:

	   #! /bin/sh

	   args=`cgiparse -sh -qs "a=1&b=2&c=3"`
	   eval "$args"
	   echo "$a $b $c"

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

BUGS

       There do not appear to be any official recommendations concerning how to handle apparently "malformed" CGI query strings that do not look
       like a sequence of name=value pairs. The parsing routines that cgiparse uses will flag an error if they see strings containing a component
       like "=foo", for example, although "foo=" is fine.

SEE ALSO

       RFC 3875[3], The WWW Common Gateway Interface, Version 1.2[4], HTML 4.01 Specification[5], dacs_prenv(8)[6]

AUTHOR

       Distributed Systems Software (www.dss.ca[7])

COPYING

       Copyright2003-2012 Distributed Systems Software. See the LICENSE[8] file that accompanies the distribution for licensing information.

NOTES

	1. form content types
	   http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4

	2. dacs.exprs(5)
	   http://dacs.dss.ca/man/dacs.exprs.5.html#encode

	3. RFC 3875
	   http://www.rfc-editor.org/rfc/rfc3875.txt

	4. The WWW Common Gateway Interface, Version 1.2
	   http://ken.coar.org/cgi/cgi-120-00a.html

	5. HTML 4.01 Specification
	   http://www.w3.org/TR/html4/

	6. dacs_prenv(8)
	   http://dacs.dss.ca/man/dacs_prenv.8.html

	7. www.dss.ca
	   http://www.dss.ca

	8. LICENSE
	   http://dacs.dss.ca/man/../misc/LICENSE

DACS 1.4.27b							    10/22/2012							       CGIPARSE(8)