pmdaRootProcessStart(3) — Linux manual page


PMDAROOTCONNECT(3)        Library Functions Manual        PMDAROOTCONNECT(3)

NAME         top

       pmdaRootConnect,  pmdaRootShutdown,  pmdaRootContainerHostName, pmda‐
       RootContainerProcessID,   pmdaRootContainerCGroupName,   pmdaRootPro‐
       cessStart, pmdaRootProcessWait, pmdaRootProcessTerminate - privileged
       PCP collector services

C SYNOPSIS         top

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

       pmdaRootConnect initializes an IPC channel between a PCP collector
       process - either a PMDA(3) or pmcd(1) itself - and the pmdaroot(1)

       On success, the return value from pmdaRootConnect is a unix(7) 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         top

       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

       The name of the container is interpreted by pmdaroot(1), 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         top

       A second set of interfaces are provided allowing the collector system
       to start privileged child processes.  In particular, these are used
       by pmcd(1) 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

DIAGNOSTICS         top

       All pmdaRoot interfaces will return negative status codes suitable
       for passing to pmErrStr_r(3).

SEE ALSO         top

       pmcd(1), pmdaroot(1), pmErrStr_r(3), PMDA(3), setns(3) and unix(7).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2020-09-18.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-09-18.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                  PMDAROOTCONNECT(3)