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/impl.h>
14 int __pmDiscoverServicesWithOptions(const char *service, const char *mechanism, const char *optionsString, const volatile unsigned *flags, char ***urls);
16 cc ... -lpcp
18
20 Given a PCP service name, as identified by service, and using the type
21 of discovery optionally specified in mechanism, pmDiscoverServices
22 returns, via urls, a list of URLs representing the services discovered
23 on the network.
24 The internal function __pmDiscoverServicesWithOptions performs the same
26 function and adds arguments for global options and a mechanism for
27 interrupting the discovery process.
28 The pmfind(1) utility provides command line access to both of these
30 interfaces.
31 Calling
33 pmDiscoverServices(service, mechanism, urls)
35 is equivalent to calling
37 __pmDiscoverServicesWithOptions(service, mechanism, NULL, NULL, urls);
39 service specifies the PCP service to be discovered. Currently supported
41 services are PM_SERVER_SERVICE_SPEC, PM_PROXY_SERVICE_SPEC and
42 PM_WEBD_SERVICE_SPEC, which search for pmcd(1), pmproxy(1), and
43 pmwebd(1), servers respectively.
44 mechanism specifies the style of discovery to be used.
46 The currently supported mechanisms are:
48 avahi This searches for services which are broadcasting using mDNS via
50 avahi-daemon(8). An optional suffix ",timeout=N" may be added
51 to specify the discovery timeout in floating-point multiples of
52 one second. The default timeout is 0.5 seconds, which may be
53 overridden by the AVAHI_DISCOVERY_TIMEOUT environment variable,
54 also specified in floating-point multiples of one second. If
55 both are specified, then the value specified in the environment
56 variable takes precedence.
57 probe=<net-address>/<mask-bits>
59 Actively probes the given subnet for the requested PCP ser‐
60 vice(s). <net-address> is an inet or ipv6 network address and
61 <mask-bits> is the number of bits used to define the subnet. For
62 example, 192.168.1.0/24 defines an 8 bit subnet consisting of
63 the addresses 192.168.1.0 through 192.168.1.255. An optional
64 suffix ",maxThreads=N" may be added to limit the number of
65 threads used while probing. The default is no fixed limit, which
66 is to say that the process' rlimits for the number of threads
67 and open file descriptors will be respected. An optional suffix
68 ",timeout=N" may be added to specify the timeout for each con‐
69 nection attempt in floating-point multiples of one second. The
70 default timeout is 20 milliseconds.
71 mechanism may also be NULL, which means to use all available discovery
73 mechanisms.
74 For __pmDiscoverServicesWithOptions, optionsString specifies global
76 options to be applied to the discovery process. Options are comma-sepa‐
77 rated and may be one or more of the following:
78 resolve
80 This requests that DNS name resolution be attempted for the
81 addresses of any discovered services.
82 timeout=N
84 This specifies a timeout period after which the discovery
85 process will be interrupted. N is a floating point number repre‐
86 senting the number of seconds before timing out.
87 optionsString may also be NULL, which means that no global options are
89 specified.
90 For __pmDiscoverServicesWithOptions, flags specifies a pointer to an
92 object of type unsigned which is a bit mask of options/status flags for
93 the discovery process. The supported flags are:
94 PM_SERVICE_DISCOVERY_RESOLVE
96 Specifying this flag is equivalent to specifying resolve in the
97 optionsString
98 PM_SERVICE_DISCOVERY_INTERRUPTED
100 This flag must be unset when calling __pmDiscoverServicesWithOp‐
101 tions but may be set asynchronously (by an interrupt handler,
102 for example) in order to interrupt the service discovery
103 process.
104 flags may also be NULL, which indicates that no flags are set.
106 pmDiscoverServices and __pmDiscoverServicesWithOptions will return the
108 number of services discovered, else a value less than zero for an
109 error. The value zero indicates that no services were discovered.
110 The resulting list of pointers, urls, and the values (the URLs) that
112 the pointers reference will have been allocated by pmDiscoverServices
113 or __pmDiscoverServicesWithOptions with a single call to malloc(3), and
114 it is the responsibility of the pmDiscoverServices or __pmDiscoverSer‐
115 vicesWithOptions caller to free(urls) to release the space when it is
116 no longer required.
117 When an error occurs, or no services are discovered, urls is undefined
119 (no space will have been allocated, and so calling free(3) is a singu‐
120 larly bad idea).
121
123 Environment variables with the prefix PCP_ are used to parameterize the
124 file and directory names used by PCP. On each installation, the file
125 /etc/pcp.conf contains the local values for these variables. The
126 $PCP_CONF variable may be used to specify an alternative configuration
127 file, as described in pcp.conf(5). Values for these variables may be
128 obtained programmatically using the pmGetConfig(3) function.
129
131 PMAPI(3), pmcd(1), pmproxy(1), pmwebd(1), pmfind(1), pmGetConfig(3),
132 pcp.conf(5), pcp.env(5) and avahi-daemon(8).
133
135 -EINVAL
136 An invalid argument has been specified.
137 -ENOMEM
139 Unable to allocate memory required to process the request.
140 -EOPNOTSUPP
142 The specified mechanism is not supported.
143Performance Co-Pilot PCP PMDISCOVERSERVICES(3)