--- name: "pmGetOptions" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmgetopt_r" --- # pmGetOptions(3) command line handling for PMAPI tools Part of [pmgetopt\_r(3)](/pmgetopt_r/3.md). ## NAME **pmgetopt\_r**, **pmGetOptions**, **pmGetContextOptions**, **pmFreeOptions**, **pmUsageMessage** - command line handling for PMAPI tools ## C SYNOPSIS **#include \** **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)](/PMAPI/3.md) tools. It is modelled on the thread-safe variants of the GNU [**getopt\_long**(3)](/getopt_long/3.md) API, and primarily differs in its focus on providing generalised processing for the (de-facto) standard PCP command line options described in [**PCPIntro**(1)](/PCPIntro/1.md). 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; 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 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 \ 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)](/pmNewContext/3.md). 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)](/pmprintf/3.md) upon which it will issue a single [**pmflush**(3)](/pmflush/3.md) 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 | a comma-separated list of metric source archives | | $PCP\_FOLIO | | --archive-folio | the metric source is a [**mkaf**(1)](/mkaf/1.md) archives folio | | $PCP\_DEBUG | -D | --debug | a comma-separated list of [**pmSetDebug**(3)](/pmSetDebug/3.md) debugging options | | $PCP\_GUIMODE | -g | --guimode | start in GUI mode with new [**pmtime**(1)](/pmtime/1.md) time control | | $PCP\_HOST | -h | --host | metrics source is [**pmcd**(1)](/pmcd/1.md) on a host | | $PCP\_HOST\_LIST | | --host-list | a comma-separated list of metric source hosts | | $PCP\_SPECLOCAL | -K | --spec-local | optional extra local context PMDA DSO information | | $PCP\_LOCALPMDA or $PCP\_LOCALMODE | -L | --local-PMDA | metrics source is local connection to a DSO PMDA | | $PCP\_NAMESPACE | -n | --namespace | use alternative PMNS (Perform-ance Metrics Name Space) | | $PCP\_UNIQNAMES | -N | --uniqnames | like **-n** but only one name allowed for each metric in the PMNS | | $PCP\_ORIGIN or $PCP\_ORIGIN\_TIME | -O | --origin | initial sample time within the time window | | $PCP\_GUIPORT | -p | --guiport | port of existing [**pmtime**(1)](/pmtime/1.md) 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 | sample interval | | $PCP\_TIMEZONE | -Z | --timezone | set reporting timezone | | $PCP\_HOSTZONE | -z | --hostzone | set reporting timezone to local time of metrics source | ## COMPATIBILITY Prior to PCP 7.0 and *libpcp.so.4* the *start*, *finish*, *origin* and *interval* members of the *pmOptions* struct were `struct timeval`s. 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**. ## 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)](/pcp.conf/5.md). Values for these variables may be obtained programmatically using the [**pmGetOptions**(3)](/pmGetOptions/3.md) function. ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pminfo**(1)](/pminfo/1.md), [**pmstat**(1)](/pmstat/1.md), [**getopt**(3)](/getopt/3.md), [**getopt\_long**(3)](/getopt_long/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pmprintf**(3)](/pmprintf/3.md), [**pmflush**(3)](/pmflush/3.md) and [**PMAPI**(3)](/PMAPI/3.md).