pmDiscoverServices,
__pmDiscoverServicesWithOptions - discover PCP
services on the network
#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
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.
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 and
PM_PROXY_SERVICE_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_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 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 second. 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 directory 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 typically 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 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(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 allocated, and so calling
free(3) is a
singularly bad idea).
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.
- -EINVAL
- An invalid argument has been specified.
- -ENOMEM
- Unable to allocate memory required to process the
request.
- -EOPNOTSUPP
- The specified mechanism is not supported.
pmcd(1),
pmfind(1),
pmproxy(1),
pcp-kube-pods(1),
PMAPI(3),
pmGetConfig(3),
pcp.conf(5),
pcp.env(5)
and
avahi-daemon(8).