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

# pmdaRootConnect(3)

privileged PCP collector services

## NAME

**pmdaRootConnect**, **pmdaRootShutdown**, **pmdaRootContainerHostName**, **pmdaRootContainerProcessID**, **pmdaRootContainerCGroupName**, **pmdaRootProcessStart**, **pmdaRootProcessWait**, **pmdaRootProcessTerminate** - privileged PCP collector services

## C SYNOPSIS

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

**int pmdaRootConnect(void);**\
 **void pmdaRootShutdown(int** *fd***);**\
 **int pmdaRootContainerHostName(int** *fd***,** **char \****name***,** **int** *namelen***,** **char \****buffer***,** **int** *buflen***);**\
 **int pmdaRootContainerProcessID(int** *fd***,** **char \****name***,** **int** *namelen***);**\
 **int pmdaRootContainerCGroupName(int** *fd***,** **char \****name***,** **int** *namelen***,** **char \****buffer***,** **int** *buflen***);**\
 **int pmdaRootProcessStart(int** *fd***,** **int** *ipctype***,** **char \****label***,** **int** *labellen***,** **const char \****args***,** **int** *argslen***,** **int \****pid***,** **int \****infd***,** **int \****outfd***);**\
 **int pmdaRootProcessWait(int** *fd***, int** *pid***, int \****status***);**\
 **int pmdaRootProcessTerminate(int** *fd***, int** *pid***);**

**cc ... -lpcp\_pmda -lpcp**

## DESCRIPTION

**pmdaRootConnect** initializes an IPC channel between a PCP collector process - either a [**PMDA**(3)](/PMDA/3.md) or [**pmcd**(1)](/pmcd/1.md) itself - and the [**pmdaroot**(1)](/pmdaroot/1.md) server.

On success, the return value from **pmdaRootConnect** is a [**unix**(7)](/unix/7.md) domain socket file descriptor, which can be subsequently passed to each of the other APIs described here. This channel can be used to perform limited privilege escalation for specific scenarios needed by PCP collector services. The channel can be deactivated using the **pmdaRootShutdown** interface.

## CONTAINERS

Several interfaces are provided for access to the container facilities of modern Linux distributions, as needed by various agents accessing kernel features related to containers.

**pmdaRootContainerHostName** allows lookup of the current hostname for a named container on behalf of an unprivileged process, via the **setns**(3) system call on Linux. On success, the hostname is returned in the supplied **buffer**, of size **buflen** and the return value indicates the length of the hostname.

**pmdaRootContainerProcessID** performs a *name* to process identifier translation - on success, the return value is the identifier of the first process started (process 1) in the named container.

**pmdaRootContainerCGroupName** fills the supplied *buffer* with the engine-specific names of kernel control groups that have been used to build the container identified by *name*. When successful, the return value indicates the length of the cgroup name resolved for the container.

The *name* of the container is interpreted by [**pmdaroot**(1)](/pmdaroot/1.md), which attempts to match up the specified name with one of the implementations of containers that it is aware of. Hence, the *name* argument is potentially interpreted differently, depending on the installed container engine, as determined internally by **pmdaroot**).

In the case of the Docker container engine, for example, a valid container name can be the unique hash identifier, the human-readable name, or any unique identifier substring. This is the algorithm used by the Docker client tools themselves.

## PROCESSES

A second set of interfaces are provided allowing the collector system to start privileged child processes. In particular, these are used by [**pmcd**(1)](/pmcd/1.md) so that it can start privileged PMDAs even when it is running under an unprivileged account itself.

These interfaces allow processes to be started (**pmdaRootProcessStart**), reaped upon completion (**pmdaRootProcessWait**), and forcibly terminated through use of signals (**pmdaRootProcessTerminate**). At this stage, they are intended only for use by **pmcd** itself and as such are described here only for completeness.

## DIAGNOSTICS

All **pmdaRoot** interfaces will return negative status codes suitable for passing to [**pmErrStr\_r**(3)](/pmErrStr_r/3.md).

## SEE ALSO

[**pmcd**(1)](/pmcd/1.md), [**pmdaroot**(1)](/pmdaroot/1.md), [**pmErrStr\_r**(3)](/pmErrStr_r/3.md), [**PMDA**(3)](/PMDA/3.md), **setns**(3) and [**unix**(7)](/unix/7.md).