.\" 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.78.1 <http://docbook.sf.net/>
.\"      Date: 07/17/2013
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.28b
.\"  Language: English
.\"
.TH "CGIPARSE" "8" "07/17/2013" "DACS 1.4.28b" "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 argument 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\-d\fR] [\fB\-nonewline\fR]
.br
[\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 arguments, 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+2application/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 arguments found in the
\fBQUERY_STRING\fR
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\&.
.SH "OPTIONS"
.PP
The
\fImode\fR
may be one of the following:
.PP
\fB\-arg\fR \fIvariable\-name\fR
.RS 4
Emit the value of the CGI argument
\fIvariable\-name\fR, then exit\&. If there is no such argument, the exit status will be
1
instead of
0\&.
.RE
.PP
\fB\-targ\fR \fIvariable\-name\fR
.RS 4
Test if the CGI argument
\fIvariable\-name\fR
exists\&. If there is no such argument, 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 argument names and their values\&.
.RE
.PP
\fB\-one\fR
.RS 4
Emit a listing of the CGI argument values (without the names)\&.
.RE
.PP
\fB\-sh\fR
.RS 4
Emit CGI arguments 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 arguments as shell variables\&.
.RE
.PP
\fB\-text\fR
.RS 4
Like
\fB\-html\fR
except emit text\&. This is the default\&. With 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 arguments, or
\fBcgiparse\fR
can be run with the
\fB\-in\fR
flag to retrieve an argument\&.
.RE
.PP
Additionally,
\fBcgiparse\fR
recognizes these options:
.PP
.HP \w'\ 'u [\fB\-enc\fR\ {none\ |\ url\ |\ mime\ |\ dacs}]
.RS 4
If writing the parsed CGI arguments (\fB\-text\fR), encode the argument value using the specified method:
url
means URL encoding,
mime
means MIME base\-64 encoding, and
dacs
means
\fBDACS\fR
base\-64 encoding\&. For details about these encodings, please see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[2]\d\s+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 (\fB\-in\fR), 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\&.
.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 an argument value\&.
.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 arguments, read variable name/value pairs (as 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 arguments:
.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\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBRFC 3875\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBThe WWW Common Gateway Interface, Version 1\&.2\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBHTML 4\&.01 Specification\fR\m[]\&\s-2\u[5]\d\s+2,
\m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[6]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[7]\d\s+2)
.SH "COPYING"
.PP
Copyright2003\-2012 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[8]\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
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#encode
.RE
.IP " 3." 4
RFC 3875
.RS 4
\%http://www.rfc-editor.org/rfc/rfc3875.txt
.RE
.IP " 4." 4
The WWW Common Gateway Interface, Version 1.2
.RS 4
\%http://ken.coar.org/cgi/cgi-120-00a.html
.RE
.IP " 5." 4
HTML 4.01 Specification
.RS 4
\%http://www.w3.org/TR/html4/
.RE
.IP " 6." 4
dacs_prenv(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_prenv.8.html
.RE
.IP " 7." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP " 8." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE