# bpftime Runtime API Header File: Complete Guide to `bpftime.hpp`

> Explore bpftime.hpp the primary runtime API header file for bpftime. Access shared-memory management program loading and attachment contexts with this essential guide.

- Repository: [eunomia-bpf/bpftime](https://github.com/eunomia-bpf/bpftime)
- Tags: api-reference
- Published: 2026-03-01

---

**The main runtime API header file in bpftime is [`runtime/include/bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/include/bpftime.hpp), which aggregates all essential runtime components including shared-memory management, program loading, and attachment contexts.**

The **bpftime** project provides a high-performance user-space eBPF runtime designed for attaching programs to user-space functions without kernel modifications. Understanding the **bpftime runtime API header file** structure is essential for developers integrating eBPF functionality into their applications. The central entry point [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp) encapsulates the entire public API surface, eliminating the need to manage multiple sub-headers individually.

## What Is the bpftime Runtime API Header File?

Located at [`runtime/include/bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/include/bpftime.hpp) in the eunomia-bpf/bpftime repository, this header serves as the single entry point for the bpftime user-space runtime. It aggregates core eBPF-VM definitions through `<ebpf-vm.h>` and pulls in configuration management, attachment contexts, user-defined functions, helper groups, program handling, and shared-memory management via its sub-includes.

The header declares C-compatible structures for trace events and Frida-Uprobe integration, enabling applications to load programs, create maps, attach probes, and interact with the shared-memory subsystem through a unified interface.

## Core Components Aggregated in [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp)

Rather than requiring developers to include individual subsystem headers, [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp) automatically exposes these key components:

- **[`bpftime_shm.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_shm.hpp)** — Defines the `bpftime_shm` class for shared-memory management and syscall-compatible BPF object operations.
- **[`bpftime_prog.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_prog.hpp)** — Provides program-related abstractions for creation, execution, and attachment handling.
- **[`bpftime_helper_group.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_helper_group.hpp)** — Registers and looks up helper functions used by eBPF programs during execution.
- **[`bpftime_ufunc.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_ufunc.hpp)** — Supports user-defined functions (UFUNC) within eBPF programs.
- **[`bpf_attach_ctx.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpf_attach_ctx.hpp)** — Manages attachment contexts for connecting programs to target functions.
- **[`bpftime_config.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_config.hpp)** — Handles runtime configuration parameters.

By including only [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp), applications gain complete access to the runtime API without managing dependency chains manually.

## Practical Usage Examples

### Loading and Attaching eBPF Programs

The following example demonstrates initializing shared memory, loading an eBPF program, and attaching it to a user-space function using the **bpftime runtime API header file**:

```cpp
#include <bpftime.hpp>

int main() {
    // Initialize the global shared memory (client side)
    bpftime_initialize_global_shm(bpftime::shm_open_type::client);

    // Load an eBPF program from an object file
    int prog_fd = bpftime_shm::global_shared_memory.add_bpf_prog(
        /*fd=*/-1,
        /*insn=*/my_ebpf_instructions,
        /*insn_cnt=*/sizeof(my_ebpf_instructions) / sizeof(ebpf_inst));

    // Attach the program to a user-space function (Uprobe)
    int uprobe_fd = bpftime_shm::global_shared_memory.add_uprobe(
        prog_fd,            // program to attach
        /*pid=*/12345,     // target process
        "my_target_func",  // symbol name
        /*offset=*/0);

    // Enable the attached program
    bpftime_shm::global_shared_memory.perf_event_enable(uprobe_fd);
}

```

### Creating and Manipulating Maps

This example shows map creation and element operations using the shared-memory interface exposed through the runtime header:

```cpp
#include <bpftime.hpp>

int main() {
    bpftime_initialize_global_shm(bpftime::shm_open_type::client);

    // Create an array map (key: uint32_t, value: uint64_t)
    int map_fd = bpftime_shm::global_shared_memory.add_map(
        /*map_type=*/BPF_MAP_TYPE_ARRAY,
        /*key_size=*/sizeof(uint32_t),
        /*value_size=*/sizeof(uint64_t),
        /*max_entries=*/128,
        /*flags=*/0);

    uint32_t key = 42;
    uint64_t value = 0;
    bpftime_shm::global_shared_memory.bpf_map_lookup_elem(
        map_fd, &key, &value);

    // Update the element
    value = 0xDEADBEEF;
    bpftime_shm::global_shared_memory.bpf_map_update_elem(
        map_fd, &key, &value, BPF_ANY);
}

```

## Summary

- The **bpftime runtime API header file** is located at [`runtime/include/bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/include/bpftime.hpp) in the eunomia-bpf/bpftime repository.
- This single header aggregates all runtime functionality including [`bpftime_shm.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_shm.hpp), [`bpftime_prog.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_prog.hpp), and helper group definitions.
- Applications initialize the runtime using `bpftime_initialize_global_shm()` before performing any operations.
- The API supports loading eBPF programs via `add_bpf_prog()`, attaching them with `add_uprobe()`, and managing maps through `add_map()` and related lookup/update functions.

## Frequently Asked Questions

### Where is the bpftime runtime API header file located?

The main header file is located at [`runtime/include/bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/runtime/include/bpftime.hpp) in the source tree. This path serves as the primary entry point for all public runtime symbols and is designed to be the only header application developers need to include.

### What functionality does [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp) provide?

According to the eunomia-bpf/bpftime source code, the header provides shared-memory management via `bpftime_shm`, program loading and attachment through `bpftime_prog` and `bpf_attach_ctx`, helper function registration via `bpftime_helper_group`, and user-defined function support through `bpftime_ufunc`. It also includes core eBPF-VM definitions required for instruction processing.

### Do I need to include additional headers beyond [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp)?

No. The [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp) header is designed as a comprehensive aggregation point that internally includes [`bpftime_shm.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_shm.hpp), [`bpftime_prog.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_prog.hpp), [`bpftime_config.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime_config.hpp), and other necessary sub-headers. Including only [`bpftime.hpp`](https://github.com/eunomia-bpf/bpftime/blob/main/bpftime.hpp) provides full access to the runtime API without managing individual component headers.

### How do I initialize the bpftime runtime before using the API?

Applications must call `bpftime_initialize_global_shm()` with the appropriate `bpftime::shm_open_type` (typically `client` for applications attaching to existing runtimes) before invoking any other API functions. This initializes the global shared memory subsystem that backs maps, programs, and attachment state.