1PMGETOPT(1) General Commands Manual PMGETOPT(1)
2
6 pmgetopt - Performance Co-Pilot shell script option parser
7
9 $PCP_BINADM_DIR/pmgetopt [-u?] [-c file] [-p name] [--] [parameters]
10
12 pmgetopt is used to perform command line option parsing for shell
13 scripts used in the Performance Co-Pilot (PCP toolkit). It is also
14 used to generate usage messages for those scripts.
15 The parameters given to pmgetopt take two forms: initially, options
17 specific to pmgetopt itself are passed in, and terminated using the --
18 mechanism. Thereafter, all of the parameters passed into the shell
19 script should be passed (usually this is simply the "$@" variable).
20
22 The available command line options are:
23 -c=file, --config=file
25 A configuration file in the format described below is passed to
26 pmconfig using this option. If this option is omitted, then pm‐
27 config will read its configuration from the standard input stream.
28 -p=name, --progname=name
30 When parsing the calling shell scripts parameters, error and usage
31 messages will contain the given program name rather than referring
32 to pmgetopt itself as the source of the error.
33 -u, --usage
35 A usage message appropriate for the calling shell script to
36 present as its own can be generated using the option.
37 -?, --help
39 Display the usage message for pmgetopt itself and exit.
40 pmgetopt parses the given parameters, and produces output in a format
42 suitable for sourcing in the calling shell script. When both short and
43 long forms of an argument are allowed by the specification, pmgetopt
44 will always indicate the short form for simpler shell processing. If
45 arguments are presented that do not match the configuration, a request
46 for a usage message (-?) will be generated for the calling script to
47 respond to. Any non-option parameters will be echoed back to the call‐
48 ing script preceded by the double-hyphen delimiter. Thus a script
49 should stop handling options when this delimiter is detected, and begin
50 the handling of any non-option arguments.
51 Unlike with the shell built-in getopt command, variables like $OPTARG
53 are not set and the calling script will typically employ use of the
54 shell built-in eval, set and positional shift commands to ensure option
55 processing occurs correctly.
56
58 The configuration format used by pmgetopt is intended to closely re‐
59 flect the usage message which would be generated in the presence of in‐
60 valid arguments (or the -?, --help option).
61 There are primarily two types of configuration line - commands and op‐
63 tions. Commands allow metadata to be passed into the option processing
64 process, and options are the allowable command line options that the
65 shell script will accept. Command lines are preceded by the hash char‐
66 acter, whereas option lines will always begin with a hyphen (either
67 single or double). Any other line in the configuration, which may in‐
68 clude usage headers or descriptive text, has no impact on the option
69 parsing and will be copied unmodified into the usage message.
70 The set of commands is: getopt (provide short-argument option specifi‐
72 cation manually, if not present this will be generated from the options
73 presented), usage (provide short one-line summary used at the head of
74 the usage message, which will be prefixed by the progname before re‐
75 porting), and end which informs pmgetopt to stop processing further
76 commands and options - any subsequent text encountered will be simply
77 appended to the usage message.
78 A short-hand notation exists for each of the standard PCP options, as
80 described in PCPIntro(1). If any of these options (e.g --host) appears
81 as a single word on any line, it will be transformed into the appropri‐
82 ate option for the shell script, including all metadata about that op‐
83 tion (whether it accepts an argument, both short and long option forms,
84 and so on).
85 Use of the equals symbol ("=") indicates the presence of a required ar‐
87 gument to any option, for both short and long forms. Any non-standard
88 option must be accompanied by a non-empty description of that argument.
89
91 As an example, the following is a valid configuration:
92 # Usage: [options] node...
94 Options:
96 --archive
97 -d, --delay pause between updates for archive replay
98 --host
99 --interval
100 -i=INST, --insts=INST comma-separated metrics instance list
101 -r output raw counters (no rate conversion)
102 --width=N set the width of each column of output
103 --timezone
104 --help
105 This configuration will produce the following usage message, when run
108 as shown.
109 $ pmgetopt --usage --progname=clusterstat -- "$@"
111 Usage: clusterstat [options] node...
112 Options:
114 -a FILE, --archive=FILE
115 metrics source is a PCP archive
116 -d, --delay pause between updates for archive replay
117 -h HOST, --host=HOST metrics source is PMCD on host
118 -t DELTA, --interval=DELTA
119 sampling interval
120 -i INST, --insts=INST comma-separated metrics instance list
121 -r output raw counters (no rate conversion)
122 --width=N set the width of each column of output
123 -Z TZ, --timezone=TZ set reporting timezone
124 -?, --help show this usage message and exit
125 Several examples of pmgetopt use form part of the PCP toolkit, in par‐
128 ticular the pcp(1) and pmlogmv(1) scripts provide good reference exam‐
129 ples.
130
132 Environment variables with the prefix PCP_ are used to parameterize the
133 file and directory names used by PCP. On each installation, the file
134 /etc/pcp.conf contains the local values for these variables. The
135 $PCP_CONF variable may be used to specify an alternative configuration
136 file, as described in pcp.conf(5).
137
139 pcp(1), pmlogmv(1), pmgetopt_r(3), pcp.conf(5) and pcp.env(5).
140Performance Co-Pilot PCP PMGETOPT(1)