FreeBSD manual

download PDF document: pmc_attach.3.pdf

PMC_ATTACH(3) FreeBSD Library Functions Manual PMC_ATTACH(3) NAME pmc_attach, pmc_detach - attaching and detaching process scope PMCs to target processes LIBRARY Performance Counters Library (libpmc, -lpmc) 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 [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. SEE ALSO pmc(3), pmc_start(3), pmc_stop(3), hwpmc(4) FreeBSD 14.0-RELEASE-p11 November 25, 2007 FreeBSD 14.0-RELEASE-p11