Ubuntu Manpage: pmDiscoverServices - discover PCP services on the network

Provided by: libpcp3-dev_3.10.8build1_amd64

NAME

       pmDiscoverServices - discover PCP services on the network

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmDiscoverServices(const char *service, const char *mechanism, char ***urls);

       #include <pcp/impl.h>

       int __pmDiscoverServicesWithOptions(const char *service, const char *mechanism, const char *optionsString, const volatile unsigned *flags, 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.

The internal function __pmDiscoverServicesWithOptions performs the same function and adds
arguments for global options and a mechanism for interrupting the discovery process.

The pmfind(1) utility provides command line access to both of these interfaces.

Calling

pmDiscoverServices(service, mechanism, urls)

is equivalent to calling

__pmDiscoverServicesWithOptions(service, mechanism, NULL, NULL, urls);

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=N" 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. If both are specified, then
the value specified in the environment variable takes precedence.

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. An optional suffix
",timeout=N" may be added to specify the timeout for each connection attempt in
floating-point multiples of one second. The default timeout is 20 milliseconds.

mechanism may also be NULL, which means to use all available discovery mechanisms.

For __pmDiscoverServicesWithOptions, optionsString specifies global options to be applied
to the discovery process. Options are comma-separated and may be one or more of the
following:

resolve
This requests that DNS name resolution be attempted for the addresses of any
discovered services.

timeout=N
This specifies a timeout period after which the discovery process will be
interrupted. N is a floating point number representing the number of seconds before
timing out.

optionsString may also be NULL, which means that no global options are specified.

For __pmDiscoverServicesWithOptions, flags specifies a pointer to an object of type
unsigned which is a bit mask of options/status flags for the discovery process. The
supported flags are:

PM_SERVICE_DISCOVERY_RESOLVE
Specifying this flag is equivalent to specifying resolve in the optionsString

PM_SERVICE_DISCOVERY_INTERRUPTED
This flag must be unset when calling __pmDiscoverServicesWithOptions but may be set
asynchronously (by an interrupt handler, for example) in order to interrupt the
service discovery process.

flags may also be NULL, which indicates that no flags are set.

pmDiscoverServices and __pmDiscoverServicesWithOptions 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 or
__pmDiscoverServicesWithOptions with a single call to malloc(3C), and it is the
responsibility of the pmDiscoverServices or __pmDiscoverServicesWithOptions 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.

DIAGNOSTICS

       -EINVAL
              An invalid argument has been specified.

       -ENOMEM
              Unable to allocate memory required to process the request.

       -EOPNOTSUPP
              The specified mechanism is not supported.

NAME

C SYNOPSIS

DESCRIPTION

PCP ENVIRONMENT

SEE ALSO

DIAGNOSTICS