1PMGETOPTIONS(3)            Library Functions Manual            PMGETOPTIONS(3)
2
3
4

NAME

6       pmgetopt_r,     pmGetOptions,    pmGetContextOptions,    pmFreeOptions,
7       pmUsageMessage - command line handling for PMAPI tools
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       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
18       cc ... -lpcp
19

DESCRIPTION

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
29       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
35       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
40       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
44         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
52         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
60             int                 index;
61             int                 optind;
62             int                 opterr;
63             int                 optopt;
64             char                *optarg;
65             /* [internal fields, undocumented] */
66
67             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
93       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
101       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
119       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
123       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
128       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
141       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
151       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
159       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
169       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

FLAGS VALUES

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
182       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
190       PM_OPTFLAG_MULTI
191              Allow  more  than  one  host or set of archives to be specified.
192              The default is to allow one source of metrics only, however some
193              of  the more sophisticated tools permit multiple metric sources,
194              each of which is handled within a separate  context.   See  also
195              PM_OPTFLAG_MIXED.
196
197       PM_OPTFLAG_USAGE_ERR
198              Indicates  that  the  library  has detected a command-line usage
199              error.  This is an error such as  when  an  option  requires  an
200              argument but none is supplied, or conflicting options are speci‐
201              fied (such as -s and -T).
202
203       PM_OPTFLAG_RUNTIME_ERR
204              Indicates that the library has detected an error  at  run  time.
205              This  is  an error such as failing to retrieve timezone informa‐
206              tion from pmcd (1) or failing to load an alternate metric names‐
207              pace from a local file (via the -n option).
208
209       PM_OPTFLAG_EXIT
210              Indicates  a  suggestion  from  the  library  that the tool exit
211              cleanly.  This is used when the version number is requested, for
212              example (the -V option and PMOPT_VERSION macro).
213
214       PM_OPTFLAG_POSIX
215              Use  strict  POSIX  command  line argument handling.  This means
216              options and following arguments will not be reordered, so  addi‐
217              tional  options  cannot follow command line arguments.  This may
218              be important for tools where the arguments can be negative  num‐
219              bers,  for  example,  as  these should not be treated as command
220              line options in this case.
221
222       PM_OPTFLAG_MIXED
223              Allow both live and archive metric sources to be specified.  The
224              default  is  to  allow  one type of metric context only, however
225              some of the more sophisticated  tools  permit  multiple  context
226              types.  See also PM_OPTFLAG_MULTI.
227
228       PM_OPTFLAG_ENV_ONLY
229              Many  options  can  be  specified through the either the command
230              line or from similarly-named environment variables.   This  flag
231              disables  all  argument  parsing, and only changes opts based on
232              the environment variables.  This may be useful for tools wishing
233              to  ensure  no command line option conflicts occur between their
234              own set and the standard PCP option set  (such  as  an  existing
235              tool, reimplemented using PMAPI services).
236
237       PM_OPTFLAG_LONG_ONLY
238              Only process long options, not short options.
239
240       PM_OPTFLAG_BOUNDARIES
241              The  default  pmGetOptions behaviour is to parse the time window
242              options (namely, -A, -O, -S  and  -T),  only  if  one  of  those
243              options  has  been specified on the command line.  However, this
244              flag can be used (particularly with archive  contexts)  to  find
245              the  start  and finish times associated with the context(s) even
246              if no time window options were specified.  In the case of multi‐
247              ple  archives,  the  time  window  is defined as the time window
248              spanning all of the archives.
249
250       PM_OPTFLAG_STDOUT_TZ
251              The timezone being used will be reported on the standard  output
252              stream  during  option parsing.  The default behaviour is to not
253              report, but simply return timezone information via the  timezone
254              (-Z) and tzflag (-z) fields in the opts structure.
255
256       PM_OPTFLAG_NOFLUSH
257              The  final pmflush call issued by pmUsageMessage will be skipped
258              if this flag is set.  This is useful  in  situations  where  the
259              caller  wishes  to append additional test to the generated usage
260              message before flushing.
261
262       PM_OPTFLAG_QUIET
263              Suppress messages from  pmgetopt_r  about  unrecognised  command
264              line  options.   This  is  the  equivalent to setting the opterr
265              field in the opt parameter (which mimics the getopt variable  of
266              the same name).
267

OPTIONS VIA ENVIRONMENT VARIABLES

269       Some environment variables may be used as an alternative to the command
270       line options.  The use of these mechanisms is  primarily  for  internal
271       use by PCP tools.  General users should choose the command line options
272       as this provides a clearer indication of intent, makes debugging issues
273       easier and avoids confusion over possible conflicts between the command
274       line options and the environment  variables  (where  the  command  line
275       options usually ``win'').
276
277       The  following  table  describes  the environment variables that may be
278       used to set values as an alternative to command line options.
279
280       ┌───────────────────┬─────────┬──────────────────┬─────────────────────┐
281       │   Environment     │ Short   │      Long        │      Meaning        │
282       │                   │ Option  │     Option       │                     │
283       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
284$PCP_ALIGN_TIME    -A      --align          │ align sample        │
285       │                   │         │                  │ times on natural    │
286       │                   │         │                  │ boundaries          │
287       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
288$PCP_ARCHIVE       -a      --archive        │ metrics source      │
289       │                   │         │                  │ is a PCP archive    │
290       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
291$PCP_ARCHIVE_LIST  │         │ --archive-list   │ comma-separated     │
292       │                   │         │                  │ list of metric      │
293       │                   │         │                  │ source archives     │
294       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
295$PCP_FOLIO         │         │ --archive-folio  │ metric source is    │
296       │                   │         │                  │ a mkaf(1)
297       │                   │         │                  │ archives folio      │
298       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
299$PCP_DEBUG         -D      --debug          │ a comma-            │
300       │                   │         │                  │ separated list      │
301       │                   │         │                  │ of pmSetDebug(3)
302       │                   │         │                  │ debugging           │
303       │                   │         │                  │ options             │
304       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
305$PCP_GUIMODE       -g      --guimode        │ start in GUI        │
306       │                   │         │                  │ mode with new       │
307       │                   │         │                  │ pmtime(1) time      │
308       │                   │         │                  │ control             │
309       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
310$PCP_HOST          -h      --host           │ metrics source      │
311       │                   │         │                  │ is pmcd(1) on a     │
312       │                   │         │                  │ host                │
313       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
314$PCP_HOST_LIST     │         │ --host-list      │ comma-separated     │
315       │                   │         │                  │ list of metric      │
316       │                   │         │                  │ source hosts        │
317       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
318$PCP_SPECLOCAL     -K      --spec-local     │ optional            │
319       │                   │         │                  │ additional DSO      │
320       │                   │         │                  │ PMDA                │
321       │                   │         │                  │ specification       │
322       │                   │         │                  │ for local           │
323       │                   │         │                  │ connection, see     │
324       │                   │         │                  │ pmSpecLocalPMDA(3)
325       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
326$PCP_LOCALPMDA or  │ -L      --local-PMDA     │ metrics source is   │
327$PCP_LOCALMODE     │         │                  │ local connection    │
328       │                   │         │                  │ to a DSO PMDA       │
329       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
330$PCP_NAMESPACE     -n      --namespace      │ use an alternative  │
331       │                   │         │                  │ Performance         │
332       │                   │         │                  │ Metrics Name Space  │
333       │                   │         │                  │ (PMNS)              │
334       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
335$PCP_UNIQNAMES     -N      --uniqnames      │ like -n but only    │
336       │                   │         │                  │ one name allowed    │
337       │                   │         │                  │ for each metric in  │
338       │                   │         │                  │ the PMNS            │
339       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
340$PCP_ORIGIN or     │ -O      --origin         │ initial sample      │
341$ORIGIN_TIME       │         │                  │ time within the     │
342       │                   │         │                  │ time window         │
343       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
344$PCP_GUIPORT       -p      --guiport        │ port for            │
345       │                   │         │                  │ connection to an    │
346       │                   │         │                  │ existing pmtime(1)
347       │                   │         │                  │ time control        │
348       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
349$PCP_START_TIME    -S      --start          │ start of the time   │
350       │                   │         │                  │ window              │
351       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
352$PCP_SAMPLES       -s      --samples        │ terminate after     │
353       │                   │         │                  │ this many samples   │
354       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
355$PCP_FINISH_TIME   -T      --finish         │ end of the time     │
356       │                   │         │                  │ window              │
357       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
358$PCP_INTERVAL      -t      --interval       │ sampling interval   │
359       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
360$PCP_TIMEZONE      -Z      --timezone       │ set reporting       │
361       │                   │         │                  │ timezone            │
362       ├───────────────────┼─────────┼──────────────────┼─────────────────────┤
363$PCP_HOSTZONE      -z      --hostzone       │ set reporting       │
364       │                   │         │                  │ timezone to local   │
365       │                   │         │                  │ time of metrics     │
366       │                   │         │                  │ source              │
367       └───────────────────┴─────────┴──────────────────┴─────────────────────┘

RETURN VALUE

369       The pmGetOptions function returns either when it detects a command-line
370       option that is not one of the standard PCP set, or when the end of  the
371       command  line options has been reached (at which point -1 is returned).
372       Both the pmgetopt_r and pmGetOptions routines  return  control  to  the
373       caller  in  the  same  way  that  a regular getopt call would, with the
374       return value indicating either the end of all processing (-1),  or  the
375       single  character form of the option currently being processed, or zero
376       for the  special  long-option-only  case.   For  all  option-processing
377       cases,  the  opts  structure  is returned containing filled out optarg,
378       opterr, optopt, optind, and index fields as  normal  (do  NOT  use  the
379       global optarg or optind from your platform C library, these will NOT be
380       modified).
381
382       pmGetOptions does not return to the caller when any of the standard PCP
383       options  are  being  processed  (although the override mechanism can be
384       used to still detect such options if needed).
385
386       The pmGetContextOptions function returns zero on success, or a negative
387       PCP  error  code on failure.  The error field within the opts parameter
388       will also be non-zero in the latter case.
389

PCP ENVIRONMENT

391       Environment variables with the prefix PCP_ are used to parameterize the
392       file  and  directory names used by PCP.  On each installation, the file
393       /etc/pcp.conf contains the  local  values  for  these  variables.   The
394       $PCP_CONF  variable may be used to specify an alternative configuration
395       file, as described in pcp.conf(5).  Values for these variables  may  be
396       obtained programmatically using the pmGetOptions(3) function.
397

SEE ALSO

399       PCPIntro(1),  pmcd(1), pminfo(1), pmstat(1), getopt(3), getopt_long(3),
400       pmNewContext(3), pmGetConfig(3), pmprintf(3), pmflush(3) and PMAPI(3).
401
402
403
404Performance Co-Pilot                  PCP                      PMGETOPTIONS(3)
Impressum