обработка командной строки для инструментов PMAPI (command line handling for PMAPI tools)
Имя (Name)
pmgetopt_r, pmGetOptions, pmGetContextOptions, pmFreeOptions,
pmUsageMessage - command line handling for PMAPI tools
Описание (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;
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;
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 2 or less are allowed). 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,
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.
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.
