Provided by: libpcp3-dev_4.0.1-1_amd64 bug

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;
             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.

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   │
       │  $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).