Ubuntu Manpage: cgiparse - CGI parameter parsing utility

NAME

       cgiparse - CGI parameter parsing utility

SYNOPSIS

       cgiparse [mode] [-enc {none | url | mime | dacs}] [-in filename] [-checkdup] [-d]
                [-duperror]
                [-nodups] [-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 parameters, 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 parameters found in the QUERY_STRING environment variable with
       parameters found in the message body it reads from the standard input.  RFC 3875[2] states
       (S4.1.7) that the query string value is case-sensitive.

       Duplicate parameter names are allowed by default; see -nodups and -duperror, which
       override duplicate handling described below.

OPTIONS

The mode may be exactly one of the following:

-arg variable-name
Emit the value of the CGI parameter variable-name, then exit. If there is no such
parameter, the exit status will be 1 instead of 0. If more than one instance of
variable-name is present, only one will be considered.

-checkdup
Check if any parameter name occurs more than once, then terminate. If a duplicate is
found, the exit status will be 1, otherwise 0.

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

-html
Emit an HTML document that lists the CGI parameter names and their values. All
instances of duplicate parameter names are output.

-one
Emit a listing of the CGI parameter values (without the names). All parameter values
are output, including those associated with duplicate parameter names.

-sh
--shell
Emit CGI parameters 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
parameters as shell variables. All parameters are output, including duplicates, in
which case a variable will be assigned the value from the parameter instance that
happens to appear last in the list.

-text
Like -html except emit text. This is the default. In 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 parameters, or cgiparse can be run with the -in flag to
retrieve a parameter. All instances of duplicate parameter names are output.

--version
Print version information to stderr and exit.

Additionally, cgiparse recognizes these options and modifiers:

If writing the parsed CGI parameters (-text), encode the parameter value using the
specified method:

url
Selects URL encoding.

mime
Selects MIME base-64 encoding.

dacs
Selects DACS base-64 encoding.

none
Indicates that no encoding is performed (use this only when you are sure this
cannot cause a problem).

For details about these encodings, please see dacs.exprs(5)[3]. The default is none.
If reading the parsed CGI parameters (-in), decode the parameter values using the
specified method. The default is none, which means that no decoding is performed; if
the parameters 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 a parameter value.

-nodups
If a duplicate parameter name is read, all but one (arbitrary) instance will be
discarded.

-duperror
If a duplicate parameter name is read, processing terminates immediately.

-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 parameters, read variable name/value pairs (in the format
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:

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

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

• 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 parameters:

           #! /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.

       The manner in which duplicate CGI parameters is handled is not standardized and
       context-specific.  cgiparse could do a little better in this respect.

AUTHOR

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

COPYING

       Copyright2003-2014 Distributed Systems Software. See the LICENSE[9] 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. RFC 3875
           http://www.rfc-editor.org/rfc/rfc3875.txt

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

        4. RFC 3986
           http://www.rfc-editor.org/rfc/rfc3986.txt

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

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

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

        8. www.dss.ca
           http://www.dss.ca

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