Ubuntu Manpage: pmDiscoverServices, __pmDiscoverServicesWithOptions

NAME

       pmDiscoverServices, __pmDiscoverServicesWithOptions - discover PCP services on the network

C SYNOPSIS

       #include <pcp/pmapi.h>

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

       #include <pcp/libpcp.h>

       int __pmDiscoverServicesWithOptions(const char *service, const char *mechanism,
                                           const char *optionsString, const volatile unsigned *flags,
                                           char ***urls);

       cc ... -lpcp

CAVEAT

       This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

       These  interfaces  are  not part of the PCP APIs that are guaranteed to remain fixed across releases, and
       they may not work, or may provide different semantics at some point in the future.

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_SER‐
VICE_SPEC and PM_SERVER_PROXY_SPEC which search for pmcd(1), and pmproxy(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_DISCOV‐
ERY_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 exam‐
ple, 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 the value of __FD_SETSIZE (which is typically 1024) or the
number of addresses in the subnet, whichever is less. An optional suffix ",timeout=N" may be
added to specify the timeout for each connection attempt in floating-point multiples of one sec‐
ond. The default is 0.02 seconds (20 milliseconds).

shell Probes the list of addresses provided by scripts for requested PCP service(s). Several optional,
comma-separated parameters can also be provided. Firstly, the "path=DIR" option specifies the di‐
rectory where commands like pcp-kube-pods(1) are located (defaults to $PCP_BINADM_DIR/discover/).
This setting can be further restricted to an individual command using the command=CMD option, but
the default is to use all available commands from the path. The "maxThreads=N" option limits the
number of threads used while probing. The default is the value of __FD_SETSIZE (which is typical‐
ly 1024) or the number of addresses returned by the scripts, whichever is less. The "timeout=N"
option may be added to limit the amount of time spent waiting for each connection attempt. N is a
floating point number specifying the number of seconds to wait. The default is 0.02 seconds (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 discov‐
ery 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(3),
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 allocat‐
ed, and so calling free(3) 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