NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | EXAMPLES | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMGETOPT(1)                General Commands Manual               PMGETOPT(1)

NAME         top

       pmgetopt - Performance Co-Pilot shell script option parser

SYNOPSIS         top

       $PCP_BINADM_DIR/pmgetopt [-c|--config file] [-p|--progname name]
       [-u|--usage] [--] [parameters]

DESCRIPTION         top

       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.

       The parameters given to pmgetopt take two forms: initially, options
       specific to 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).

       The options specific to pmgetopt are as follows:

       -c,--config
            A configuration file in the format described below is passed to
            pmconfig using this option.  If this option is omitted, then
            pmconfig will read its configuration from the standard input
            stream.

       -p,--progname
            When parsing the calling shell scripts parameters, error and
            usage messages will contain the given program name rather than
            referring to pmgetopt itself as the source of the error.

       -u,--usage
            A usage message appropriate for the calling shell script to
            present as its own can be generated using the option.

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

       Unlike with the shell built-in getopt command, variables like $OPTARG
       are not set and the calling script will typically employ use of the
       shell built-in eval, set and positional shift commands to ensure
       option processing occurs correctly.

CONFIGURATION         top

       The configuration format used by pmgetopt is intended to closely
       reflect the usage message which would be generated in the presence of
       invalid arguments (or the -?,--help option).

       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.

       The set of commands is: getopt (provide short-argument option
       specification manually, if not present this will be generated from
       the options presented), usage (provide short one-line summary used at
       the head of the usage message, which will be prefixed by the progname
       before reporting), and end which informs pmgetopt to stop processing
       further commands and options - any subsequent text encountered will
       be simply appended to the usage message.

       A short-hand notation exists for each of the standard PCP options, as
       described in PCPIntro(1).  If any of these options (e.g --host)
       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).

       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.

EXAMPLES         top

       As an example, the following is a valid configuration:

            # 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

       This configuration will produce the following usage message, when run
       as shown.

            $ 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

       Several examples of pmgetopt use form part of the PCP toolkit, in
       particular the pcp(1) and pmlogmv(1) scripts provide good reference
       examples.

PCP ENVIRONMENT         top

       Environment variables with the prefix PCP_ are used to parameterize
       the file and directory names used by PCP.  On each installation, the
       file /etc/pcp.conf contains the local values for these variables.
       The $PCP_CONF variable may be used to specify an alternative
       configuration file, as described in pcp.conf(5).

SEE ALSO         top

       pcp(1), pmlogmv(1), pmgetopt_r(3), pcp.conf(5) and pcp.env(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

Performance Co-Pilot                 PCP                         PMGETOPT(1)