NAME¶
pmDiscoverServices - discover PCP services on the network
C SYNOPSIS¶
#include <pcp/pmapi.h>
int pmDiscoverServices(const char * service, const char *mechanism, const char *globalOptions, char ***urls);
cc ... -lpcp
DESCRIPTION¶
Given a PCP service name, as identified by
service, and using the type of
discovery optionally specified in
mechanism,
pmDiscoverServices
returns, via
urls, a list of URLs representing the services discovered
on the network.
service specifies the PCP service to be discovered. Currently supported
services are
PM_SERVER_SERVICE_SPEC, PM_PROXY_SERVICE_SPEC and
PM_WEBD_SERVICE_SPEC, which search for
pmcd(1),
pmproxy(1), and
pmwebd(1), servers respectively.
mechanism specifies the style of discovery to be used.
The currently supported mechanisms are:
- avahi
- This searches for services which are broadcasting using mDNS via
avahi-daemon(8). An optional suffix
",timeout=NNNN" may be added to specify the discovery
timeout, in floating-point multiples of one second. The default timeout is
0.5 seconds, which may be overridden by the AVAHI_DISCOVERY_TIMEOUT
environment variable, also specified in floating-point multiples of one
second.
- probe=<net-address>/<mask-bits>
- Actively probes the given subnet for the requested PCP service(s).
<net-address> is an inet or ipv6 network address and
<mask-bits> is the number of bits used to define the subnet. For
example, 192.168.1.0/24 defines an 8 bit subnet consisting of the
addresses 192.168.1.0 through 192.168.1.255. An optional suffix
",maxThreads=N" may be added to limit the number of
threads used while probing. The default is no fixed limit, which is to say
that the process' rlimits for the number of threads and open file
descriptors will be respected.
mechanism may also be NULL, which means to use all available discovery
mechanisms.
globalOptions is a string containing options to be applied to the entire
discovery process. Currently, the only supported option is
"resolve". Normally the results are reported as a list of
urls containing the network addresses of the discovered servers. The
"resolve" option requests that an attempt be made to resolve
these addresses. If successful, the host name will be reported instead. If
unsuccessful, then the address will be reported.
pmDiscoverServices will return the number of services discovered, else a
value less than zero for an error. The value zero indicates that no services
were discovered.
The resulting list of pointers,
urls,
and the values (the URLs)
that the pointers reference will have been allocated by
pmDiscoverServices with a single call to
malloc(3C), and it is
the responsibility of the
pmDiscoverServices caller to
free(
urls) to release the space when it is no longer required.
When an error occurs, or no services are discovered,
urls is undefined
(no space will have been allocated, and so calling
free(3C) is a
singularly bad idea).
PCP ENVIRONMENT¶
Environment variables with the prefix
PCP_ are used to parameterize the
file and directory names used by PCP. On each installation, the file
/etc/pcp.conf contains the local values for these variables. The
$PCP_CONF variable may be used to specify an alternative configuration
file, as described in
pcp.conf(5). Values for these variables may be
obtained programmatically using the
pmGetConfig(3) function.
SEE ALSO¶
PMAPI(3),
pmcd(1),
pmproxy(1),
pmwebd(1),
pmfind(1),
pmGetConfig(3),
pcp.conf(5),
pcp.env(5)
and
avahi-daemon(8).
DIAGNOSTICS¶
- EOPNOTSUPP
- The specified mechanism is not supported.
