pmdagetoptions(3)

1PMDAGETOPTIONS(3)          Library Functions Manual          PMDAGETOPTIONS(3)
2
3
4

NAME

6       pmdaGetOpt,  pmdaGetOptions  -  get  options  from  arguments,  parsing
7       generic PMDA options
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/impl.h>
12       #include <pcp/pmda.h>
13
14       int pmdaGetOptions(int argc, char *const *argv, pmdaOptions *opts,
15               pmdaInterface *dispatch);
16
17       int pmdaGetOpt(int argc, char *const *argv, const char *optstring,
18               pmdaInterface *dispatch, int *err);
19
20       cc ... -lpcp_pmda -lpcp
21

DESCRIPTION

23       These functions are wrappers for pmgetopt_r(3).  The behavior  of  each
24       function  is  that certain options are assumed to have a predefined be‐
25       havior which initializes several fields in the pmdaInterface structure.
26       The  pmdaGetOptions  interface allows both short and long options to be
27       given, whereas pmdaGetOpt allows for short form options only.
28
29       The options that both pmdaGetOptions and pmdaGetOpt will trap are:
30
31       -Dtrace        Set the PMAPI(3) debug  control  variable  (pmDebug)  to
32                      trace.   Used  for  controlling  levels  of trace output
33                      while debugging.
34
35       -ddomain       Set the domain number of this agent.
36
37       -hhelpfile     Obtain the help text (see pmdaText(3)) for  the  metrics
38                      from  this file rather than from the path specified with
39                      pmdaDSO(3) or pmdaDaemon(3).
40
41       -iport         Expect PMCD to connect on inet port (number or name).
42
43       -6port         Expect PMCD to connect on ipv6 port (number or name).
44
45       -llogfile      Redirect diagnostics and trace output to logfile.
46
47       -p             Expect PMCD to supply stdin/stdout pipe.
48
49       -usocket       Expect PMCD to connect on unix domain socket.
50
51       The pmdaGetOptions interface will also capture the  following  options,
52       and store them within the opts parameter:
53
54       -Uusername     Set  the  user  account name under which the PMDA should
55                      execute.
56
57       Only one of -i, -6, -p and -u may be specified.  If none of these three
58       options  is  given, a pipe (-p) is assumed.  When these options are en‐
59       countered by pmdaGetOpt, the option is processed and the next option is
60       examined.   Therefore, pmdaGetOpt will only return when an option other
61       than those listed above is found, or the end of the  list  is  reached.
62       The returned value will be the argument or EOF, respectively.
63
64       A  PMDA can control which of these options the program will accept with
65       either the opts or optstring argument.  To accept all the options,  the
66       PMDA  should  call  pmdaGetOptions  with the short_options field of the
67       opts structure set to the PMDA_OPTIONS macro, or  pmdaGetOpt  with  the
68       option  string  "D:d:h:i:l:pu:".   Any  PMDA specific options should be
69       added to these strings in the style of getopt(3), and will be  returned
70       by both pmdaGetOptions and pmdaGetOpt if encountered.
71
72       When  a  command  line option usage error is detected in the pmdaGetOp‐
73       tions interface, the error field of the opts structure will  contain  a
74       non-zero error count.
75
76       pmdaGetOpt  takes  a  pointer to an int, err, which is used as an error
77       count.  This variable should be initialized to zero  before  pmdaGetOpt
78       is first called, and tested when pmdaGetOpt returns EOF.
79
80       Neither pmdaGetOptions nor pmdaGetOpt modify their argc or argv parame‐
81       ters.
82
83       The global variables used by the system getopt (3) interface  may  also
84       be used by the caller of pmdaGetOpt within the argument parsing loop.
85
86       On the other hand, the pmdaGetOptions interface does not utilize global
87       variables at all (neither reading nor modifying them).  Instead,  these
88       variables can be access via the opts fields of the same name.
89

DIAGNOSTICS

91       Both pmdaGetOptions and pmdaGetOpt will display the same error messages
92       as getopt.
93

CAVEAT

95       The options -D, -d, -i, -l, -p and -u cannot be reused for  other  pur‐
96       poses  by  the  PMDA,  unless using the override method provided by the
97       pmdaGetOptions interface, which operates in the same way  as  described
98       for the pmGetOptions(3) interface used by PMAPI client tools.
99
100       The  PMDA  must be using PMDA_INTERFACE_2 or later, as specified in the
101       call to pmdaDSO(3) or pmdaDaemon(3).
102

NAME

C SYNOPSIS

DESCRIPTION

DIAGNOSTICS

CAVEAT

SEE ALSO