'\" t
'\"macro stdmacro
.\"
.\" Copyright (c) 2014 Red Hat.
.\" 
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMGETOPT 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmgetopt\f1 \- Performance Co-Pilot shell script option parser
.SH SYNOPSIS
\f3$PCP_BINADM_DIR/pmgetopt\f1
[\f3\-c\f1|\f3\-\-config\f1 \f2file\f1]
[\f3\-p\f1|\f3\-\-progname\f1 \f2name\f1]
[\f3\-u\f1|\f3\-\-usage\f1]
[\f3\-\-\f1]
[\f2parameters\f1]
.SH DESCRIPTION
.de EX
.in +0.5i
.ie t .ft CB
.el .ft B
.ie t .sp .5v
.el .sp
.ta \\w' 'u*8
.nf
..
.de EE
.fi
.ie t .sp .5v
.el .sp
.ft R
.in
..
.B pmgetopt
is used to perform command line option parsing for shell scripts
used in the Performance Co-Pilot (PCP toolkit).
It is also used to generate usage messages for those scripts.
.PP
The parameters given to
.B pmgetopt
take two forms: initially, options specific to
.B pmgetopt
itself are passed in, and terminated using the \-\- mechanism.
Thereafter, all of the parameters passed into the shell script
should be passed (usually this is simply the "$@" variable).
.PP
The options specific to
.B pmgetopt
are as follows:
.TP 5
.BR \-c , \-\-config
A configuration
.I file
in the format described below is passed to
.B pmconfig 
using this option.
If this option is omitted, then
.B pmconfig 
will read its configuration from the standard input stream.
.TP
.BR \-p , \-\-progname
When parsing the calling shell scripts parameters, error and usage
messages will contain the given program
.I name
rather than referring to
.B pmgetopt
itself as the source of the error.
.TP
.BR \-u , \-\-usage
A usage message appropriate for the calling shell script to
present as its own can be generated using the
option.
.PP
.B pmgetopt
parses the given parameters, and produces output in a format
suitable for sourcing in the calling shell script.
When both short and long forms of an argument are allowed by
the specification,
.B pmgetopt
will always indicate the short form for simpler shell processing.
If arguments are presented that do not match the configuration,
a request for a usage message (\-?) will be generated for the
calling script to respond to.
Any non-option parameters will be echoed back to the calling
script preceded by the double-hyphen delimiter.  Thus a script
should stop handling options when this delimiter is detected,
and begin the handling of any non-option arguments.
.PP
Unlike with the shell built-in
.I getopt
command, variables like $OPTARG are
not set and the calling script will typically employ use of the
shell built-in
.IR eval ,
.I set
and positional
.I shift
commands to ensure option processing occurs correctly.
.SH CONFIGURATION
The configuration format used by
.B pmgetopt
is intended to closely reflect the usage message which would be
generated in the presence of invalid arguments (or the 
.BR \-? , \-\-help
option).
.PP
There are primarily two types of configuration line \- commands
and options.
Commands allow metadata to be passed into the option processing
process, and options are the allowable command line options that
the shell script will accept.
Command lines are preceded by the hash character, whereas option
lines will always begin with a hyphen (either single or double).
Any other line in the configuration, which may include usage headers
or descriptive text, has no impact on the option parsing and will be
copied unmodified into the usage message.
.PP
The set of commands is:
.I getopt
(provide short-argument option specification manually,
if not present this will be generated from the options presented),
.I usage
(provide short one-line summary used at the head of the
usage message, which will be prefixed by the
.I progname
before reporting), and
.I end
which informs
.B pmgetopt
to stop processing further commands and options \- any subsequent
text encountered will be simply appended to the usage message.
.PP
A short-hand notation exists for each of the standard PCP options,
as described in
.BR PCPIntro (1).
If any of these options (e.g \f3\-\-host\f1) appears as a single word on
any line, it will be transformed into the appropriate option for the
shell script, including all metadata about that option (whether it
accepts an argument, both short and long option forms, and so on).
.PP
Use of the equals symbol ("=") indicates the presence of a required
argument to any option, for both short and long forms.
Any non-standard option must be accompanied by a non-empty description
of that argument.
.SH EXAMPLES
As an example, the following is a valid configuration:
.EX
# Usage: [options] node...

Options:
    \-\-archive
    \-d, \-\-delay            pause between updates for archive replay
    \-\-host
    \-\-interval
    \-i=INST, \-\-insts=INST  comma-separated metrics instance list
    \-r                     output raw counters (no rate conversion)
    \-\-width=N              set the width of each column of output
    \-\-timezone
    \-\-help
.EE
.PP
This configuration will produce the following usage message,
when run as shown.
.EX
$ pmgetopt \-\-usage \-\-progname=clusterstat \-\- "$@"
Usage: clusterstat [options] node...

Options:
  \-a FILE, \-\-archive=FILE
                        metrics source is a PCP log archive
  \-d, \-\-delay           pause between updates for archive replay
  \-h HOST, \-\-host=HOST  metrics source is PMCD on host
  \-t DELTA, \-\-interval=DELTA
                        sampling interval
  \-i INST, \-\-insts=INST comma-separated metrics instance list
  \-r                    output raw counters (no rate conversion)
  \-\-width=N             set the width of each column of output
  \-Z TZ, \-\-timezone=TZ  set reporting timezone
  \-?, \-\-help            show this usage message and exit
.EE
.PP
Several examples of
.B pmgetopt
use form part of the PCP toolkit, in particular the
.BR pcp (1)
and
.BR pmlogmv (1)
scripts provide good reference examples.
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
.SH SEE ALSO
.BR pcp (1),
.BR pmlogmv (1),
.BR pmgetopt_r (3),
.BR pcp.conf (5)
and
.BR pcp.env (5).