# pmdiscoverservices

## 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_ , **pmDiscover‐**
           **Services** returns, via _urls_ , a list of URLs representing  the  ser‐
           vices discovered on the network.
    
           The internal function **__pmDiscoverServicesWithOptions** performs the
           same  function  and adds arguments for global options and a mecha‐
           nism 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_SERV‐**
           **ER_PROXY_SPEC** which search for pmcd(1), and pmproxy(1) servers re‐
           spectively.
    
           _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 float‐
                  ing-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 ser‐
                  vice(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 sub‐
                  net 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 typical‐
                  ly 1024) or the number of addresses in the subnet, whichev‐
                  er 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 re‐
                  quested 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_BI‐_
                  _NADM_DIR/discover/_).  This setting can be further restrict‐
                  ed 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 ad‐
                  dresses 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 dis‐
           covery mechanisms.
    
           For **__pmDiscoverServicesWithOptions,**_optionsString_ specifies glob‐
           al 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 **__pmDiscoverSer‐**
                  **vicesWithOptions** but may be set asynchronously (by an in‐
                  terrupt 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 discov‐
           ered.
    
           The resulting list of pointers, _urls_ , **and** the values (the URLs)
           that the pointers reference will have been allocated by **pmDiscov‐**
           **erServices** or **__pmDiscoverServicesWithOptions** with a single call
           to malloc(3), and it is the responsibility of the **pmDiscoverSer‐**
           **vices** 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 unde‐
           fined (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 parameter‐
           ize the file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values for these
           variables.  The **$PCP_CONF** variable may be used to specify an al‐
           ternative 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.
    


* * *