# pmgetoptions

## 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()_  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.
    


## FLAGS VALUES



           **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).
    


## 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 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             │
          └───────────────────┴────────┴─────────────────┴────────────────────┘
    


## COMPATIBILITY



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


## RETURN VALUE



           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.
    


## PCP ENVIRONMENT



           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.
    


* * *