Provided by: pcp_6.0.5-1_amd64 bug

NAME

       pmgetopt - Performance Co-Pilot shell script option parser

SYNOPSIS

       $PCP_BINADM_DIR/pmgetopt [-u?]  [-c file] [-p name] [--] [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).

OPTIONS

       The available command line options are:

       -c=file, --config=file
            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=name, --progname=name
            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.

       -?, --help
            Display the usage message for pmgetopt itself and exit.

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