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
33 regarding 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
42 defined 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 struct timeval start;
74 struct timeval finish;
75 struct timeval origin;
76 struct timeval interval;
77 char * align_optarg;
78 char * start_optarg;
79 char * finish_optarg;
80 char * origin_optarg;
81 char * guiport_optarg;
82 char * timezone;
83 int samples;
84 int guiport;
85 int padding;
86 unsigned int guiflag : 1;
87 unsigned int tzflag : 1;
88 unsigned int nsflag : 1;
89 unsigned int Lflag : 1;
90 unsigned int zeroes : 28;
91 } pmOptions;
92 The initial flags and version fields describe how the rest of the pmOp‐
94 tions structure is to be interpreted. These fields can be zeroed,
95 specifying a default interpretation. Alternatively, the PMAPI_VERSION
96 macro can be used to specify the API level to use (currently, values of
97 2 or less are allowed). The flags field can be used to modify option
98 processing behaviour as described in the ``FLAGS VALUES'' section
99 below.
100 The array of long_options pmLongOpts structures must be terminated by a
102 sentinel and the PMAPI_OPTIONS_END macro can be used to effect this
103 termination. Individual records within the long_options array can be
104 of two types - options headers, or actual options. An options header
105 is constructed using the PMAPI_OPTIONS_HEADER macro, and is used for
106 usage message option grouping. Free form text can be inserted into the
107 usage message at any point using the PMAPI_OPTIONS_TEXT macro - this is
108 intended for additional explanatory text covering detailed usage that
109 is beyond the scope of the individual headers or options. Otherwise,
110 the array entry specifies an option. These should be named (long_opt)
111 if a long-option form is allowed, specify whether or not they take an
112 argument (has_arg), specify the single character variant argument
113 (short_opt) if a short-option form is allowed, and finally specify how
114 to present the option in the usage message. This latter component con‐
115 sists of a short, one-word description of the optional argument
116 (argname) and a one-line description of what the command-line option
117 does (message).
118 The short_usage string is also used only when constructing the usage
120 message. It forms the component of the usage message that follows the
121 program name (i.e. argv[0]).
122 The optional short_options string is the normal getopt command-line
124 option specification string, using individual characters (those with
125 arguments are designated as such using the ':' character) - as used by
126 all getopt implementations.
127 A facility is provided to extend the existing set of common options
129 with additional options, as well as to re-task the standard options
130 into non-standard roles for individual tools. The latter is achieved
131 using the override method, which allows a callback function to be pro‐
132 vided which will be called on receipt of every argument, prior to com‐
133 mon processing. If this callback returns a non-zero value the common
134 processing will be short-circuited for that option, otherwise process‐
135 ing continues. Thus, aach client tool is free to choose exactly which
136 of the standard options they wish to support - this can be all, some,
137 or none, and no matter what they choose, each tool always has access to
138 the long option parsing capability and the usage message generation
139 facility.
140 The remaining pmOptions structure fields are filled in as a result of
142 processing the arguments, and are largely self-explanatory. Further
143 discussion of these is deferred to the ``FLAGS VALUES'' section below.
144 The error field contains a count of errors detected during option pro‐
145 cessing. These can be either usage or runtime errors, as indicated by
146 the flags field (set, and passed out to the caller). Typically, a com‐
147 mand line tool will fail to start successfully and will produce an
148 error message (e.g. via pmUsageMessage) if the error field is non-zero
149 at the end of either pmGetOptions or pmGetContextOptions.
150 Some command line option post-processing can only be performed once the
152 tool has established a PMAPI context via pmNewContext(3). This pro‐
153 cessing includes use of context-aware timezones (-z), and time window
154 processing (-A, -O, -S, -T) that may be affected by the timezone, for
155 example. The pmGetContextOptions function is available for such situa‐
156 tions, and it completes any remaining processing of opts with respect
157 to the ctx context identifier given.
158 The pmUsageMessage function generates a usage message for the tool, and
160 included both standard PCP options and custom options for each tool, as
161 specified by the pmLongOptions array. It supports grouping of options
162 (via PMAPI_OPTIONS_HEADER) as well as neat formatting of all options -
163 short and long - their arguments, and individual explanatory messages.
164 It will build this usage message using pmprintf(3) upon which it will
165 issue a single pmflush(3) before returning to the caller, provided the
166 PM_OPTFLAG_USAGE_ERR flag is set in flags, which will happen automati‐
167 cally during option parsing, when usage errors are detected.
168 In certain situations, such as recording lists of host specifications
170 or PCP archive paths, the pmGetOptions routine may allocate memory, and
171 store pointers to it within opts. Should a program wish to free this
172 memory before exiting, it can use the pmFreeOptions routine to do so.
173 This is safe to call irrespective of whether memory was allocated
174 dynamically, provided that opts was zeroed initially.
175
177 PM_OPTFLAG_INIT
178 Used internally within the library to indicate initialisation
179 has been done, so that on subsequent calls it will not be done
180 again.
181 PM_OPTFLAG_DONE
183 Used primarily internally within the library to indicate that
184 the final option processing has been completed. This processing
185 involves cross-referencing a number of the options, to check for
186 mutual exclusion, for example. There may be other post-process‐
187 ing at this stage also, provided it does not require a PMAPI
188 context.
189 PM_OPTFLAG_MULTI
191 Allow more than one host or archive to be specified. The
192 default is to allow one source of metrics only, however some of
193 the more sophisticated tools permit multiple metric sources.
194 See also PM_OPTFLAG_MIXED.
195 PM_OPTFLAG_USAGE_ERR
197 Indicates that the library has detected a command-line usage
198 error. This is an error such as when an option requires an
199 argument but none is supplied, or conflicting options are speci‐
200 fied (such as -s and -T).
201 PM_OPTFLAG_RUNTIME_ERR
203 Indicates that the library has detected an error at run time.
204 This is an error such as failing to retrieve timezone informa‐
205 tion from pmcd (1) or failing to load an alternate metric names‐
206 pace from a local file (via the -n option).
207 PM_OPTFLAG_EXIT
209 Indicates a suggestion from the library that the tool exit
210 cleanly. This is used when the version number is requested, for
211 example (the -V option and PMOPT_VERSION macro).
212 PM_OPTFLAG_POSIX
214 Use strict POSIX command line argument handling. This means
215 options and following arguments will not be reordered, so addi‐
216 tional options cannot follow command line arguments. This may
217 be important for tools where the arguments can be negative num‐
218 bers, for example, as these should not be treated as command
219 line options in this case.
220 PM_OPTFLAG_MIXED
222 Allow both live and archive metric sources to be specified. The
223 default is to allow one type of metric context only, however
224 some of the more sophisticated tools permit multiple context
225 types. See also PM_OPTFLAG_MULTI.
226 PM_OPTFLAG_ENV_ONLY
228 Many options can be specified through the either the command
229 line or from similarly-named environment variables. This flag
230 disables all argument parsing, and only changes opts based on
231 the environment variables. This may be useful for tools wishing
232 to ensure no command line option conflicts occur between their
233 own set and the standard PCP option set (such as an existing
234 tool, reimplemented using PMAPI services).
235 PM_OPTFLAG_LONG_ONLY
237 Only process long options, not short options.
238 PM_OPTFLAG_BOUNDARIES
240 The default pmGetOptions behaviour is to parse the time window
241 options (namely, -A, -O, -S and -T), only if one of those
242 options has been specified on the command line. However, this
243 flag can be used (particularly with archive contexts) to find
244 the start and finish times associated with the context(s) even
245 if no time window options were specified. In the case of multi‐
246 ple archives, the time window is defined as the time window
247 spanning all of the archives.
248 PM_OPTFLAG_STDOUT_TZ
250 The timezone being used will be reported on the standard output
251 stream during option parsing. The default behaviour is to not
252 report, but simply return timezone information via the timezone
253 (-Z) and tzflag (-z) fields in the opts structure.
254 PM_OPTFLAG_NOFLUSH
256 The final pmflush call issued by pmUsageMessage will be skipped
257 if this flag is set. This is useful in situations where the
258 caller wishes to append additional test to the generated usage
259 message before flushing.
260 PM_OPTFLAG_QUIET
262 Suppress messages from pmgetopt_r about unrecognised command
263 line options. This is the equivalent to setting the opterr
264 field in the opt parameter (which mimics the getopt variable of
265 the same name).
266
268 The pmGetOptions function returns either when it detects a command-line
269 option that is not one of the standard PCP set, or when the end of the
270 command line options has been reached (at which point -1 is returned).
271 Both the pmgetopt_r and pmGetOptions routines return control to the
272 caller in the same way that a regular getopt call would, with the
273 return value indicating either the end of all processing (-1), or the
274 single character form of the option currently being processed, or zero
275 for the special long-option-only case. For all option-processing
276 cases, the opts structure is returned containing filled out optarg,
277 opterr, optopt, optind, and index fields as normal (do NOT use the
278 global optarg or optind from your platform C library, these will NOT be
279 modified).
280 pmGetOptions does not return to the caller when any of the standard PCP
282 options are being processed (although the override mechanism can be
283 used to still detect such options if needed).
284 The pmGetContextOptions function returns zero on success, or a negative
286 PCP error code on failure. The error field within the opts parameter
287 will also be non-zero in the latter case.
288
290 Environment variables with the prefix PCP_ are used to parameterize the
291 file and directory names used by PCP. On each installation, the file
292 /etc/pcp.conf contains the local values for these variables. The
293 $PCP_CONF variable may be used to specify an alternative configuration
294 file, as described in pcp.conf(5). Values for these variables may be
295 obtained programmatically using the pmGetOptions(3) function.
296
298 PCPIntro(1), pmcd(1), pminfo(1), pmstat(1), getopt(3), getopt_long(3),
299 pmNewContext(3), pmGetConfig(3), pmprintf(3), pmflush(3) and PMAPI(3).
300Performance Co-Pilot PCP PMGETOPTIONS(3)