Provided by: libpcp3-dev_5.3.7-1_amd64 bug

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_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).

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.

SEE ALSO

       pmcd(1),  pmfind(1),  pmproxy(1), pcp-kube-pods(1), PMAPI(3), pmGetConfig(3), pcp.conf(5),
       pcp.env(5) and avahi-daemon(8).