PMDISCOVERSERVICES(3)

💖 PMDISCOVERSERVICES(3) 💖

okay bestie, so this one lives in the Library Functions Manual section, and it's literally about finding PCP services all over the network 🦋

---

✨ NAME ✨

pmDiscoverServices, __pmDiscoverServicesWithOptions — the duo that discovers 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 🚨

ngl, this documentation is meant for internal Performance Co-Pilot (PCP) developer use. Like, devs only, iykyk.

These interfaces are not part of the PCP APIs that are guaranteed to stay fixed across releases 👀 and they may not work, or may provide different semantics at some point in the future. so… don't build your whole personality on them fr fr 😭

---

👑 DESCRIPTION 👑

Given a PCP service name (that's 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 does the exact same thing, but it adds arguments for global options and a mechanism for interrupting the discovery process. main character energy honestly 💅

The pmfind(1) utility gives you 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) and pmproxy(1) servers respectively 🎀

mechanism specifies the style of discovery to be used.

The currently supported mechanisms are:

• 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. You can add an optional suffix ",maxThreads=N" 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. You can also add an optional suffix ",timeout=N" 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 the requested PCP service(s) 🐚 Several optional, comma-separated parameters can also be provided. First up, the "path=DIR" option specifies the directory where commands like pcp-kube-pods(1) are located (defaults to $PCP_BINADM_DIR/discover/). You can further restrict this to an individual command with 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 how long you spend 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 — Requests that DNS name resolution be attempted for the addresses of any discovered services 🔍
• timeout=N — 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 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, or 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) 😭 do NOT do it bestie.

---

🌱 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), and pcp.env(5).

---

and that's the whole thing, periodt 💅 this page came to you from Performance Co-Pilot (that's the PCP crew 👑) and the date/version line at the bottom is PMDISCOVERSERVICES(3) — stan a manpage that eats every single time 🎀✨💖