---
title: cpu-usage
related:
  - "[timeslice.h](timeslice.h.md)"
categories:
  - C libraries
---

**cpu-usage** (`cpu_usage.h`) is a tiny public domain library that reads CPU
usage per core on Linux. It also measures RAPL package energy (joules and
watts), estimates per-process energy, and converts it to CO2e emissions.

The library is self-documented: read `cpu_usage.h`.

## Usage

Everything works with snapshots ("slices"): take one, run something, take
another, and compute the difference.

| Function | Description |
|---|---|
| `get_cpu_usage(id, &slice)` | Snapshot a core (or the whole machine) |
| `calc_cpu_usage(t0, t1)` | Usage % between two snapshots |
| `get_proc_cpu_usage(pid, &slice)` | Snapshot a process (`pid <= 0` is self) |
| `get_thread_cpu_usage(pid, tid, &slice)` | Snapshot a thread |
| `calc_proc_cpu_usage(...)` | Process usage % against the machine |
| `calc_proc_cpu_usage_per_core(...)` | top-style %, one core = 100% |
| `get_cpu_count()` | Cores the process may run on |
| `get_energy_open(&h)`, `close_energy(&h)` | Open/close the RAPL counter |
| `get_energy_usage(&h, &slice)` | Snapshot package energy |
| `calc_energy_joules(t0, t1)`, `calc_energy_power(t0, t1)` | Energy and average power |
| `calc_proc_energy_joules(...)` | Estimated energy of one process |
| `calc_carbon_emissions(t0, t1, g_per_kwh)` | Grams of CO2e |

The `*_children` variants include waited-for children.

> [!NOTE]
> The energy counters come from RAPL through the perf `power` PMU and need
> root or `CAP_PERFMON`. RAPL measures the first socket only, and per-process
> energy is an estimate: package joules times the process's share of CPU
> time. Run the test with `sudo` for the energy part.

## See also

- [Source code](https://github.com/hugoocoto/cpu-usage) (Unlicense)