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

# \_\_pmParseHostSpec(3)

uniform host specification parser

## NAME

**\_\_pmParseHostSpec**, **\_\_pmUnparseHostSpec**, **\_\_pmFreeHostSpec** - uniform host specification parser

## C SYNOPSIS

**#include "pmapi.h"**\
 **#include "libpcp.h"**

**int \_\_pmParseHostSpec(const char \****string***,** **\_\_pmHostSpec \*\****hostsp***,** **int \****count***,** **char \*\****errmsg***);**\
 **int \_\_pmUnparseHostSpec(\_\_pmHostSpec \****hosts***,** **int** *count***,** **char \****string***,** **size\_t** *size***);**\
 **void \_\_pmFreeHostSpec(\_\_pmHostSpec \****hosts***, int** *count***);**

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

**\_\_pmParseHostSpec** accepts a **string** specifying the location of a PCP performance metric collector daemon. The syntax of the various formats of this **string** is described in [**PCPIntro**(1)](/PCPIntro/1.md) where several examples are also presented.

The syntax allows the initial [**pmcd**(1)](/pmcd/1.md) hostname to be optionally followed by a list of port numbers, which will be tried in order when connecting to **pmcd** on that host. The list of port numbers is separated from the hostname using a colon, and each port in the list is comma-separated.

In addition, one or more optional [**pmproxy**(1)](/pmproxy/1.md) hosts can be specified (currently, only one proxy host is supported by the PCP protocols). These are separated from each other and from the **pmcd** component using the @ character. These may also be followed by an optional port list, using the same comma-separated syntax as before.

**\_\_pmParseHostSpec** takes a null-terminated host specification **string** and returns an array of **\_\_pmHostSpec** structures, where the array has **count** entries.

These **\_\_pmHostSpec** structures that are returned via **hostsp** represent each individual host in the specification **string** and has the following declaration:

```
    typedef struct {
        char    *name;       /* hostname (always valid) */
        int     *ports;      /* array of host port numbers */
        int     nports;      /* number of ports in host port array */
    } __pmHostSpec;
```

**\_\_pmUnparseHostSpec** `performs the inverse operation, creating a` **string** `representation from a number of` **hosts** `structures.` `Where the` **count** `of structures indicated by` **hosts** `is greater than one, the proxy syntax is used to indicate a chain of` `proxied hosts.` `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` **\_\_pmParseHostSpec** `returns zero.` `In this case the dynamic storage allocated by` **\_\_pmParseHostSpec** `can be released by calling` **\_\_pmFreeHostSpec** `using the address returned from` **\_\_pmParseHostSpec** `via` **hosts**.

**\_\_pmParseHostSpec** `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,` **hosts** `is undefined.` `In the case of success,` **errmsg** `is undefined.`

`On success` **\_\_pmUnparseHostSpec** `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** `is returned.`

## SEE ALSO

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