.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: cgiparse
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "CGIPARSE" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
cgiparse \- CGI parameter parsing utility
.SH "SYNOPSIS"
.HP \w'\fBcgiparse\fR\ 'u
\fBcgiparse\fR [\fImode\fR] [\fB\-enc\fR\ {none\ |\ url\ |\ mime\ |\ dacs}] [\fB\-in\fR\ \fIfilename\fR] [\fB\-checkdup\fR] [\fB\-d\fR] [\fB\-duperror\fR]
.br
[\fB\-nodups\fR] [\fB\-nonewline\fR] [\fB\-qs\fR\ \fIquery\-string\fR] [\fB\-copy\fR\ \fIfilename\fR] [[\fB\-n\fR\ \fIname\fR\ \fIfilename\fR]...]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&. It is a stand\-alone program that neither accepts the usual
\fBDACS\fR
command line options (\fIdacsoptions\fR) nor accesses any
\fBDACS\fR
configuration files\&.
.PP
This utility is used by web\-based scripts (shell scripts in particular) to obtain their
CGI
parameters, which can be obtained from a URI\*(Aqs query component or in an encoded entity\-body read from the standard input (as with the
POST
method)\&. The
\m[blue]\fBform content types\fR\m[]\&\s-2\u[1]\d\s+2
application/x\-www\-form\-urlencoded
and
multipart/form\-data
are both understood\&.
.PP
The program has several different modes of operation, one of which may be specified by the first command line argument\&.
.PP
\fBcgiparse\fR
combines query parameters found in the
\fBQUERY_STRING\fR
environment variable with parameters found in the message body it reads from the standard input\&.
\m[blue]\fBRFC 3875\fR\m[]\&\s-2\u[2]\d\s+2
states (S4\&.1\&.7) that the query string value is case\-sensitive\&.
.PP
Duplicate parameter names are allowed by default; see
\fB\-nodups\fR
and
\fB\-duperror\fR, which override duplicate handling described below\&.
.SH "OPTIONS"
.PP
The
\fImode\fR
may be exactly one of the following:
.PP
\fB\-arg\fR \fIvariable\-name\fR
.RS 4
Emit the value of the
CGI
parameter
\fIvariable\-name\fR, then exit\&. If there is no such parameter, the exit status will be
1
instead of
0\&. If more than one instance of
\fIvariable\-name\fR
is present, only one will be considered\&.
.RE
.PP
\fB\-checkdup\fR
.RS 4
Check if any parameter name occurs more than once, then terminate\&. If a duplicate is found, the exit status will be
1, otherwise
0\&.
.RE
.PP
\fB\-targ\fR \fIvariable\-name\fR
.RS 4
Test if the
CGI
parameter
\fIvariable\-name\fR
exists\&. If there is no such parameter, the exit status will be
1, otherwise it will be
0\&.
.RE
.PP
\fB\-html\fR
.RS 4
Emit an HTML document that lists the
CGI
parameter names and their values\&. All instances of duplicate parameter names are output\&.
.RE
.PP
\fB\-one\fR
.RS 4
Emit a listing of the
CGI
parameter values (without the names)\&. All parameter values are output, including those associated with duplicate parameter names\&.
.RE
.PP
\fB\-sh\fR
.br
\fB\-\-shell\fR
.RS 4
Emit
CGI
parameters as a single line in the format:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIvariable\-name\fR=\*(Aq\fIvariable\-value\fR\*(Aq; [\&.\&.\&.]
.fi
.if n \{\
.RE
.\}
.sp
It is an error if any
\fIvariable\-name\fR
or
\fIvariable\-value\fR
is syntactically unsuitable for this format\&. The returned string can be used as the argument to
\fBeval\fR
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\&.
.RE
.PP
\fB\-text\fR
.RS 4
Like
\fB\-html\fR
except emit text\&. This is the default\&. In this mode, the program\*(Aqs
stdout
is usually written to a file\&. Each line of the file has the format:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIvariable\-name\fR \fIvariable\-value\fR
.fi
.if n \{\
.RE
.\}
.sp
A space separates the name from the corresponding value\&. The file is typically read by a script to obtain the parameters, or
\fBcgiparse\fR
can be run with the
\fB\-in\fR
flag to retrieve a parameter\&. All instances of duplicate parameter names are output\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print version information to
stderr
and exit\&.
.RE
.PP
Additionally,
\fBcgiparse\fR
recognizes these options and modifiers:
.PP
.HP \w'\ 'u [\fB\-enc\fR\ {url\ |\ mime\ |\ dacs\ |\ none}]
.RS 4
If writing the parsed
CGI
parameters (\fB\-text\fR), encode the parameter value using the specified method:
.PP
url
.RS 4
Selects URL encoding\&.
.RE
.PP
mime
.RS 4
Selects
MIME
base\-64 encoding\&.
.RE
.PP
dacs
.RS 4
Selects
\fBDACS\fR
base\-64 encoding\&.
.RE
.PP
none
.RS 4
Indicates that no encoding is performed (use this only when you are sure this cannot cause a problem)\&.
.RE
.sp
For details about these encodings, please see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[3]\d\s+2\&. The default is
none\&. If reading the parsed
CGI
parameters (\fB\-in\fR), 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\&.
.RE
.PP
\fB\-qs\fR \fIquery\-string\fR
.RS 4
Instead of using the environment variable
\fIQUERY_STRING\fR
to get a query component, use
\fIquery\-string\fR\&.
.RE
.PP
\fB\-nonewline\fR
.RS 4
With
\fB\-arg\fR, do not emit a newline after printing a parameter value\&.
.RE
.PP
\fB\-nodups\fR
.RS 4
If a duplicate parameter name is read, all but one (arbitrary) instance will be discarded\&.
.RE
.PP
\fB\-duperror\fR
.RS 4
If a duplicate parameter name is read, processing terminates immediately\&.
.RE
.PP
\fB\-d\fR
.RS 4
Enable debugging output\&.
.RE
.PP
\fB\-copy\fR \fIfilename\fR
.RS 4
Append the input stream to
\fIfilename\fR\&. This can be useful for debugging purposes\&.
.RE
.PP
\fB\-in\fR \fIfilename\fR
.RS 4
Instead of parsing
CGI
parameters, read variable name/value pairs (in the format produced by the
\fB\-text\fR
flag) from
\fIfilename\fR\&. If
\fIfilename\fR
is "\-",
stdin
is read\&.
.RE
.PP
\fB\-n\fR \fIname\fR \fIfilename\fR
.RS 4
If parsing succeeds, and there is a
MIME
body part with a name exactly matching
\fIname\fR, then:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if the content disposition is
multipart/form\-data, write the content as
quoted\-printable
text to
\fIfilename\fR;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if the content disposition is
base64, write the decoded content to
\fIfilename\fR;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
otherwise the content is written verbatim to
\fIfilename\fR\&.
.RE
.sp
If the output file exists it is truncated\&.
.RE
.SH "EXAMPLES"
.PP
The following shell script demonstrates one way of using
\fBcgiparse\fR\&.
.PP
.if n \{\
.RS 4
.\}
.nf
#! /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
.fi
.if n \{\
.RE
.\}
.PP
The following code fragment uses
\fBcgiparse\fR
to save and then look up its
CGI
parameters:
.sp
.if n \{\
.RS 4
.\}
.nf
#! /bin/sh

tmpfile=/tmp/cgiparse\&.$$
trap \*(Aqrm \-f ${tmpfile}; exit 1\*(Aq 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`
.fi
.if n \{\
.RE
.\}
.PP
The following script will print "1 2 3" to its standard output:
.sp
.if n \{\
.RS 4
.\}
.nf
#! /bin/sh

args=`cgiparse \-sh \-qs "a=1&b=2&c=3"`
eval "$args"
echo "$a $b $c"
.fi
.if n \{\
.RE
.\}
.sp
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
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
\fIname\fR=\fIvalue\fR
pairs\&. The parsing routines that
\fBcgiparse\fR
uses will flag an error if they see strings containing a component like "=foo", for example, although "foo=" is fine\&.
.PP
The manner in which duplicate
CGI
parameters is handled is not standardized and context\-specific\&.
\fBcgiparse\fR
could do a little better in this respect\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBRFC 3875\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBRFC 3986\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBThe WWW Common Gateway Interface, Version 1\&.2\fR\m[]\&\s-2\u[5]\d\s+2,
\m[blue]\fBHTML 4\&.01 Specification\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[7]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[8]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2014 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[9]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
form content types
.RS 4
\%http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4
.RE
.IP " 2." 4
RFC 3875
.RS 4
\%http://www.rfc-editor.org/rfc/rfc3875.txt
.RE
.IP " 3." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#encode
.RE
.IP " 4." 4
RFC 3986
.RS 4
\%http://www.rfc-editor.org/rfc/rfc3986.txt
.RE
.IP " 5." 4
The WWW Common Gateway Interface, Version 1.2
.RS 4
\%http://ken.coar.org/cgi/cgi-120-00a.html
.RE
.IP " 6." 4
HTML 4.01 Specification
.RS 4
\%http://www.w3.org/TR/html4/
.RE
.IP " 7." 4
dacs_prenv(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_prenv.8.html
.RE
.IP " 8." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP " 9." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE