1PMDISCOVERSERVICES(3) Library Functions Manual PMDISCOVERSERVICES(3)
2
6 pmDiscoverServices - discover PCP services on the network
7
9 #include <pcp/pmapi.h>
10 int pmDiscoverServices(const char *service, const char *mechanism, char ***urls);
12 #include <pcp/libpcp.h>
14 int __pmDiscoverServicesWithOptions(const char *service, const char *mechanism, const char *optionsString, const volatile unsigned *flags, char ***urls);
16 cc ... -lpcp
18
20 This documentation is intended for internal Performance Co-Pilot (PCP)
21 developer use.
22 These interfaces are not part of the PCP APIs that are guaranteed to
24 remain fixed across releases, and they may not work, or may provide
25 different semantics at some point in the future.
26
28 Given a PCP service name, as identified by service, and using the type
29 of discovery optionally specified in mechanism, pmDiscoverServices
30 returns, via urls, a list of URLs representing the services discovered
31 on the network.
32 The internal function __pmDiscoverServicesWithOptions performs the same
34 function and adds arguments for global options and a mechanism for
35 interrupting the discovery process.
36 The pmfind(1) utility provides command line access to both of these
38 interfaces.
39 Calling
41 pmDiscoverServices(service, mechanism, urls)
43 is equivalent to calling
45 __pmDiscoverServicesWithOptions(service, mechanism, NULL, NULL, urls);
47 service specifies the PCP service to be discovered. Currently sup‐
49 ported services are PM_SERVER_SERVICE_SPEC and PM_PROXY_SERVICE_SPEC
50 which search for pmcd(1), and pmproxy(1) servers respectively.
51 mechanism specifies the style of discovery to be used.
53 The currently supported mechanisms are:
55 avahi This searches for services which are broadcasting using mDNS via
57 avahi-daemon(8). An optional suffix ",timeout=N" may be added
58 to specify the discovery timeout in floating-point multiples of
59 one second. The default timeout is 0.5 seconds, which may be
60 overridden by the AVAHI_DISCOVERY_TIMEOUT environment variable,
61 also specified in floating-point multiples of one second. If
62 both are specified, then the value specified in the environment
63 variable takes precedence.
64 probe=<net-address>/<mask-bits>
66 Actively probes the given subnet for the requested PCP ser‐
67 vice(s). <net-address> is an inet or ipv6 network address and
68 <mask-bits> is the number of bits used to define the subnet.
69 For example, 192.168.1.0/24 defines an 8 bit subnet consisting
70 of the addresses 192.168.1.0 through 192.168.1.255. An optional
71 suffix ",maxThreads=N" may be added to limit the number of
72 threads used while probing. The default is the value of FD_SET‐
73 SIZE (which is typically 1024) or the number of addresses in the
74 subnet, whichever is less. An optional suffix ",timeout=N" may
75 be added to specify the timeout for each connection attempt in
76 floating-point multiples of one second. The default is 0.02
77 seconds (20 milliseconds).
78 shell Probes the list of addresses provided by scripts for requested
80 PCP service(s). Several optional, comma-separated parameters
81 can also be provided. Firstly, the "path=DIR" option specifies
82 the directory where commands like pcp-kube-pods(1) are located
83 (defaults to $PCP_BINADM_DIR/discover/). This setting can be
84 further restricted to an individual command using the com‐
85 mand=CMD option, but the default is to use all available com‐
86 mands from the path. The "maxThreads=N" option limits the num‐
87 ber of threads used while probing. The default is the value of
88 FD_SETSIZE (which is typically 1024) or the number of addresses
89 returned by the scripts, whichever is less. The "timeout=N"
90 option may be added to limit the amount of time spent waiting
91 for each connection attempt. N is a floating point number spec‐
92 ifying the number of seconds to wait. The default is 0.02 sec‐
93 onds (20 milliseconds).
94 mechanism may also be NULL, which means to use all available discovery
96 mechanisms.
97 For __pmDiscoverServicesWithOptions, optionsString specifies global
99 options to be applied to the discovery process. Options are comma-sep‐
100 arated and may be one or more of the following:
101 resolve
103 This requests that DNS name resolution be attempted for the
104 addresses of any discovered services.
105 timeout=N
107 This specifies a timeout period after which the discovery
108 process will be interrupted. N is a floating point number rep‐
109 resenting the number of seconds before timing out.
110 optionsString may also be NULL, which means that no global options are
112 specified.
113 For __pmDiscoverServicesWithOptions, flags specifies a pointer to an
115 object of type unsigned which is a bit mask of options/status flags for
116 the discovery process. The supported flags are:
117 PM_SERVICE_DISCOVERY_RESOLVE
119 Specifying this flag is equivalent to specifying resolve in the
120 optionsString
121 PM_SERVICE_DISCOVERY_INTERRUPTED
123 This flag must be unset when calling __pmDiscoverServicesWithOp‐
124 tions but may be set asynchronously (by an interrupt handler,
125 for example) in order to interrupt the service discovery
126 process.
127 flags may also be NULL, which indicates that no flags are set.
129 pmDiscoverServices and __pmDiscoverServicesWithOptions will return the
131 number of services discovered, else a value less than zero for an
132 error. The value zero indicates that no services were discovered.
133 The resulting list of pointers, urls, and the values (the URLs) that
135 the pointers reference will have been allocated by pmDiscoverServices
136 or __pmDiscoverServicesWithOptions with a single call to malloc(3), and
137 it is the responsibility of the pmDiscoverServices or __pmDiscoverSer‐
138 vicesWithOptions caller to free(urls) to release the space when it is
139 no longer required.
140 When an error occurs, or no services are discovered, urls is undefined
142 (no space will have been allocated, and so calling free(3) is a singu‐
143 larly bad idea).
144
146 Environment variables with the prefix PCP_ are used to parameterize the
147 file and directory names used by PCP. On each installation, the file
148 /etc/pcp.conf contains the local values for these variables. The
149 $PCP_CONF variable may be used to specify an alternative configuration
150 file, as described in pcp.conf(5). Values for these variables may be
151 obtained programmatically using the pmGetConfig(3) function.
152
154 pmcd(1), pmfind(1), pmproxy(1), pcp-kube-pods(1), PMAPI(3), pmGetCon‐
155 fig(3), pcp.conf(5), pcp.env(5) and avahi-daemon(8).
156
158 -EINVAL
159 An invalid argument has been specified.
160 -ENOMEM
162 Unable to allocate memory required to process the request.
163 -EOPNOTSUPP
165 The specified mechanism is not supported.
166Performance Co-Pilot PCP PMDISCOVERSERVICES(3)