---
name: "pmc_attach"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/pmc_attach"
---

# pmc\_attach(3)

attaching and detaching process scope PMCs to target processes

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

The **pmc\_attach()** function returns the value 0 if successful; 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)](/hwpmc/4.md).

- \[ESRCH\]

  The process specified by argument *pid* did not exist.

## SEE ALSO

[pmc(3)](/pmc/3.md), [pmc\_start(3)](/pmc_start/3.md), [pmc\_stop(3)](/pmc_stop/3.md), [hwpmc(4)](/hwpmc/4.md)