1PMGETOPTIONS(3) Library Functions Manual PMGETOPTIONS(3)
2
6 pmgetopt_r, pmGetOptions, pmGetContextOptions, pmFreeOptions,
7 pmUsageMessage - command line handling for PMAPI tools
8
10 #include <pcp/pmapi.h>
11 int pmgetopt_r(int argc, char *const *argv, pmOptions *opts);
13 int pmGetOptions(int argc, char *const *argv, pmOptions *opts);
14 int pmGetContextOptions(int ctx, pmOptions *opts);
15 void pmUsageMessage(pmOptions *opts);
16 void pmFreeOptions(pmOptions *opts);
17 cc ... -lpcp
19
21 The pmGetOptions function provides command line option processing ser‐
22 vices for both monitor and collector PMAPI(3) tools. It is modelled on
23 the thread-safe variants of the GNU getopt_long(3) API, and primarily
24 differs in its focus on providing generalised processing for the (de-
25 facto) standard PCP command line options described in PCPIntro(1).
26 These common options include the host and archive specification, time
27 windows, timezones, sample counts, time intervals, and so on.
28 The primary interface is pmGetOptions, which should be passed the argc
30 argument count and argv array, as passed to the main() function on pro‐
31 gram invocation. The final opts argument describes the set of long and
32 short options the tools is prepared to process, and other metadata re‐
33 garding how those options should be processed.
34 The pmgetopt_r interface, used internally by pmGetOptions, behaves in a
36 similar fashion, but it does not perform any common option processing.
37 It is more suited to PCP collector processes, whereas PCP monitor tools
38 tend to use pmGetOptions.
39 The opts argument consists of an array of pmLongOpts entries describing
41 the arguments, as well as the enclosing pmOptions struct, which are de‐
42 fined as follows (internal fields are not presented, for brevity):
43 typedef struct {
45 const char * long_opt;
46 int has_arg;
47 int short_opt;
48 const char * argname;
49 const char * message;
50 } pmLongOptions;
51 typedef struct {
53 int version;
54 int flags;
55 const char * short_options;
56 pmLongOptions * long_options;
57 const char * short_usage;
58 pmOptionOverride override;
59 int index;
61 int optind;
62 int opterr;
63 int optopt;
64 char *optarg;
65 /* [internal fields, undocumented] */
66 int errors;
68 int context; /* PM_CONTEXT_{HOST,ARCHIVE,LOCAL} */
69 int nhosts;
70 int narchives;
71 char ** hosts;
72 char ** archives;
73 #if PMAPI_VERSION == PMAPI_VERSION_3
74 struct timeval unused[4];
75 #else
76 struct timeval start;
77 struct timeval finish;
78 struct timeval origin;
79 struct timeval interval;
80 #endif
81 char * align_optarg;
82 char * start_optarg;
83 char * finish_optarg;
84 char * origin_optarg;
85 char * guiport_optarg;
86 char * timezone;
87 int samples;
88 int guiport;
89 int padding;
90 unsigned int guiflag : 1;
91 unsigned int tzflag : 1;
92 unsigned int nsflag : 1;
93 unsigned int Lflag : 1;
94 unsigned int zeroes : 28;
95 #if PMAPI_VERSION == PMAPI_VERSION_3
96 struct timespec start;
97 struct timespec finish;
98 struct timespec origin;
99 struct timespec interval;
100 #endif
101 } pmOptions;
102 The initial flags and version fields describe how the rest of the pmOp‐
104 tions structure is to be interpreted. These fields can be zeroed,
105 specifying a default interpretation. Alternatively, the PMAPI_VERSION
106 macro can be used to specify the API level to use (currently, values of
107 3 or less are allowed). Version 2 is the default, version 3 introduces
108 high resolution time window and interval fields (i.e. using struct
109 timespec as opposed to struct timeval). When using the latter form,
110 before including <pcp/pmapi.h> the PMAPI_VERSION macro must be set to 3
111 to ensure the correct layout of pmOptions structure is used by the ap‐
112 plication. The flags field can be used to modify option processing be‐
113 haviour as described in the ``FLAGS VALUES'' section below.
114 The array of long_options pmLongOpts structures must be terminated by a
116 sentinel and the PMAPI_OPTIONS_END macro can be used to effect this
117 termination. Individual records within the long_options array can be
118 of two types - options headers, or actual options. An options header
119 is constructed using the PMAPI_OPTIONS_HEADER macro, and is used for
120 usage message option grouping. Free form text can be inserted into the
121 usage message at any point using the PMAPI_OPTIONS_TEXT macro - this is
122 intended for additional explanatory text covering detailed usage that
123 is beyond the scope of the individual headers or options. Otherwise,
124 the array entry specifies an option. These should be named (long_opt)
125 if a long-option form is allowed, specify whether or not they take an
126 argument (has_arg), specify the single character variant argument
127 (short_opt) if a short-option form is allowed, and finally specify how
128 to present the option in the usage message. This latter component con‐
129 sists of a short, one-word description of the optional argument
130 (argname) and a one-line description of what the command-line option
131 does (message).
132 The short_usage string is also used only when constructing the usage
134 message. It forms the component of the usage message that follows the
135 program name (i.e. argv[0]).
136 The optional short_options string is the normal getopt command-line op‐
138 tion specification string, using individual characters (those with ar‐
139 guments are designated as such using the ':' character) - as used by
140 all getopt implementations.
141 A facility is provided to extend the existing set of common options
143 with additional options, as well as to re-task the standard options
144 into non-standard roles for individual tools. The latter is achieved
145 using the override method, which allows a callback function to be pro‐
146 vided which will be called on receipt of every argument, prior to com‐
147 mon processing. If this callback returns a non-zero value the common
148 processing will be short-circuited for that option, otherwise process‐
149 ing continues. Thus, aach client tool is free to choose exactly which
150 of the standard options they wish to support - this can be all, some,
151 or none, and no matter what they choose, each tool always has access to
152 the long option parsing capability and the usage message generation fa‐
153 cility.
154 The remaining pmOptions structure fields are filled in as a result of
156 processing the arguments, and are largely self-explanatory. Further
157 discussion of these is deferred to the ``FLAGS VALUES'' section below.
158 The error field contains a count of errors detected during option pro‐
159 cessing. These can be either usage or runtime errors, as indicated by
160 the flags field (set, and passed out to the caller). Typically, a com‐
161 mand line tool will fail to start successfully and will produce an er‐
162 ror message (e.g. via pmUsageMessage) if the error field is non-zero at
163 the end of either pmGetOptions or pmGetContextOptions.
164 Some command line option post-processing can only be performed once the
166 tool has established a PMAPI context via pmNewContext(3). This pro‐
167 cessing includes use of context-aware timezones (-z), and time window
168 processing (-A, -O, -S, -T) that may be affected by the timezone, for
169 example. The pmGetContextOptions function is available for such situa‐
170 tions, and it completes any remaining processing of opts with respect
171 to the ctx context identifier given.
172 The pmUsageMessage function generates a usage message for the tool, and
174 included both standard PCP options and custom options for each tool, as
175 specified by the pmLongOptions array. It supports grouping of options
176 (via PMAPI_OPTIONS_HEADER) as well as neat formatting of all options -
177 short and long - their arguments, and individual explanatory messages.
178 It will build this usage message using pmprintf(3) upon which it will
179 issue a single pmflush(3) before returning to the caller, provided the
180 PM_OPTFLAG_USAGE_ERR flag is set in flags, which will happen automati‐
181 cally during option parsing, when usage errors are detected.
182 In certain situations, such as recording lists of host specifications
184 or PCP archive paths, the pmGetOptions routine may allocate memory, and
185 store pointers to it within opts. Should a program wish to free this
186 memory before exiting, it can use the pmFreeOptions routine to do so.
187 This is safe to call irrespective of whether memory was allocated dy‐
188 namically, provided that opts was zeroed initially.
189
191 PM_OPTFLAG_INIT
192 Used internally within the library to indicate initialisation
193 has been done, so that on subsequent calls it will not be done
194 again.
195 PM_OPTFLAG_DONE
197 Used primarily internally within the library to indicate that
198 the final option processing has been completed. This processing
199 involves cross-referencing a number of the options, to check for
200 mutual exclusion, for example. There may be other post-process‐
201 ing at this stage also, provided it does not require a PMAPI
202 context.
203 PM_OPTFLAG_MULTI
205 Allow more than one host or set of archives to be specified.
206 The default is to allow one source of metrics only, however some
207 of the more sophisticated tools permit multiple metric sources,
208 each of which is handled within a separate context. See also
209 PM_OPTFLAG_MIXED.
210 PM_OPTFLAG_USAGE_ERR
212 Indicates that the library has detected a command-line usage er‐
213 ror. This is an error such as when an option requires an argu‐
214 ment but none is supplied, or conflicting options are specified
215 (such as -s and -T).
216 PM_OPTFLAG_RUNTIME_ERR
218 Indicates that the library has detected an error at run time.
219 This is an error such as failing to retrieve timezone informa‐
220 tion from pmcd (1) or failing to load an alternate metric name‐
221 space from a local file (via the -n option).
222 PM_OPTFLAG_EXIT
224 Indicates a suggestion from the library that the tool exit
225 cleanly. This is used when the version number is requested, for
226 example (the -V option and PMOPT_VERSION macro).
227 PM_OPTFLAG_POSIX
229 Use strict POSIX command line argument handling. This means op‐
230 tions and following arguments will not be reordered, so addi‐
231 tional options cannot follow command line arguments. This may
232 be important for tools where the arguments can be negative num‐
233 bers, for example, as these should not be treated as command
234 line options in this case.
235 PM_OPTFLAG_MIXED
237 Allow both live and archive metric sources to be specified. The
238 default is to allow one type of metric context only, however
239 some of the more sophisticated tools permit multiple context
240 types. See also PM_OPTFLAG_MULTI.
241 PM_OPTFLAG_ENV_ONLY
243 Many options can be specified through the either the command
244 line or from similarly-named environment variables. This flag
245 disables all argument parsing, and only changes opts based on
246 the environment variables. This may be useful for tools wishing
247 to ensure no command line option conflicts occur between their
248 own set and the standard PCP option set (such as an existing
249 tool, reimplemented using PMAPI services).
250 PM_OPTFLAG_LONG_ONLY
252 Only process long options, not short options.
253 PM_OPTFLAG_BOUNDARIES
255 The default pmGetOptions behaviour is to parse the time window
256 options (namely, -A, -O, -S and -T), only if one of those op‐
257 tions has been specified on the command line. However, this
258 flag can be used (particularly with archive contexts) to find
259 the start and finish times associated with the context(s) even
260 if no time window options were specified. In the case of multi‐
261 ple archives, the time window is defined as the time window
262 spanning all of the archives.
263 PM_OPTFLAG_STDOUT_TZ
265 The timezone being used will be reported on the standard output
266 stream during option parsing. The default behaviour is to not
267 report, but simply return timezone information via the timezone
268 (-Z) and tzflag (-z) fields in the opts structure.
269 PM_OPTFLAG_NOFLUSH
271 The final pmflush call issued by pmUsageMessage will be skipped
272 if this flag is set. This is useful in situations where the
273 caller wishes to append additional test to the generated usage
274 message before flushing.
275 PM_OPTFLAG_QUIET
277 Suppress messages from pmgetopt_r about unrecognised command
278 line options. This is the equivalent to setting the opterr
279 field in the opt parameter (which mimics the getopt variable of
280 the same name).
281
283 Some environment variables may be used as an alternative to the command
284 line options. The use of these mechanisms is primarily for internal
285 use by PCP tools. General users should choose the command line options
286 as this provides a clearer indication of intent, makes debugging issues
287 easier and avoids confusion over possible conflicts between the command
288 line options and the environment variables (where the command line op‐
289 tions usually ``win'').
290 The following table describes the environment variables that may be
292 used to set values as an alternative to command line options.
293 ┌───────────────────┬─────────┬──────────────────┬─────────────────────┐
295 │ Environment │ Short │ Long │ Meaning │
296 │ │ Option │ Option │ │
297 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
298 │$PCP_ALIGN_TIME │ -A │ --align │ align sample │
299 │ │ │ │ times on natural │
300 │ │ │ │ boundaries │
301 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
302 │$PCP_ARCHIVE │ -a │ --archive │ metrics source │
303 │ │ │ │ is a PCP archive │
304 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
305 │$PCP_ARCHIVE_LIST │ │ --archive-list │ comma-separated │
306 │ │ │ │ list of metric │
307 │ │ │ │ source archives │
308 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
309 │$PCP_FOLIO │ │ --archive-folio │ metric source is │
310 │ │ │ │ a mkaf(1) │
311 │ │ │ │ archives folio │
312 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
313 │$PCP_DEBUG │ -D │ --debug │ a comma- │
314 │ │ │ │ separated list │
315 │ │ │ │ of pmSetDebug(3) │
316 │ │ │ │ debugging │
317 │ │ │ │ options │
318 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
319 │$PCP_GUIMODE │ -g │ --guimode │ start in GUI │
320 │ │ │ │ mode with new │
321 │ │ │ │ pmtime(1) time │
322 │ │ │ │ control │
323 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
324 │$PCP_HOST │ -h │ --host │ metrics source │
325 │ │ │ │ is pmcd(1) on a │
326 │ │ │ │ host │
327 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
328 │$PCP_HOST_LIST │ │ --host-list │ comma-separated │
329 │ │ │ │ list of metric │
330 │ │ │ │ source hosts │
331 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
332 │$PCP_SPECLOCAL │ -K │ --spec-local │ optional │
333 │ │ │ │ additional DSO │
334 │ │ │ │ PMDA │
335 │ │ │ │ specification │
336 │ │ │ │ for local │
337 │ │ │ │ connection, see │
338 │ │ │ │ pmSpecLocalPMDA(3) │
339 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
340 │$PCP_LOCALPMDA or │ -L │ --local-PMDA │ metrics source is │
341 │$PCP_LOCALMODE │ │ │ local connection │
342 │ │ │ │ to a DSO PMDA │
343 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
344 │$PCP_NAMESPACE │ -n │ --namespace │ use an alternative │
345 │ │ │ │ Performance │
346 │ │ │ │ Metrics Name Space │
347 │ │ │ │ (PMNS) │
348 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
349 │$PCP_UNIQNAMES │ -N │ --uniqnames │ like -n but only │
350 │ │ │ │ one name allowed │
351 │ │ │ │ for each metric in │
352 │ │ │ │ the PMNS │
353 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
354 │$PCP_ORIGIN or │ -O │ --origin │ initial sample │
355 │$ORIGIN_TIME │ │ │ time within the │
356 │ │ │ │ time window │
357 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
358 │$PCP_GUIPORT │ -p │ --guiport │ port for │
359 │ │ │ │ connection to an │
360 │ │ │ │ existing pmtime(1) │
361 │ │ │ │ time control │
362 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
363 │$PCP_START_TIME │ -S │ --start │ start of the time │
364 │ │ │ │ window │
365 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
366 │$PCP_SAMPLES │ -s │ --samples │ terminate after │
367 │ │ │ │ this many samples │
368 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
369 │$PCP_FINISH_TIME │ -T │ --finish │ end of the time │
370 │ │ │ │ window │
371 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
372 │$PCP_INTERVAL │ -t │ --interval │ sampling interval │
373 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
374 │$PCP_TIMEZONE │ -Z │ --timezone │ set reporting │
375 │ │ │ │ timezone │
376 ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
377 │$PCP_HOSTZONE │ -z │ --hostzone │ set reporting │
378 │ │ │ │ timezone to local │
379 │ │ │ │ time of metrics │
380 │ │ │ │ source │
381 └───────────────────┴─────────┴──────────────────┴─────────────────────┘
383 The pmGetOptions function returns either when it detects a command-line
384 option that is not one of the standard PCP set, or when the end of the
385 command line options has been reached (at which point -1 is returned).
386 Both the pmgetopt_r and pmGetOptions routines return control to the
387 caller in the same way that a regular getopt call would, with the
388 return value indicating either the end of all processing (-1), or the
389 single character form of the option currently being processed, or zero
390 for the special long-option-only case. For all option-processing
391 cases, the opts structure is returned containing filled out optarg,
392 opterr, optopt, optind, and index fields as normal (do NOT use the
393 global optarg or optind from your platform C library, these will NOT be
394 modified).
395 pmGetOptions does not return to the caller when any of the standard PCP
397 options are being processed (although the override mechanism can be
398 used to still detect such options if needed).
399 The pmGetContextOptions function returns zero on success, or a negative
401 PCP error code on failure. The error field within the opts parameter
402 will also be non-zero in the latter case.
403
405 Environment variables with the prefix PCP_ are used to parameterize the
406 file and directory names used by PCP. On each installation, the file
407 /etc/pcp.conf contains the local values for these variables. The
408 $PCP_CONF variable may be used to specify an alternative configuration
409 file, as described in pcp.conf(5). Values for these variables may be
410 obtained programmatically using the pmGetOptions(3) function.
411
413 PCPIntro(1), pmcd(1), pminfo(1), pmstat(1), getopt(3), getopt_long(3),
414 pmNewContext(3), pmGetConfig(3), pmprintf(3), pmflush(3) and PMAPI(3).
415Performance Co-Pilot PCP PMGETOPTIONS(3)