1PMGETOPT(1) General Commands Manual PMGETOPT(1)
2
6 pmgetopt - Performance Co-Pilot shell script option parser
7
9 $PCP_BINADM_DIR/pmgetopt [-c|--config file] [-p|--progname name]
10 [-u|--usage] [--] [parameters]
11
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 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 The options specific to pmgetopt are as follows:
23 -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 -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 -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 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 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
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 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 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 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 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
90 As an example, the following is a valid configuration:
91 # Usage: [options] node...
93 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 This configuration will produce the following usage message, when run
107 as shown.
108 $ pmgetopt --usage --progname=clusterstat -- "$@"
110 Usage: clusterstat [options] node...
111 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 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
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
138 pcp(1), pmlogmv(1), pmgetopt_r(3), pcp.conf(5) and pcp.env(5).
139Performance Co-Pilot PCP PMGETOPT(1)