NAME
pmc_attach,
pmc_detach —
attaching and detaching process scope
PMCs to target processes
LIBRARY
library “libpmc”
SYNOPSIS
#include
<pmc.h>
int
pmc_attach(pmc_id_t
pmcid, pid_t
pid);
int
pmc_detach(pmc_id_t
pmcid, pid_t
pid);
DESCRIPTION
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.
RETURN VALUES
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.
ERRORS
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.