---
name: "__pmParseHostAttrsSpec"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/__pmParseHostAttrsSpec"
---

# \_\_pmParseHostAttrsSpec(3)

host and attributes specification parser

## NAME

**\_\_pmParseHostAttrsSpec**, **\_\_pmUnparseHostAttrsSpec**, **\_\_pmFreeHostAttrsSpec**, **\_\_pmFreeAttrsSpec** - host and attributes specification parser

## 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***);**

**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

**\_\_pmParseHostAttrsSpec** accepts a **string** specifying the location of a PCP performance metric collector daemon, and any attributes that should be associated with the connection to that daemon.

The syntax allows the optional specification of a protocol (native PCP protocol, encrypted PCP protocol or unix domain socket protocol).

If the specified protocol is native PCP protocol, or encrypted PCP protocol, an initial [**pmcd**(1)](/pmcd/1.md) hostname with optional port numbers and optional proxy host, and optional attributes which are to be associated with the connection may be specified. Some examples follow:

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

If the specified protocol is a unix domain socket protocol, the path to the socket in the local file system may be specified along with optional attributes which are to be associated with the connection. For example:

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

If the optional protocol component is not specified, then the default setting will be used - which is the native PCP binary protocol. However, this can still be overwritten via the environment as described in [**PCPIntro**(1)](/PCPIntro/1.md). If the protocol prefix is specified, it must be one of either "pcp://" (clear), "pcps://" (secure, encrypted), "unix://" (authenticated local) or "local://" ("unix://" then "pcp://").

The path specified for the "unix://" and "local://" protocols will always be interpreted as an absolute path name. For example, the following are all interpreted identically as *$PCP\_RUN\_DIR/pmcd.socket*.

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

Refer to [**\_\_pmParseHostSpec**(3)](/__pmParseHostSpec/3.md) for further details of the host and proxy host components.

If any optional connection attributes are to be specified, these are separated from the hostname component via the '?' character. Each attribute is separated by the '&' character, and each can be either a simple attribute flag (such as "compress") or a name=value pair (such as "username=fred").

**\_\_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)](/__pmParseHostSpec/3.md).

The **\_\_pmHashCtl** structure that is filled out on return via **attributes**, represents each individual attribute in the specification **string** with any associated value. It should be considered an opaque structure and should be zeroed beforehand.

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 provide access to the individual hash nodes, as **\_\_pmHashNode** entries, which provide 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, however these may be` `extended in future releases as new connection parameters become` `needed.` `These can be identified 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.`

## RETURN VALUE

`If the given` **string** `is successfully parsed` **\_\_pmParseHostAttrsSpec** `returns zero.` `In this 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)](/__pmFreeHostSpec/3.md) `and` **\_\_pmFreeAttrsSpec**.

**\_\_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)](/free/3.md) `the error message string in this situation.`

`In the case of an error, both` **hosts** `and` **attributes** `are undefined.` `In the case of success,` **errmsg** `is undefined.`

`On success` **\_\_pmUnparseHostAttrsSpec** `returns a positive value indicating the number of characters written` `into the supplied buffer.` `However, if the supplied buffer was too small, a negative status code of` **-E2BIG** `will be returned.`

## SEE ALSO

[**pmcd**(1)](/pmcd/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**pmchart**(1)](/pmchart/1.md), [**\_\_pmParseHostSpec**(3)](/__pmParseHostSpec/3.md), [**PMAPI**(3)](/PMAPI/3.md) `and` [**pmNewContext**(3)](/pmNewContext/3.md).