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/pmda.h>
12
13       int pmdaGetOptions(int argc, char *const *argv, pmdaOptions *opts,
14               pmdaInterface *dispatch);
15
16       int pmdaGetOpt(int argc, char *const *argv, const char *optstring,
17               pmdaInterface *dispatch, int *err);
18
19       cc ... -lpcp_pmda -lpcp
20

DESCRIPTION

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

DIAGNOSTICS

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

CAVEAT

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

NAME

C SYNOPSIS

DESCRIPTION

DIAGNOSTICS

CAVEAT

SEE ALSO