diff options
Diffstat (limited to 'man/man1/pmgetopt.1')
| -rw-r--r-- | man/man1/pmgetopt.1 | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/man/man1/pmgetopt.1 b/man/man1/pmgetopt.1 new file mode 100644 index 0000000..0302861 --- /dev/null +++ b/man/man1/pmgetopt.1 @@ -0,0 +1,218 @@ +'\"! tbl | mmdoc +'\"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). |