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  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
196       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
202       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
208       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
213       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
221       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
227       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
236       PM_OPTFLAG_LONG_ONLY
237              Only process long options, not short options.
238
239       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
249       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
255       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
261       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

RETURN VALUE

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
281       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
285       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

PCP ENVIRONMENT

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

SEE ALSO

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).
300
301
302
303Performance Co-Pilot                  PCP                      PMGETOPTIONS(3)
Impressum