Provided by: pcp_4.3.1-1_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).