Debian 3.9.10debian/3.9.10debian

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).