1PMGETOPT(1)                 General Commands Manual                PMGETOPT(1)
2
3
4

NAME

6       pmgetopt - Performance Co-Pilot shell script option parser
7

SYNOPSIS

9       $PCP_BINADM_DIR/pmgetopt [-u?]  [-c file] [-p name] [--] [parameters]
10

DESCRIPTION

12       pmgetopt  is  used  to  perform  command  line option parsing for shell
13       scripts used in the Performance Co-Pilot (PCP  toolkit).   It  is  also
14       used to generate usage messages for those scripts.
15
16       The  parameters  given  to  pmgetopt take two forms: initially, options
17       specific to pmgetopt itself are passed in, and terminated using the  --
18       mechanism.   Thereafter,  all  of  the parameters passed into the shell
19       script should be passed (usually this is simply the "$@" variable).
20

OPTIONS

22       The options specific to pmgetopt are as follows:
23
24       -c=file, --config=file
25            A configuration file in the format described below  is  passed  to
26            pmconfig  using  this  option.   If  this  option is omitted, then
27            pmconfig will read  its  configuration  from  the  standard  input
28            stream.
29
30       -p=name, --progname=name
31            When parsing the calling shell scripts parameters, error and usage
32            messages will contain the given program name rather than referring
33            to pmgetopt itself as the source of the error.
34
35       -u, --usage
36            A  usage  message  appropriate  for  the  calling  shell script to
37            present as its own can be generated using the option.
38
39       -?, --help
40            Display the usage message for pmgetopt itself and exit.
41
42       pmgetopt parses the given parameters, and produces output in  a  format
43       suitable for sourcing in the calling shell script.  When both short and
44       long forms of an argument are allowed by  the  specification,  pmgetopt
45       will  always  indicate the short form for simpler shell processing.  If
46       arguments are presented that do not match the configuration, a  request
47       for  a  usage  message (-?) will be generated for the calling script to
48       respond to.  Any non-option parameters will be echoed back to the call‐
49       ing  script  preceded  by  the  double-hyphen delimiter.  Thus a script
50       should stop handling options when this delimiter is detected, and begin
51       the handling of any non-option arguments.
52
53       Unlike  with  the shell built-in getopt command, variables like $OPTARG
54       are not set and the calling script will typically  employ  use  of  the
55       shell built-in eval, set and positional shift commands to ensure option
56       processing occurs correctly.
57

CONFIGURATION

59       The configuration format  used  by  pmgetopt  is  intended  to  closely
60       reflect  the  usage message which would be generated in the presence of
61       invalid arguments (or the -?, --help option).
62
63       There are primarily two types of  configuration  line  -  commands  and
64       options.  Commands allow metadata to be passed into the option process‐
65       ing process, and options are the allowable command  line  options  that
66       the  shell  script will accept.  Command lines are preceded by the hash
67       character, whereas option lines will always begin with a hyphen (either
68       single  or  double).   Any  other  line in the configuration, which may
69       include usage headers or descriptive text, has no impact on the  option
70       parsing and will be copied unmodified into the usage message.
71
72       The  set of commands is: getopt (provide short-argument option specifi‐
73       cation manually, if not present this will be generated from the options
74       presented),  usage  (provide short one-line summary used at the head of
75       the usage message, which  will  be  prefixed  by  the  progname  before
76       reporting),  and  end which informs pmgetopt to stop processing further
77       commands and options - any subsequent text encountered will  be  simply
78       appended to the usage message.
79
80       A  short-hand  notation exists for each of the standard PCP options, as
81       described in PCPIntro(1).  If any of these options (e.g --host) appears
82       as a single word on any line, it will be transformed into the appropri‐
83       ate option for the shell script,  including  all  metadata  about  that
84       option  (whether  it  accepts  an  argument, both short and long option
85       forms, and so on).
86
87       Use of the equals symbol ("=") indicates the  presence  of  a  required
88       argument  to  any option, for both short and long forms.  Any non-stan‐
89       dard option must be accompanied by  a  non-empty  description  of  that
90       argument.
91

EXAMPLES

93       As an example, the following is a valid configuration:
94
95            # Usage: [options] node...
96
97            Options:
98                --archive
99                -d, --delay            pause between updates for archive replay
100                --host
101                --interval
102                -i=INST, --insts=INST  comma-separated metrics instance list
103                -r                     output raw counters (no rate conversion)
104                --width=N              set the width of each column of output
105                --timezone
106                --help
107
108
109       This  configuration  will produce the following usage message, when run
110       as shown.
111
112            $ pmgetopt --usage --progname=clusterstat -- "$@"
113            Usage: clusterstat [options] node...
114
115            Options:
116              -a FILE, --archive=FILE
117                                    metrics source is a PCP log archive
118              -d, --delay           pause between updates for archive replay
119              -h HOST, --host=HOST  metrics source is PMCD on host
120              -t DELTA, --interval=DELTA
121                                    sampling interval
122              -i INST, --insts=INST comma-separated metrics instance list
123              -r                    output raw counters (no rate conversion)
124              --width=N             set the width of each column of output
125              -Z TZ, --timezone=TZ  set reporting timezone
126              -?, --help            show this usage message and exit
127
128
129       Several examples of pmgetopt use form part of the PCP toolkit, in  par‐
130       ticular  the pcp(1) and pmlogmv(1) scripts provide good reference exam‐
131       ples.
132

PCP ENVIRONMENT

134       Environment variables with the prefix PCP_ are used to parameterize the
135       file  and  directory names used by PCP.  On each installation, the file
136       /etc/pcp.conf contains the  local  values  for  these  variables.   The
137       $PCP_CONF  variable may be used to specify an alternative configuration
138       file, as described in pcp.conf(5).
139

SEE ALSO

141       pcp(1), pmlogmv(1), pmgetopt_r(3), pcp.conf(5) and pcp.env(5).
142
143
144
145Performance Co-Pilot                  PCP                          PMGETOPT(1)
Impressum