|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | FLAGS VALUES | OPTIONS VIA ENVIRONMENT VARIABLES | COMPATIBILITY | RETURN VALUE | PCP ENVIRONMENT | SEE ALSO | COLOPHON |
|
|
|
PMGETOPTIONS(3) Library Functions Manual PMGETOPTIONS(3)
pmgetopt_r, pmGetOptions, pmGetContextOptions, pmFreeOptions,
pmUsageMessage - command line handling for PMAPI tools
#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
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() func‐
tion 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 de‐
scribing 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;
struct timespec start;
struct timespec finish;
struct timespec origin;
struct timespec interval;
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;
} pmOptions;
The initial flags and version fields describe how the rest of the
pmOptions structure is to be interpreted. These fields can be ze‐
roed, 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 in‐
terval 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 applica‐
tion. The flags field can be used to modify option processing be‐
haviour 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 ef‐
fect 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 ex‐
planatory 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 argu‐
ment (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 com‐
ponent 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 us‐
age 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 ':' charac‐
ter) - as used by all getopt implementations.
A facility is provided to extend the existing set of common op‐
tions 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 detect‐
ed 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 ei‐
ther 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 pro‐
cessing 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 sup‐
ports 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_OPT‐
FLAG_USAGE_ERR flag is set in flags, which will happen automati‐
cally during option parsing, when usage errors are detected.
In certain situations, such as recording lists of host specifica‐
tions 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 pmFreeOp‐
tions routine to do so. This is safe to call irrespective of
whether memory was allocated dynamically, provided that opts was
zeroed initially.
PM_OPTFLAG_INIT
Used internally within the library to indicate initialisa‐
tion 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 op‐
tions, 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 speci‐
fied. The default is to allow one source of metrics only,
however some of the more sophisticated tools permit multi‐
ple metric sources, each of which is handled within a sepa‐
rate context. See also PM_OPTFLAG_MIXED.
PM_OPTFLAG_USAGE_ERR
Indicates that the library has detected a command-line us‐
age error. This is an error such as when an option re‐
quires an argument but none is supplied, or conflicting op‐
tions 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 time‐
zone information from pmcd(1) or failing to load an alter‐
nate metric namespace from a local file (via the -n op‐
tion).
PM_OPTFLAG_EXIT
Indicates a suggestion from the library that the tool exit
cleanly. This is used when the version number is request‐
ed, 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 re‐
ordered, so additional options cannot follow command line
arguments. This may be important for tools where the argu‐
ments 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 multi‐
ple context types. See also PM_OPTFLAG_MULTI.
PM_OPTFLAG_ENV_ONLY
Many options can be specified through the either the com‐
mand 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 use‐
ful for tools wishing to ensure no command line option con‐
flicts occur between their own set and the standard PCP op‐
tion 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. How‐
ever, this flag can be used (particularly with archive con‐
texts) to find the start and finish times associated with
the context(s) even if no time window options were speci‐
fied. 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 com‐
mand line options. This is the equivalent to setting the
opterr field in the opt parameter (which mimics the getopt
variable of the same name).
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 in‐
tent, makes debugging issues easier and avoids confusion over pos‐
sible conflicts between the command line options and the environ‐
ment 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 │
│ $PCP_ORIGIN_TIME │ │ │ 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 │
└───────────────────┴────────┴─────────────────┴────────────────────┘
Prior to PCP 7.0 and libpcp.so.4 the start, finish, origin and in‐
terval members of the pmOptions struct were struct timevals. To
support PMAPI transition, the old interfaces and semantics can be
used if applications are linked with libpcp.so.3 or recompiled
with -DPMAPI_VERSION=2.
The pmGetOptions function returns either when it detects a com‐
mand-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 rou‐
tines 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-on‐
ly 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 stan‐
dard PCP options are being processed (although the override mecha‐
nism 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.
Environment variables with the prefix PCP_ are used to parameter‐
ize the file and directory names used by PCP. On each installa‐
tion, the file /etc/pcp.conf contains the local values for these
variables. The $PCP_CONF variable may be used to specify an al‐
ternative configuration file, as described in pcp.conf(5). Values
for these variables may be obtained programmatically using the
pmGetOptions(3) function.
PCPIntro(1), pmcd(1), pminfo(1), pmstat(1), getopt(3),
getopt_long(3), pmNewContext(3), pmGetConfig(3), pmprintf(3),
pmflush(3) and PMAPI(3).
This page is part of the PCP (Performance Co-Pilot) project. In‐
formation about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-08-11.) If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page,
or you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a
mail to man-pages@man7.org
Performance Co-Pilot PCP PMGETOPTIONS(3)
Pages that refer to this page: chkhelp(1), collectl2pcp(1), dbpmda(1), newhelp(1), pcp(1), pcp2arrow(1), pcp2elasticsearch(1), pcp2graphite(1), pcp2influxdb(1), pcp2json(1), pcp2openmetrics(1), pcp2spark(1), pcp2template(1), pcp2xlsx(1), pcp2xml(1), pcp2zabbix(1), pcp-atop(1), pcp-atopsar(1), pcp-buddyinfo(1), pcp-dmcache(1), pcp-dstat(1), pcp-free(1), pcpintro(1), pcp-iostat(1), pcp-ipcs(1), pcp-meminfo(1), pcp-mpstat(1), pcp-netstat(1), pcp-numastat(1), pcp-pidstat(1), pcp-ps(1), pcp-rocestat(1), pcp-slabinfo(1), pcp-ss(1), pcp-tapestat(1), pcp-uptime(1), pcp-verify(1), pcp-xsos(1), pcp-zoneinfo(1), pmcd(1), pmclient(1), pmcpp(1), pmdbg(1), pmdumptext(1), pmgetopt(1), pminfo(1), pmlogextract(1), pmlogrewrite(1), pmprobe(1), pmproxy(1), pmrep(1), pmsearch(1), pmseries(1), pmstat(1), pmval(1), sar2pcp(1), sheet2pcp(1), pmdagetoptions(3), pmgetoptions(3), pmsetdebug(3), pcp-dstat(5), pmrep.conf(5)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|