Provided by: libpcp3-dev_6.3.1-1_amd64 
NAME
pmgetopt_r, pmGetOptions, pmGetContextOptions, pmFreeOptions, pmUsageMessage - command
line handling for PMAPI tools
C SYNOPSIS
#include <pcp/pmapi.h>
int pmgetopt_r(int argc, char *const *argv, pmOptions *opts);
int pmGetOptions(int argc, char *const *argv, pmOptions *opts);
int pmGetContextOptions(int ctx, pmOptions *opts);
void pmUsageMessage(pmOptions *opts);
void pmFreeOptions(pmOptions *opts);
cc ... -lpcp
DESCRIPTION
The pmGetOptions function provides command line option processing services for both
monitor and collector PMAPI(3) tools. It is modelled on the thread-safe variants of the
GNU getopt_long(3) API, and primarily differs in its focus on providing generalised
processing for the (de-facto) standard PCP command line options described in PCPIntro(1).
These common options include the host and archive specification, time windows, timezones,
sample counts, time intervals, and so on.
The primary interface is pmGetOptions, which should be passed the argc argument count and
argv array, as passed to the main() function on program invocation. The final opts
argument describes the set of long and short options the tools is prepared to process, and
other metadata regarding how those options should be processed.
The pmgetopt_r interface, used internally by pmGetOptions, behaves in a similar fashion,
but it does not perform any common option processing. It is more suited to PCP collector
processes, whereas PCP monitor tools tend to use pmGetOptions.
The opts argument consists of an array of pmLongOpts entries describing the arguments, as
well as the enclosing pmOptions struct, which are defined as follows (internal fields are
not presented, for brevity):
typedef struct {
const char * long_opt;
int has_arg;
int short_opt;
const char * argname;
const char * message;
} pmLongOptions;
typedef struct {
int version;
int flags;
const char * short_options;
pmLongOptions * long_options;
const char * short_usage;
pmOptionOverride override;
int index;
int optind;
int opterr;
int optopt;
char *optarg;
/* [internal fields, undocumented] */
int errors;
int context; /* PM_CONTEXT_{HOST,ARCHIVE,LOCAL} */
int nhosts;
int narchives;
char ** hosts;
char ** archives;
#if PMAPI_VERSION == PMAPI_VERSION_3
struct timeval unused[4];
#else
struct timeval start;
struct timeval finish;
struct timeval origin;
struct timeval interval;
#endif
char * align_optarg;
char * start_optarg;
char * finish_optarg;
char * origin_optarg;
char * guiport_optarg;
char * timezone;
int samples;
int guiport;
int padding;
unsigned int guiflag : 1;
unsigned int tzflag : 1;
unsigned int nsflag : 1;
unsigned int Lflag : 1;
unsigned int zeroes : 28;
#if PMAPI_VERSION == PMAPI_VERSION_3
struct timespec start;
struct timespec finish;
struct timespec origin;
struct timespec interval;
#endif
} pmOptions;
The initial flags and version fields describe how the rest of the pmOptions structure is
to be interpreted. These fields can be zeroed, specifying a default interpretation.
Alternatively, the PMAPI_VERSION macro can be used to specify the API level to use
(currently, values of 3 or less are allowed). Version 2 is the default, version 3
introduces high resolution time window and interval fields (i.e. using struct timespec as
opposed to struct timeval). When using the latter form, before including <pcp/pmapi.h>
the PMAPI_VERSION macro must be set to 3 to ensure the correct layout of pmOptions
structure is used by the application. The flags field can be used to modify option
processing behaviour as described in the ``FLAGS VALUES'' section below.
The array of long_options pmLongOpts structures must be terminated by a sentinel and the
PMAPI_OPTIONS_END macro can be used to effect this termination. Individual records within
the long_options array can be of two types - options headers, or actual options. An
options header is constructed using the PMAPI_OPTIONS_HEADER macro, and is used for usage
message option grouping. Free form text can be inserted into the usage message at any
point using the PMAPI_OPTIONS_TEXT macro - this is intended for additional explanatory
text covering detailed usage that is beyond the scope of the individual headers or
options. Otherwise, the array entry specifies an option. These should be named
(long_opt) if a long-option form is allowed, specify whether or not they take an argument
(has_arg), specify the single character variant argument (short_opt) if a short-option
form is allowed, and finally specify how to present the option in the usage message. This
latter component consists of a short, one-word description of the optional argument
(argname) and a one-line description of what the command-line option does (message).
The short_usage string is also used only when constructing the usage message. It forms
the component of the usage message that follows the program name (i.e. argv[0]).
The optional short_options string is the normal getopt command-line option specification
string, using individual characters (those with arguments are designated as such using the
':' character) - as used by all getopt implementations.
A facility is provided to extend the existing set of common options with additional
options, as well as to re-task the standard options into non-standard roles for individual
tools. The latter is achieved using the override method, which allows a callback function
to be provided which will be called on receipt of every argument, prior to common
processing. If this callback returns a non-zero value the common processing will be
short-circuited for that option, otherwise processing continues. Thus, each client tool
is free to choose exactly which of the standard options they wish to support - this can be
all, some, or none, and no matter what they choose, each tool always has access to the
long option parsing capability and the usage message generation facility.
The remaining pmOptions structure fields are filled in as a result of processing the
arguments, and are largely self-explanatory. Further discussion of these is deferred to
the ``FLAGS VALUES'' section below. The error field contains a count of errors detected
during option processing. These can be either usage or runtime errors, as indicated by
the flags field (set, and passed out to the caller). Typically, a command line tool will
fail to start successfully and will produce an error message (e.g. via pmUsageMessage) if
the error field is non-zero at the end of either pmGetOptions or pmGetContextOptions.
Some command line option post-processing can only be performed once the tool has
established a PMAPI context via pmNewContext(3). This processing includes use of context-
aware timezones (-z), and time window processing (-A, -O, -S, -T) that may be affected by
the timezone, for example. The pmGetContextOptions function is available for such
situations, and it completes any remaining processing of opts with respect to the ctx
context identifier given.
The pmUsageMessage function generates a usage message for the tool, and included both
standard PCP options and custom options for each tool, as specified by the pmLongOptions
array. It supports grouping of options (via PMAPI_OPTIONS_HEADER) as well as neat
formatting of all options - short and long - their arguments, and individual explanatory
messages. It will build this usage message using pmprintf(3) upon which it will issue a
single pmflush(3) before returning to the caller, provided the PM_OPTFLAG_USAGE_ERR flag
is set in flags, which will happen automatically during option parsing, when usage errors
are detected.
In certain situations, such as recording lists of host specifications or PCP archive
paths, the pmGetOptions routine may allocate memory, and store pointers to it within opts.
Should a program wish to free this memory before exiting, it can use the pmFreeOptions
routine to do so. This is safe to call irrespective of whether memory was allocated
dynamically, provided that opts was zeroed initially.
FLAGS VALUES
PM_OPTFLAG_INIT
Used internally within the library to indicate initialisation has been done, so
that on subsequent calls it will not be done again.
PM_OPTFLAG_DONE
Used primarily internally within the library to indicate that the final option
processing has been completed. This processing involves cross-referencing a number
of the options, to check for mutual exclusion, for example. There may be other
post-processing at this stage also, provided it does not require a PMAPI context.
PM_OPTFLAG_MULTI
Allow more than one host or set of archives to be specified. The default is to
allow one source of metrics only, however some of the more sophisticated tools
permit multiple metric sources, each of which is handled within a separate context.
See also PM_OPTFLAG_MIXED.
PM_OPTFLAG_USAGE_ERR
Indicates that the library has detected a command-line usage error. This is an
error such as when an option requires an argument but none is supplied, or
conflicting options are specified (such as -s and -T).
PM_OPTFLAG_RUNTIME_ERR
Indicates that the library has detected an error at run time. This is an error
such as failing to retrieve timezone information from pmcd (1) or failing to load
an alternate metric namespace from a local file (via the -n option).
PM_OPTFLAG_EXIT
Indicates a suggestion from the library that the tool exit cleanly. This is used
when the version number is requested, for example (the -V option and PMOPT_VERSION
macro).
PM_OPTFLAG_POSIX
Use strict POSIX command line argument handling. This means options and following
arguments will not be reordered, so additional options cannot follow command line
arguments. This may be important for tools where the arguments can be negative
numbers, for example, as these should not be treated as command line options in
this case.
PM_OPTFLAG_MIXED
Allow both live and archive metric sources to be specified. The default is to
allow one type of metric context only, however some of the more sophisticated tools
permit multiple context types. See also PM_OPTFLAG_MULTI.
PM_OPTFLAG_ENV_ONLY
Many options can be specified through the either the command line or from
similarly-named environment variables. This flag disables all argument parsing,
and only changes opts based on the environment variables. This may be useful for
tools wishing to ensure no command line option conflicts occur between their own
set and the standard PCP option set (such as an existing tool, reimplemented using
PMAPI services).
PM_OPTFLAG_LONG_ONLY
Only process long options, not short options.
PM_OPTFLAG_BOUNDARIES
The default pmGetOptions behaviour is to parse the time window options (namely, -A,
-O, -S and -T), only if one of those options has been specified on the command
line. However, this flag can be used (particularly with archive contexts) to find
the start and finish times associated with the context(s) even if no time window
options were specified. In the case of multiple archives, the time window is
defined as the time window spanning all of the archives.
PM_OPTFLAG_STDOUT_TZ
The timezone being used will be reported on the standard output stream during
option parsing. The default behaviour is to not report, but simply return timezone
information via the timezone (-Z) and tzflag (-z) fields in the opts structure.
PM_OPTFLAG_NOFLUSH
The final pmflush call issued by pmUsageMessage will be skipped if this flag is
set. This is useful in situations where the caller wishes to append additional
test to the generated usage message before flushing.
PM_OPTFLAG_QUIET
Suppress messages from pmgetopt_r about unrecognised command line options. This is
the equivalent to setting the opterr field in the opt parameter (which mimics the
getopt variable of the same name).
OPTIONS VIA ENVIRONMENT VARIABLES
Some environment variables may be used as an alternative to the command line options. The
use of these mechanisms is primarily for internal use by PCP tools. General users should
choose the command line options as this provides a clearer indication of intent, makes
debugging issues easier and avoids confusion over possible conflicts between the command
line options and the environment variables (where the command line options usually
``win'').
The following table describes the environment variables that may be used to set values as
an alternative to command line options.
┌───────────────────────┬──────────────┬───────────────────────┬──────────────────────────┐
│ Environment │ Short │ Long │ Meaning │
│ │ Option │ Option │ │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_ALIGN_TIME │ -A │ --align │ align sample times │
│ │ │ │ on natural │
│ │ │ │ boundaries │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_ARCHIVE │ -a │ --archive │ metrics source is a │
│ │ │ │ PCP archive │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_ARCHIVE_LIST │ │ --archive-list │ comma-separated │
│ │ │ │ list of metric │
│ │ │ │ source archives │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_FOLIO │ │ --archive-folio │ metric source is a │
│ │ │ │ mkaf(1) archives │
│ │ │ │ folio │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_DEBUG │ -D │ --debug │ a comma-separated │
│ │ │ │ list of │
│ │ │ │ pmSetDebug(3) │
│ │ │ │ debugging options │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_GUIMODE │ -g │ --guimode │ start in GUI mode │
│ │ │ │ with new pmtime(1) │
│ │ │ │ time control │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_HOST │ -h │ --host │ metrics source is │
│ │ │ │ pmcd(1) on a host │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_HOST_LIST │ │ --host-list │ comma-separated │
│ │ │ │ list of metric │
│ │ │ │ source hosts │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_SPECLOCAL │ -K │ --spec-local │ optional additional │
│ │ │ │ DSO PMDA │
│ │ │ │ specification for │
│ │ │ │ local connection, │
│ │ │ │ see │
│ │ │ │ pmSpecLocalPMDA(3) │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_LOCALPMDA or │ -L │ --local-PMDA │ metrics source is │
│ $PCP_LOCALMODE │ │ │ local connection to │
│ │ │ │ a DSO PMDA │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_NAMESPACE │ -n │ --namespace │ use an alternative │
│ │ │ │ Performance Metrics │
│ │ │ │ Name Space (PMNS) │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_UNIQNAMES │ -N │ --uniqnames │ like -n but only │
│ │ │ │ one name allowed │
│ │ │ │ for each metric in │
│ │ │ │ the PMNS │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_ORIGIN or │ -O │ --origin │ initial sample time │
│ $PCP_ORIGIN_TIME │ │ │ within the time │
│ │ │ │ window │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_GUIPORT │ -p │ --guiport │ port for connection │
│ │ │ │ to an existing │
│ │ │ │ pmtime(1) time │
│ │ │ │ control │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_START_TIME │ -S │ --start │ start of the time │
│ │ │ │ window │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_SAMPLES │ -s │ --samples │ terminate after │
│ │ │ │ this many samples │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_FINISH_TIME │ -T │ --finish │ end of the time │
│ │ │ │ window │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_INTERVAL │ -t │ --interval │ sampling interval │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_TIMEZONE │ -Z │ --timezone │ set reporting │
│ │ │ │ timezone │
├───────────────────────┼──────────────┼───────────────────────┼──────────────────────────┤
│ $PCP_HOSTZONE │ -z │ --hostzone │ set reporting │
│ │ │ │ timezone to local │
│ │ │ │ time of metrics │
│ │ │ │ source │
└───────────────────────┴──────────────┴───────────────────────┴──────────────────────────┘
RETURN VALUE
The pmGetOptions function returns either when it detects a command-line option that is not
one of the standard PCP set, or when the end of the command line options has been reached
(at which point -1 is returned). Both the pmgetopt_r and pmGetOptions routines return
control to the caller in the same way that a regular getopt call would, with the return
value indicating either the end of all processing (-1), or the single character form of
the option currently being processed, or zero for the special long-option-only case. For
all option-processing cases, the opts structure is returned containing filled out optarg,
opterr, optopt, optind, and index fields as normal (do NOT use the global optarg or optind
from your platform C library, these will NOT be modified).
pmGetOptions does not return to the caller when any of the standard PCP options are being
processed (although the override mechanism can be used to still detect such options if
needed).
The pmGetContextOptions function returns zero on success, or a negative PCP error code on
failure. The error field within the opts parameter will also be non-zero in the latter
case.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory
names used by PCP. On each installation, the file /etc/pcp.conf contains the local values
for these variables. The $PCP_CONF variable may be used to specify an alternative
configuration file, as described in pcp.conf(5). Values for these variables may be
obtained programmatically using the pmGetOptions(3) function.
SEE ALSO
PCPIntro(1), pmcd(1), pminfo(1), pmstat(1), getopt(3), getopt_long(3), pmNewContext(3),
pmGetConfig(3), pmprintf(3), pmflush(3) and PMAPI(3).