---
name: "pmc_allocate"
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_allocate"
---

# pmc\_allocate(3)

allocate and free performance monitoring counters

## NAME

**pmc\_allocate**, **pmc\_release** – allocate and free performance monitoring counters

## LIBRARY

library “libpmc”

## SYNOPSIS

**#include \<pmc.h\>**

*int*\

**pmc\_allocate**(*const char \*eventspecifier*, *enum pmc\_mode mode*, *uint32\_t flags*, *int cpu*, *pmc\_id\_t \*pmcid*, *uint64\_t count*);

*int*\

**pmc\_release**(*pmc\_id\_t pmc*);

## DESCRIPTION

Function **pmc\_allocate**() allocates a performance monitoring counter that measures the events named by argument *eventspecifier*, and writes the allocated handle to the location pointed to by argument *pmcid*.

Argument *eventspecifier* comprises an PMC event name followed by an optional comma separated list of keywords and qualifiers. The allowed syntax for argument *eventspecifier* is processor specific and is listed in section EVENT SPECIFIERS in the [pmc(3)](/pmc/3.md) manual page.

The desired PMC mode is specified by argument *mode*. Legal values for the *mode* argument are:

- PMC\_MODE\_SC

  Allocate a system-scope counting PMC.

- PMC\_MODE\_SS

  Allocate a system-scope sampling PMC.

- PMC\_MODE\_TC

  Allocate a process-scope counting PMC.

- PMC\_MODE\_TS

  Allocate a process-scope sampling PMC.

Mode specific modifiers may be specified using argument *flags*. The flags supported at PMC allocation time are:

- PMC\_F\_DESCENDANTS

  For process-scope PMCs, automatically track descendants of attached processes.

- PMC\_F\_LOG\_PROCCSW

  For process-scope counting PMCs, generate a log event at every context switch containing the incremental number of hardware events seen by the process during the time it was executing on the CPU.

- PMC\_F\_LOG\_PROCEXIT

  For process-scope counting PMCs, accumulate hardware events seen when the process was executing on a CPU and generate a log event when an attached process exits.

PMCs allocated with flags PMC\_F\_LOG\_PROCCSW and PMC\_F\_LOG\_PROCEXIT need a log file to be configured before they are started.

For system scope PMCs, the argument *cpu* is a non-negative value that specifies the CPU number that the PMC is to be allocated on. Process scope PMC allocations should specify the constant PMC\_CPU\_ANY for this argument.

The *count* argument behaves identically to the [pmc\_set(3)](/pmc_set/3.md) function's *value* argument. For counting PMCs, *count* specifies the initial value of the allocated PMC. For sampling PMCs, *count* specifies the reload count.

Function **pmc\_release**() releases the PMC denoted by argument *pmcid*.

## RETURN VALUES

If successful, function **pmc\_allocate**() sets the location specified by argument *pmcid* to the handle of the allocated PMC and returns 0. In case of an error, the function returns -1 and sets the global variable *errno* to indicate the error.

The **pmc\_release()** 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

- \[EINVAL\]

  The argument *mode* to function **pmc\_allocate**() had an invalid value.

- \[EINVAL\]

  Argument *cpu* to function **pmc\_allocate**() had an invalid CPU number.

- \[EINVAL\]

  Argument *flags* contained flags that were unsupported or otherwise incompatible with the requested PMC mode.

- \[EINVAL\]

  Argument *eventspecifier* to function **pmc\_allocate**() specified an event not supported by hardware or contained a syntax error.

- \[ENXIO\]

  Function **pmc\_allocate**() requested the use of a hardware resource that was absent or administratively disabled.

- \[EOPNOTSUPP\]

  The underlying hardware does not support the capabilities needed for a PMC being allocated by a call to **pmc\_allocate**().

- \[EPERM\]

  A system scope PMC allocation was attempted without adequate process privilege.

- \[ESRCH\]

  Function **pmc\_release**() was called without first having allocated a PMC.

- \[EINVAL\]

  Argument *pmcid* to function **pmc\_release**() did not specify a PMC previously allocated by this process.

## SEE ALSO

[pmc(3)](/pmc/3.md), [pmc\_attach(3)](/pmc_attach/3.md), [pmc\_configure\_logfile(3)](/pmc_configure_logfile/3.md), [pmc\_start(3)](/pmc_start/3.md), [hwpmc(4)](/hwpmc/4.md)