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

The main runtime API header file in bpftime is 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 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 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

Rather than requiring developers to include individual subsystem headers, bpftime.hpp automatically exposes these key components:

• bpftime_shm.hpp — Defines the bpftime_shm class for shared-memory management and syscall-compatible BPF object operations.
• bpftime_prog.hpp — Provides program-related abstractions for creation, execution, and attachment handling.
• bpftime_helper_group.hpp — Registers and looks up helper functions used by eBPF programs during execution.
• bpftime_ufunc.hpp — Supports user-defined functions (UFUNC) within eBPF programs.
• bpf_attach_ctx.hpp — Manages attachment contexts for connecting programs to target functions.
• bpftime_config.hpp — Handles runtime configuration parameters.

By including only 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:

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

#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 in the eunomia-bpf/bpftime repository.
• This single header aggregates all runtime functionality including bpftime_shm.hpp, 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 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 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?

No. The bpftime.hpp header is designed as a comprehensive aggregation point that internally includes bpftime_shm.hpp, bpftime_prog.hpp, bpftime_config.hpp, and other necessary sub-headers. Including only 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}