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

# pmGetHostName(3)

return the hostname associated with a Performance Co-Pilot context

## NAME

**pmGetHostName**, **pmGetContextHostName**, **pmGetContextHostName\_r** - return the hostname associated with a Performance Co-Pilot context

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**

**int pmGetHostName(int** *id***, char \****buf***, int** *buflen***);**\
 **const char \*pmGetContextHostName(int** *id***);**\
 **char \*pmGetContextHostName\_r(int** *id***, char \****buf***, int** *buflen***);**

**cc ... -lpcp**

## DESCRIPTION

Given a valid PCP context identifier previously created with [**pmNewContext**(3)](/pmNewContext/3.md) or [**pmDupContext**(3)](/pmDupContext/3.md), the **pmGetContextHostName** function returns the hostname associated with *id*. The **pmGetContextHostName\_r** function does the same, but stores the result in a user-supplied buffer *buf* of length *buflen*, which should have room for at least **MAXHOSTNAMELEN** bytes. The **pmGetHostName** function behaves similarly again, but returns a status code to indicate success or failure.

If the context *id* is associated with an archive source of data, the hostname returned is extracted from the archive label using [**pmGetArchiveLabel**(3)](/pmGetArchiveLabel/3.md).

For live contexts, an attempt will first be made to retrieve the hostname from the PCP collector system using [**pmFetch**(3)](/pmFetch/3.md) with the *pmcd.hostname* metric. This allows client tools using this interface to retrieve an accurate host identifier even in the presence of port forwarding and tunnelled connections.

Should this not succeed, then a fallback method is used. For local contexts - with local meaning any of DSO, \`\`localhost'' or Unix domain socket connection - a hostname will be sought via [**gethostname**(3)](/gethostname/3.md). For other contexts, the hostname extracted from the initial context host specification will be used.

## RETURN VALUE

If *id* is not a valid PCP context identifier, the returned hostname is a zero length string.

On failure, the return code of **pmGetHostName** is a negative PMAPI error code which can be processed by [**pmErrStr\_r**(3)](/pmErrStr_r/3.md) for diagnostics relating to the failure to obtain the context hostname.

## NOTES

**pmGetContextHostName** returns a pointer to a static buffer, so the returned value is only valid until the next call to **pmGetContextHostName** and hence is not thread-safe. Multi-threaded applications should use **pmGetHostName** or **pmGetContextHostName\_r** instead.

## 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.

## SEE ALSO

[**PCPIntro**(1)](/PCPIntro/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**gethostname**(3)](/gethostname/3.md), [**pmDupContext**(3)](/pmDupContext/3.md), [**pmErrStr\_r**(3)](/pmErrStr_r/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmGetArchiveLabel**(3)](/pmGetArchiveLabel/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pcp.conf**(5)](/pcp.conf/5.md) and [**pcp.env**(5)](/pcp.env/5.md).