pmdarootconnect(3) — Linux manual page


PMDAROOTCONNECT(3)      Library Functions Manual      PMDAROOTCONNECT(3)

NAME         top

       pmdaRootConnect, pmdaRootShutdown, pmdaRootContainerHostName,
       pmdaRootContainerProcessID, pmdaRootContainerCGroupName,
       pmdaRootProcessStart, 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) server.

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

       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

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

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

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 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  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)

Pages that refer to this page: pmdaroot(1)