--- name: "pmDiscoverServices" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmDiscoverServices" --- # pmDiscoverServices(3) discover PCP services on the network ## NAME **pmDiscoverServices**, **\_\_pmDiscoverServicesWithOptions** - discover PCP services on the network ## C SYNOPSIS **#include \** **int pmDiscoverServices(const char \****service***,** **const char \****mechanism***,** **char \*\*\****urls***);** **#include \** **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)](/pmfind/1.md) 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\_SERVER\_PROXY\_SPEC** which search for [**pmcd**(1)](/pmcd/1.md), and [**pmproxy**(1)](/pmproxy/1.md) servers respectively. *mechanism* specifies the style of discovery to be used. The currently supported mechanisms are: - **probe=\/\** Actively probes the given subnet for the requested PCP service(s). \ is an inet or ipv6 network address and \ 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)](/pcp-kube-pods/1.md) 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)](/malloc/3.md), 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)](/free/3.md) 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)](/pcp.conf/5.md). Values for these variables may be obtained programmatically using the [**pmGetConfig**(3)](/pmGetConfig/3.md) 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)](/pmcd/1.md), [**pmfind**(1)](/pmfind/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**pcp-kube-pods**(1)](/pcp-kube-pods/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmGetConfig**(3)](/pmGetConfig/3.md), [**pcp.conf**(5)](/pcp.conf/5.md), and [**pcp.env**(5)](/pcp.env/5.md).