Manual Pages  — PMC_ATTACH

pmc_attach, pmc_detach – attaching and detaching process scope PMCs to target processes

LIBRARY SYNOPSIS DESCRIPTION RETURN VALUES ERRORS SEE ALSO

Performance Counters Library (libpmc, -lpmc)

#include <pmc.h>

int
pmc_attach(pmc_id_t pmcid, pid_t pid);

int
pmc_detach(pmc_id_t pmcid, pid_t pid);

These functions control the set of target processes tracked by a process scope PMC.

Function pmc_attach() is used to attach a process scope PMC specified by argument pmcid to a target process specified by argument pid. Argument pid may be zero to denote the current process. If the PMC was allocated with modifier PMC_F_DESCENDANTS, the PMC will additionally attach to current and future descendents of the specified target process. The PMC should be in a quiescent state (i.e., not running).

Function pmc_detach() is used to detach a process scope PMC specified by argument pmcid from a process specified by argument pid. Argument pid may be zero to denote the current process.

Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

A call to function pmc_attach() may fail with the following errors:

[EBUSY]
	Argument pmcid specified a PMC that was not in a quiescent state.
[EBUSY]
	The target process specified by function pmc_attach is being tracked by another process scope PMC that uses the same PMC hardware resources.
[EEXIST]
	The target process is already being tracked by the specified PMC.
[EINVAL]
	Argument pmcid specified a PMC with system scope.
[EINVAL]
	Argument pid specified an illegal process id.
[EINVAL]
	The current process does not own a PMC with the handle specified in argument pmcid.
[EPERM]
	The caller lacked the privilege needed to attach PMCs to the specified target process.
[EPERM]
	(i386 and amd64 architectures) The PMC specified by argument pmcid has been setup to allow the use of the RDPMC instruction for self measurement.
[ESRCH]
	The current process does not own any PMCs.
[ESRCH]
	The process specified by argument pid did not exist.

A call to function pmc_detach() may fail with the following errors:

[EINVAL]
	Argument pmcid specified a PMC with system scope.
[EINVAL]
	Argument pid specified an illegal process id.
[EINVAL]
	The current process does not own a PMC with the handle specified in argument pmcid.
[EINVAL]
	The specified PMC was not attached to the target process.
[ESRCH]
	The current process does not own any PMCs.
[ESRCH]
	The process specified by argument pid is not being monitored by hwpmc(4).
[ESRCH]
	The process specified by argument pid did not exist.