PMPARSEHOSTATTRSSPEC(3)

✨ PMPARSEHOSTATTRSSPEC ✨ — Library Functions Manual, section 3, but make it cute

okay so bestie, this is the manual page for the host-and-attributes specification parser, and she is so much. grab a snack, we're going in 🍓

---

🌸 NAME 🌸

__pmParseHostAttrsSpec, __pmUnparseHostAttrsSpec, __pmFreeHostAttrsSpec, __pmFreeAttrsSpec — host and attributes specification parser. she parses, she unparses, she frees. multitasking icon 💅

---

🎀 C SYNOPSIS 🎀

#include "pmapi.h"
#include "libpcp.h"

int __pmParseHostAttrsSpec(const char *string, __pmHostSpec **hostsp,
                           int *count, __pmHashCtl *attrs,
                           char **errmsg);
int __pmUnparseHostAttrsSpec(__pmHostSpec *hostsp, int *count,
                             __pmHashCtl *attrs, char *string,
                             size_t size);
void __pmFreeHostAttrsSpec(__pmHostSpec *hosts, int count,
                           __pmHashCtl *attrs);
void __pmFreeAttrsSpec(__pmHashCtl *attrs);

and you link it like:

cc ... -lpcp

---

💀 CAVEAT 💀

this documentation is intended for internal Performance Co-Pilot (PCP) developer use. not a public-facing situation, bestie.

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

---

🦋 DESCRIPTION 🦋

__pmParseHostAttrsSpec takes a string that says where a PCP performance metric collector daemon lives, plus any attributes that should ride along with the connection to that daemon. it's giving ✨connection vision board✨

the syntax lets you optionally specify a protocol — that's native PCP protocol, encrypted PCP protocol, or unix domain socket protocol. pick your fighter 💖

if the protocol you specified is native PCP protocol, or encrypted PCP protocol, then you can specify an initial pmcd(1) hostname with optional port numbers and an optional proxy host, plus optional attributes to associate with the connection. some examples, because examples ate:

pcp://nas1.servers.com:44321@firewalls.r.us?compress
pcps://nas1.servers.com?user=otto&pass=blotto&compress

if the protocol you specified is a unix domain socket protocol, then you can specify the path to the socket in the local file system, along with optional attributes to associate with the connection. for example:

unix://$PCP_RUN_DIR/pmcd.socket:?compress
local://my/local/pmcd.socket:?user=otto&pass=blotto&compress

if you don't specify the optional protocol component, the default setting gets used — which is the native PCP binary protocol. but no cap, this can still be overwritten via the environment as described in PCPIntro(1). and if you do specify the protocol prefix, it has to be one of these four, periodt:

• "pcp://" — clear
• "pcps://" — secure, encrypted
• "unix://" — authenticated local
• "local://" — "unix://" then "pcp://"

the path you give for the "unix://" and "local://" protocols will always be interpreted as an absolute path name. so these three? all interpreted identically as $PCP_RUN_DIR/pmcd.socket. same girl, three outfits:

unix://$PCP_RUN_DIR/pmcd.socket
unix:/$PCP_RUN_DIR/pmcd.socket
unix:$PCP_RUN_DIR/pmcd.socket

head over to __pmParseHostSpec(3) for further details of the host and proxy host components 🫶

if you want to specify any optional connection attributes, they get separated from the hostname component by the '?' character. each attribute is separated by the '&' character, and each one can be either a simple attribute flag (like "compress") or a name=value pair (like "username=fred"). lowkey elegant.

__pmParseHostAttrsSpec takes a null-terminated host-and-attributes specification string and returns:

• an array of __pmHostSpec structures, where the array has count entries, and
• an attrs hash table containing any attributes (including the optional protocol, if it was specified)

full details of the __pmHostSpec structures are provided in __pmParseHostSpec(3).

the __pmHashCtl structure that gets filled out on return via attributes represents each individual attribute in the specification string with any associated value. consider it an opaque structure and zero it beforehand — no peeking inside, and wipe the counter first 💅

the returned hash table control structure can be iterated using one of the supplied iteration mechanisms — __pmHashWalkCB (a callback-based mechanism) or __pmHashWalk (a simple procedural mechanism). these give you access to the individual hash nodes, as __pmHashNode entries, which in turn give you access to decoded attributes and their (optional) values:

typedef struct __pmHashNode {
    __pmHashNode    *next;    /* next node in hash bucket (internal) */
    unsigned int    key;      /* key identifying particular attribute */
    void            *data;    /* attributes value (optional, string) */
} __pmHashNode;

there are a set number of valid attributes, but these may be extended in future releases as new connection parameters become needed. you can identify them via the PCP_ATTR_* macros in the PCP header files 👑

__pmUnparseHostSpec performs the inverse operation — creating a string representation from hosts and attributes structures. the size of the supplied string buffer must be provided by the caller using the size parameter. reverse uno card, slay.

---

🌈 RETURN VALUE 🌈

if the given string is successfully parsed, __pmParseHostAttrsSpec returns zero. in that case, the dynamic storage allocated by __pmParseHostAttrsSpec can be released by calling __pmFreeHostAttrsSpec using the addresses returned from __pmParseHostAttrsSpec.

alternatively, the hosts and attributes memory can be freed separately, using __pmFreeHostSpec(3) and __pmFreeAttrsSpec. your call, bestie 💖

__pmParseHostAttrsSpec returns PM_ERR_GENERIC and a dynamically allocated error message string in errmsg if the given string does not parse and the user-supplied errmsg pointer is non-null. be sure to free(3) the error message string in this situation — yes, that's on you, don't leak her 😭

in the case of an error, both hosts and attributes are undefined. in the case of success, errmsg is undefined. them's the rules.

on success, __pmUnparseHostAttrsSpec returns a positive value indicating the number of characters written into the supplied buffer. but if the supplied buffer was too small, a negative status code of -E2BIG will be returned. buffer said no 💀

---

💜 SEE ALSO 💜

pmcd(1), pmproxy(1), pmchart(1), __pmParseHostSpec(3), PMAPI(3) and pmNewContext(3). go read them, iykyk 🧚

---

Performance Co-Pilot 🌟 PCP 🌟 and that's the whole page, no notes. mwah 💋 thanks for reading my little manpage bestie, you ate 🫶✨