xenial (1) pmgetopt.1.gz

Provided by: pcp_3.10.8build1_amd64 bug

NAME

       pmgetopt - Performance Co-Pilot shell script option parser

SYNOPSIS

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

DESCRIPTION

       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

       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

       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

       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

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