diff options
Diffstat (limited to 'man/man3/pmgetoptions.3')
| -rw-r--r-- | man/man3/pmgetoptions.3 | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/man/man3/pmgetoptions.3 b/man/man3/pmgetoptions.3 new file mode 100644 index 0000000..a713b2b --- /dev/null +++ b/man/man3/pmgetoptions.3 @@ -0,0 +1,481 @@ +.\" +.\" Copyright (c) 2014 Red Hat. +.\" +.\" This program is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2 of the License, or (at your +.\" option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.TH PMGETOPTIONS 3 "PCP" "Performance Co-Pilot" +.SH NAME +\f3pmgetopt_r\f1, +\f3pmGetOptions\f1, +\f3pmGetContextOptions\f1, +\f3pmFreeOptions\f1, +\f3pmUsageMessage\f1 \- command line handling for PMAPI tools +.SH "C SYNOPSIS" +.ft 3 +#include <pcp/pmapi.h> +.sp +.br +int pmgetopt_r(int \fIargc\fP, char *const *\fIargv\fP, pmOptions *\fIopts\fP); +.br +int pmGetOptions(int \fIargc\fP, char *const *\fIargv\fP, pmOptions *\fIopts\fP); +.br +int pmGetContextOptions(int \fIctx\fP, pmOptions *\fIopts\fP); +.br +void pmUsageMessage(pmOptions *\fIopts\fP); +.br +void pmFreeOptions(pmOptions *\fIopts\fP); +.fi +.sp +cc ... \-lpcp +.ft 1 +.SH DESCRIPTION +The +.B pmGetOptions +function provides command line option processing services for both +monitor and collector +.BR PMAPI (3) +tools. +It is modelled on the thread-safe variants of the GNU +.BR 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 +.BR PCPIntro (1). +These common options include the host and archive specification, +time windows, timezones, sample counts, time intervals, and so on. +.PP +The primary interface is +.BR pmGetOptions , +which should be passed the +.I argc +argument count and +.I argv +array, as passed to the +.IR main() +function on program invocation. +The final +.I 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. +.PP +The +.B pmgetopt_r +interface, used internally by +.BR 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 +.BR pmGetOptions . +.PP +The +.I opts +argument consists of an array of +.I pmLongOpts +entries describing the arguments, as well as the enclosing +.I pmOptions +struct, which are defined as follows (internal fields are not +presented, for brevity): +.PP +.sp 0.5v +.ft CW +.nf +.in +0.25i +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 timeval start; + struct timeval finish; + struct timeval origin; + struct timeval 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; +.in -0.25i +.fi +.ft R +.PP +The initial +.I flags +and +.I 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 2 or less are allowed). +The +.I flags +field can be used to modify option processing behaviour as +described in the ``FLAGS VALUES'' section below. +.PP +The array of +.I 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 +.I 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 (\c +.IR long_opt ) +if a long-option form is allowed, +specify whether or not they take an argument (\c +.IR has_arg ), +specify the single character variant argument (\c +.IR 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 (\c +.IR argname ) +and a one-line description of what the command-line option does (\c +.IR message ). +.PP +The +.I 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. \c +.IR argv[0] ). +.PP +The optional +.I short_options +string is the normal +.I getopt +command-line option specification string, using individual +characters (those with arguments are designated as such +using the ':' character) \- as used by all +.I getopt +implementations. +.PP +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 +.I 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, aach 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. +.PP +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 +.I error +field contains a count of errors detected during option processing. +These can be either usage or runtime errors, as indicated by the +.I 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 +.BR pmUsageMessage ) +if the +.I error +field is non-zero at the end of either +.B pmGetOptions +or +.BR pmGetContextOptions . +.PP +Some command line option post-processing can only be performed once +the tool has established a PMAPI context via +.BR pmNewContext (3). +This processing includes use of context-aware timezones (\f3\-z\f1), +and time window processing (\f3\-A\f1, \f3\-O\f1, \f3\-S\f1, \f3\-T\f1) +that may be affected by the timezone, for example. +The +.B pmGetContextOptions +function is available for such situations, and it completes any +remaining processing of +.I opts +with respect to the +.I ctx +context identifier given. +.PP +The +.B 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 +.BR pmprintf (3) +upon which it will issue a single +.BR pmflush (3) +before returning to the caller, provided the PM_OPTFLAG_USAGE_ERR +flag is set in +.IR flags , +which will happen automatically during option parsing, when usage +errors are detected. +.PP +In certain situations, such as recording lists of host specifications +or PCP archive paths, the +.B pmGetOptions +routine may allocate memory, and store pointers to it within +.IR opts . +Should a program wish to free this memory before exiting, it can +use the +.B pmFreeOptions +routine to do so. +This is safe to call irrespective of whether memory was allocated +dynamically, provided that +.I opts +was zeroed initially. +.SH "FLAGS VALUES" +.TP +.B 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. +.TP +.B 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. +.TP +.B PM_OPTFLAG_MULTI +Allow more than one host or archive to be specified. +The default is to allow one source of metrics only, however some of the +more sophisticated tools permit multiple metric sources. +See also +.BR PM_OPTFLAG_MIXED . +.TP +.B 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 \f3\-s\f1 +and \f3-T\f1). +.TP +.B 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 +.B pmcd (1) +or +failing to load an alternate metric namespace from a local file +(via the \f3-n\f1 option). +.TP +.B 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 +\f3\-V\f1 option and PMOPT_VERSION macro). +.TP +.B 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. +.TP +.B 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 +.BR PM_OPTFLAG_MULTI . +.TP +.B 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 +.I 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). +.TP +.B PM_OPTFLAG_LONG_ONLY +Only process long options, not short options. +.TP +.B PM_OPTFLAG_BOUNDARIES +The default +.B pmGetOptions +behaviour is to parse the time window options (namely, \f3\-A\f1, +\f3\-O\f1, \f3\-S\f1 and \f3\-T\f1), 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 +.I start +and +.I 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. +.TP +.B 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 +.I timezone +(\f3\-Z\f1) +and +.I tzflag +(\f3\-z\f1) +fields in the +.I opts +structure. +.TP +.B PM_OPTFLAG_NOFLUSH +The final +.B pmflush +call issued by +.B 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. +.TP +.B PM_OPTFLAG_QUIET +Suppress messages from +.B pmgetopt_r +about unrecognised command line options. +This is the equivalent to setting the +.I opterr +field in the +.I opt +parameter (which mimics the +.B getopt +variable of the same name). +.SH "RETURN VALUE" +The +.B 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 +.B pmgetopt_r +and +.B pmGetOptions +routines return control to the caller in the same way that a regular +.B 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 +.I opts +structure is returned containing filled out +.IR optarg , +.IR opterr , +.IR optopt , +.IR optind , +and +.I index +fields as normal (do +.B NOT +use the global optarg or optind from your platform C library, +these will +.B NOT +be modified). +.PP +.B pmGetOptions +does not return to the caller when any of the standard PCP options are +being processed (although the +.I override +mechanism can be used to still detect such options if needed). +.PP +The +.B pmGetContextOptions +function returns zero on success, or a negative PCP error code +on failure. +The +.I error +field within the +.I +opts +parameter will also be non-zero in the latter case. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (5). +Values for these variables may be obtained programmatically +using the +.BR pmGetOptions (3) +function. +.SH SEE ALSO +.BR PCPIntro (1), +.BR pmcd (1), +.BR pminfo (1), +.BR pmstat (1), +.BR getopt (3), +.BR getopt_long (3), +.BR pmNewContext (3), +.BR pmconfig (3), +.BR pmprintf (3), +.BR pmflush (3) +and +.BR PMAPI (3). |