1PMGETOPT(1)                 General Commands Manual                PMGETOPT(1)
2
3
4

NAME

6       pmgetopt - Performance Co-Pilot shell script option parser
7

SYNOPSIS

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

DESCRIPTION

13       pmgetopt is used to perform  command  line  option  parsing  for  shell
14       scripts  used  in  the  Performance Co-Pilot (PCP toolkit).  It is also
15       used to generate usage messages for those scripts.
16
17       The parameters given to pmgetopt take  two  forms:  initially,  options
18       specific  to pmgetopt itself are passed in, and terminated using the --
19       mechanism.  Thereafter, all of the parameters  passed  into  the  shell
20       script should be passed (usually this is simply the "$@" variable).
21
22       The options specific to pmgetopt are as follows:
23
24       -c,--config
25            A  configuration  file  in the format described below is passed to
26            pmconfig using this option.   If  this  option  is  omitted,  then
27            pmconfig  will  read  its  configuration  from  the standard input
28            stream.
29
30       -p,--progname
31            When parsing the calling shell scripts parameters, error and usage
32            messages will contain the given program name rather than referring
33            to pmgetopt itself as the source of the error.
34
35       -u,--usage
36            A usage message  appropriate  for  the  calling  shell  script  to
37            present as its own can be generated using the option.
38
39       pmgetopt  parses  the given parameters, and produces output in a format
40       suitable for sourcing in the calling shell script.  When both short and
41       long  forms  of  an argument are allowed by the specification, pmgetopt
42       will always indicate the short form for simpler shell  processing.   If
43       arguments  are presented that do not match the configuration, a request
44       for a usage message (-?) will be generated for the  calling  script  to
45       respond to.  Any non-option parameters will be echoed back to the call‐
46       ing script preceded by the  double-hyphen  delimiter.   Thus  a  script
47       should stop handling options when this delimiter is detected, and begin
48       the handling of any non-option arguments.
49
50       Unlike with the shell built-in getopt command, variables  like  $OPTARG
51       are  not  set  and  the calling script will typically employ use of the
52       shell built-in eval, set and positional shift commands to ensure option
53       processing occurs correctly.
54

CONFIGURATION

56       The  configuration  format  used  by  pmgetopt  is  intended to closely
57       reflect the usage message which would be generated in the  presence  of
58       invalid arguments (or the -?,--help option).
59
60       There  are  primarily  two  types  of configuration line - commands and
61       options.  Commands allow metadata to be passed into the option process‐
62       ing  process,  and  options are the allowable command line options that
63       the shell script will accept.  Command lines are preceded by  the  hash
64       character, whereas option lines will always begin with a hyphen (either
65       single or double).  Any other line  in  the  configuration,  which  may
66       include  usage headers or descriptive text, has no impact on the option
67       parsing and will be copied unmodified into the usage message.
68
69       The set of commands is: getopt (provide short-argument option  specifi‐
70       cation manually, if not present this will be generated from the options
71       presented), usage (provide short one-line summary used at the  head  of
72       the  usage  message,  which  will  be  prefixed  by the progname before
73       reporting), and end which informs pmgetopt to stop  processing  further
74       commands  and  options - any subsequent text encountered will be simply
75       appended to the usage message.
76
77       A short-hand notation exists for each of the standard PCP  options,  as
78       described in PCPIntro(1).  If any of these options (e.g --host) appears
79       as a single word on any line, it will be transformed into the appropri‐
80       ate  option  for  the  shell  script, including all metadata about that
81       option (whether it accepts an argument,  both  short  and  long  option
82       forms, and so on).
83
84       Use  of  the  equals  symbol ("=") indicates the presence of a required
85       argument to any option, for both short and long forms.   Any  non-stan‐
86       dard  option  must  be  accompanied  by a non-empty description of that
87       argument.
88

EXAMPLES

90       As an example, the following is a valid configuration:
91
92            # Usage: [options] node...
93
94            Options:
95                --archive
96                -d, --delay            pause between updates for archive replay
97                --host
98                --interval
99                -i=INST, --insts=INST  comma-separated metrics instance list
100                -r                     output raw counters (no rate conversion)
101                --width=N              set the width of each column of output
102                --timezone
103                --help
104
105
106       This configuration will produce the following usage message,  when  run
107       as shown.
108
109            $ pmgetopt --usage --progname=clusterstat -- "$@"
110            Usage: clusterstat [options] node...
111
112            Options:
113              -a FILE, --archive=FILE
114                                    metrics source is a PCP log archive
115              -d, --delay           pause between updates for archive replay
116              -h HOST, --host=HOST  metrics source is PMCD on host
117              -t DELTA, --interval=DELTA
118                                    sampling interval
119              -i INST, --insts=INST comma-separated metrics instance list
120              -r                    output raw counters (no rate conversion)
121              --width=N             set the width of each column of output
122              -Z TZ, --timezone=TZ  set reporting timezone
123              -?, --help            show this usage message and exit
124
125
126       Several  examples of pmgetopt use form part of the PCP toolkit, in par‐
127       ticular the pcp(1) and pmlogmv(1) scripts provide good reference  exam‐
128       ples.
129

PCP ENVIRONMENT

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

SEE ALSO

138       pcp(1), pmlogmv(1), pmgetopt_r(3), pcp.conf(5) and pcp.env(5).
139
140
141
142Performance Co-Pilot                  PCP                          PMGETOPT(1)
Impressum