--- name: "cgiparse" section: "8" platform: "linux" package: "dacs" version: "1.4.40-2" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/cgiparse/8" --- # cgiparse(8) 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)](/dacs.exprs/5.md)**\[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. ## SEE ALSO **RFC 3875**\[2\], **RFC 3986**\[4\], **The WWW Common Gateway Interface, Version 1.2**\[5\], **HTML 4.01 Specification**\[6\], **[dacs\_prenv(8)](/dacs_prenv/8.md)**\[7\] ## AUTHOR Distributed Systems Software (**www.dss.ca**\[8\]) ## COPYING Copyright © 2003-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)](/dacs.exprs/5.md) 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)](/dacs_prenv/8.md) 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