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, PM_PROXY_SERVICE_SPEC and
50 PM_WEBD_SERVICE_SPEC, which search for pmcd(1), pmproxy(1), and
51 pmwebd(1), servers respectively.
52 mechanism specifies the style of discovery to be used.
54 The currently supported mechanisms are:
56 avahi This searches for services which are broadcasting using mDNS via
58 avahi-daemon(8). An optional suffix ",timeout=N" may be added
59 to specify the discovery timeout in floating-point multiples of
60 one second. The default timeout is 0.5 seconds, which may be
61 overridden by the AVAHI_DISCOVERY_TIMEOUT environment variable,
62 also specified in floating-point multiples of one second. If
63 both are specified, then the value specified in the environment
64 variable takes precedence.
65 probe=<net-address>/<mask-bits>
67 Actively probes the given subnet for the requested PCP ser‐
68 vice(s). <net-address> is an inet or ipv6 network address and
69 <mask-bits> is the number of bits used to define the subnet.
70 For example, 192.168.1.0/24 defines an 8 bit subnet consisting
71 of the addresses 192.168.1.0 through 192.168.1.255. An optional
72 suffix ",maxThreads=N" may be added to limit the number of
73 threads used while probing. The default is the value of FD_SET‐
74 SIZE (which is typically 1024) or the number of addresses in the
75 subnet, whichever is less. An optional suffix ",timeout=N" may
76 be added to specify the timeout for each connection attempt in
77 floating-point multiples of one second. The default is 0.02
78 seconds (20 milliseconds).
79 shell Probes the list of addresses provided by scripts for requested
81 PCP service(s). Several optional, comma-separated parameters
82 can also be provided. Firstly, the "path=DIR" option specifies
83 the directory where commands like pcp-kube-pods(1) are located
84 (defaults to $PCP_BINADM_DIR/discover/). This setting can be
85 further restricted to an individual command using the com‐
86 mand=CMD option, but the default is to use all available com‐
87 mands from the path. The "maxThreads=N" option limits the num‐
88 ber of threads used while probing. The default is the value of
89 FD_SETSIZE (which is typically 1024) or the number of addresses
90 returned by the scripts, whichever is less. The "timeout=N"
91 option may be added to limit the amount of time spent waiting
92 for each connection attempt. N is a floating point number spec‐
93 ifying the number of seconds to wait. The default is 0.02 sec‐
94 onds (20 milliseconds).
95 mechanism may also be NULL, which means to use all available discovery
97 mechanisms.
98 For __pmDiscoverServicesWithOptions, optionsString specifies global
100 options to be applied to the discovery process. Options are comma-sep‐
101 arated and may be one or more of the following:
102 resolve
104 This requests that DNS name resolution be attempted for the
105 addresses of any discovered services.
106 timeout=N
108 This specifies a timeout period after which the discovery
109 process will be interrupted. N is a floating point number rep‐
110 resenting the number of seconds before timing out.
111 optionsString may also be NULL, which means that no global options are
113 specified.
114 For __pmDiscoverServicesWithOptions, flags specifies a pointer to an
116 object of type unsigned which is a bit mask of options/status flags for
117 the discovery process. The supported flags are:
118 PM_SERVICE_DISCOVERY_RESOLVE
120 Specifying this flag is equivalent to specifying resolve in the
121 optionsString
122 PM_SERVICE_DISCOVERY_INTERRUPTED
124 This flag must be unset when calling __pmDiscoverServicesWithOp‐
125 tions but may be set asynchronously (by an interrupt handler,
126 for example) in order to interrupt the service discovery
127 process.
128 flags may also be NULL, which indicates that no flags are set.
130 pmDiscoverServices and __pmDiscoverServicesWithOptions will return the
132 number of services discovered, else a value less than zero for an
133 error. The value zero indicates that no services were discovered.
134 The resulting list of pointers, urls, and the values (the URLs) that
136 the pointers reference will have been allocated by pmDiscoverServices
137 or __pmDiscoverServicesWithOptions with a single call to malloc(3), and
138 it is the responsibility of the pmDiscoverServices or __pmDiscoverSer‐
139 vicesWithOptions caller to free(urls) to release the space when it is
140 no longer required.
141 When an error occurs, or no services are discovered, urls is undefined
143 (no space will have been allocated, and so calling free(3) is a singu‐
144 larly bad idea).
145
147 Environment variables with the prefix PCP_ are used to parameterize the
148 file and directory names used by PCP. On each installation, the file
149 /etc/pcp.conf contains the local values for these variables. The
150 $PCP_CONF variable may be used to specify an alternative configuration
151 file, as described in pcp.conf(5). Values for these variables may be
152 obtained programmatically using the pmGetConfig(3) function.
153
155 pmcd(1), pmproxy(1), pmwebd(1), pmfind(1), pcp-kube-pods(1), PMAPI(3),
156 pmGetConfig(3), pcp.conf(5), pcp.env(5) and avahi-daemon(8).
157
159 -EINVAL
160 An invalid argument has been specified.
161 -ENOMEM
163 Unable to allocate memory required to process the request.
164 -EOPNOTSUPP
166 The specified mechanism is not supported.
167Performance Co-Pilot PCP PMDISCOVERSERVICES(3)