eBPF Libbpf

https://docs.ebpf.io/ebpf-library/libbpf/
Admin
Libbpf is a C/C++ library that simplifies the development, loading, and management of eBPF programs...
Tokens:141,926
Snippets:1,262
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example usage of bpf_map_create

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_map_create

Demonstrates how to invoke bpf_map_create to create a hash map with basic parameters.

```c
// struct example_map{
//         __uint(type, BPF_MAP_TYPE_HASH);
//         __uint(max_entries, 10);
//         __type(key, __u32);
//         __type(value, __u32);
// };

int main(){
    int fd = bpf_map_create(
        BPF_MAP_TYPE_HASH,
        NULL,
        sizeof(__u32),
        sizeof(__u32),
        INNER_MAP_MAX_ENTRY,
        NULL
    );
    if(fd < 0)
        puts("error creating map");
}
```

--------------------------------

### BPF_KRETPROBE Usage Example

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_KRETPROBE

A practical example of using BPF_KRETPROBE to capture the return value of the do_unlinkat function.

```c
SEC("kretprobe/do_unlinkat")
int BPF_KRETPROBE(do_unlinkat_exit, long ret)
{
    pid_t pid;

    pid = bpf_get_current_pid_tgid() >> 32;
    bpf_printk("KPROBE EXIT: pid = %d, ret = %ld\n", pid, ret);
    return 0;
}
```

--------------------------------

### BPF_CORE_READ Usage Example

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_CORE_READ

A kprobe example demonstrating the use of BPF_CORE_READ to access sk_buff fields and BPF_CORE_READ_STR_INTO for string reading.

```c
/* Copyright (c) 2013-2015 PLUMgrid, http://plumgrid.com
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of version 2 of the GNU General Public
 * License as published by the Free Software Foundation.
 */
#include "vmlinux.h"
#include "net_shared.h"
#include <linux/version.h>
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_core_read.h>
#include <bpf/bpf_tracing.h>

/* kprobe is NOT a stable ABI
 * kernel functions can be removed, renamed or completely change semantics.
 * Number of arguments and their positions can change, etc.
 * In such case this bpf+kprobe example will no longer be meaningful
 */
SEC("kprobe.multi/__netif_receive_skb_core*")
int bpf_prog1(struct pt_regs *ctx)
{
    /* attaches to kprobe __netif_receive_skb_core,
     * looks for packets on loopback device and prints them
     * (wildcard is used for avoiding symbol mismatch due to optimization)
     */
    char devname[IFNAMSIZ];
    struct net_device *dev;
    struct sk_buff *skb;
    int len;

    bpf_core_read(&skb, sizeof(skb), (void *)PT_REGS_PARM1(ctx));
    dev = BPF_CORE_READ(skb, dev);
    len = BPF_CORE_READ(skb, len);

    BPF_CORE_READ_STR_INTO(&devname, dev, name);

    if (devname[0] == 'l' && devname[1] == 'o') {
        char fmt[] = "skb %p len %d\n";
        /* using bpf_trace_printk() for DEBUG ONLY */
        bpf_trace_printk(fmt, sizeof(fmt), skb, len);
    }

    return 0;
}

char _license[] SEC("license") = "GPL";
u32 _version SEC("version") = LINUX_VERSION_CODE;
```

--------------------------------

### Comparison of BPF_PROBE_READ_USER and BPF_PROBE_READ_USER_INTO

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_PROBE_READ_USER_INTO

Equivalent usage examples showing the difference between returning a value and writing it into a destination.

```c
int x = BPF_PROBE_READ_USER(s, a.b.c, d.e, f, g);
```

```c
int x;
BPF_PROBE_READ_USER_INTO(&x, s, a.b.c, d.e, f, g);
```

--------------------------------

### BPF_KPROBE Usage Example

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_KPROBE

An example of attaching a kprobe to 'bpf_map_copy_value' using the BPF_KPROBE macro to directly access the 'map' argument.

```c
SEC("kprobe/bpf_map_copy_value")
int BPF_KPROBE(bpf_prog2, struct bpf_map *map)
{
    u32 key = bpf_get_smp_processor_id();
    struct bpf_perf_event_value *val, buf;
    enum bpf_map_type type;
    int error;

    type = BPF_CORE_READ(map, map_type);
    if (type != BPF_MAP_TYPE_HASH)
        return 0;

    error = bpf_perf_event_read_value(&counters, key, &buf, sizeof(buf));
    if (error)
        return 0;

    val = bpf_map_lookup_elem(&values2, &key);
    if (val)
        *val = buf;
    else
        bpf_map_update_elem(&values2, &key, &buf, BPF_NOEXIST);

    return 0;
}
```

--------------------------------

### Implement kprobe with BPF_KSYSCALL

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_KSYSCALL

Example implementation of a kprobe program attached to the write syscall using the BPF_KSYSCALL macro.

```c
SEC("ksyscall/write")
int BPF_KSYSCALL(bpf_prog3, unsigned int fd, const char *buf, size_t count)
{
    long init_val = 1;
    long *value;
    struct hist_key key;

    key.index = log2l(count);
    key.pid_tgid = bpf_get_current_pid_tgid();
    key.uid_gid = bpf_get_current_uid_gid();
    bpf_get_current_comm(&key.comm, sizeof(key.comm));

    value = bpf_map_lookup_elem(&my_hist_map, &key);
    if (value)
        __sync_fetch_and_add(value, 1);
    else
        bpf_map_update_elem(&my_hist_map, &key, &init_val, BPF_ANY);
    return 0;
}
```

--------------------------------

### Example compilation unit type definitions

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/btf__dedup

Example structures representing partial type information across two different compilation units.

```c
// CU #1:
struct S;
struct A {
    int a;
    struct A* self;
    struct S* parent;
};
struct B;
struct S {
    struct A* a_ptr;
    struct B* b_ptr;
};

// CU #2:
struct S;
struct A;
struct B {
    int b;
    struct B* self;
    struct S* parent;
};
struct S {
    struct A* a_ptr;
    struct B* b_ptr;
};
```

--------------------------------

### Define structure for bpf_core_read usage

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_core_read

Example structure definition used to demonstrate field access via bpf_core_read.

```c
struct a {
    int b;
    struct {
        struct some_value *d;
    } c;
};
```

--------------------------------

### Usage of __percpu_kptr in eBPF programs

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__percpu_kptr

Example demonstrating the initialization, update, summarization, and deletion of per-CPU objects stored in a BPF map.

```c
#include "bpf_experimental.h"

struct val_t {
    long b, c, d;
};

struct elem {
    long sum;
    struct val_t __percpu_kptr *pc;
};

struct {
    __uint(type, BPF_MAP_TYPE_ARRAY);
    __uint(max_entries, 1);
    __type(key, int);
    __type(value, struct elem);
} array SEC(".maps");

void bpf_rcu_read_lock(void) __ksym;
void bpf_rcu_read_unlock(void) __ksym;

const volatile int nr_cpus;

/* Initialize the percpu object */
SEC("?fentry/bpf_fentry_test1")
int BPF_PROG(test_array_map_1)
{
    struct val_t __percpu_kptr *p;
    struct elem *e;
    int index = 0;

    e = bpf_map_lookup_elem(&array, &index);
    if (!e)
        return 0;

    p = bpf_percpu_obj_new(struct val_t);
    if (!p)
        return 0;

    p = bpf_kptr_xchg(&e->pc, p);
    if (p)
        bpf_percpu_obj_drop(p);

    return 0;
}

/* Update percpu data */
SEC("?fentry/bpf_fentry_test2")
int BPF_PROG(test_array_map_2)
{
    struct val_t __percpu_kptr *p;
    struct val_t *v;
    struct elem *e;
    int index = 0;

    e = bpf_map_lookup_elem(&array, &index);
    if (!e)
        return 0;

    p = e->pc;
    if (!p)
        return 0;

    v = bpf_per_cpu_ptr(p, 0);
    if (!v)
        return 0;
    v->c = 1;
    v->d = 2;

    return 0;
}

int cpu0_field_d, sum_field_c;
int my_pid;

/* Summarize percpu data */
SEC("?fentry/bpf_fentry_test3")
int BPF_PROG(test_array_map_3)
{
    struct val_t __percpu_kptr *p;
    int i, index = 0;
    struct val_t *v;
    struct elem *e;

    if ((bpf_get_current_pid_tgid() >> 32) != my_pid)
        return 0;

    e = bpf_map_lookup_elem(&array, &index);
    if (!e)
        return 0;

    p = e->pc;
    if (!p)
        return 0;

    bpf_for(i, 0, nr_cpus) {
        v = bpf_per_cpu_ptr(p, i);
        if (v) {
            if (i == 0)
                cpu0_field_d = v->d;
            sum_field_c += v->c;
        }
    }

    return 0;
}

/* Explicitly free allocated percpu data */
SEC("?fentry/bpf_fentry_test4")
int BPF_PROG(test_array_map_4)
{
    struct val_t __percpu_kptr *p;
    struct elem *e;
    int index = 0;

    e = bpf_map_lookup_elem(&array, &index);
    if (!e)
        return 0;

    /* delete */
    p = bpf_kptr_xchg(&e->pc, NULL);
    if (p) {
        bpf_percpu_obj_drop(p);
    }

    return 0;
}

SEC("?fentry.s/bpf_fentry_test1")
int BPF_PROG(test_array_map_10)
{
    struct val_t __percpu_kptr *p, *p1;
    int i, index = 0;
    struct val_t *v;
    struct elem *e;

    if ((bpf_get_current_pid_tgid() >> 32) != my_pid)
        return 0;

    e = bpf_map_lookup_elem(&array, &index);
    if (!e)
        return 0;

    bpf_rcu_read_lock();
    p = e->pc;
    if (!p) {
        p = bpf_percpu_obj_new(struct val_t);
        if (!p)
            goto out;

        p1 = bpf_kptr_xchg(&e->pc, p);
        if (p1) {
            /* race condition */
            bpf_percpu_obj_drop(p1);
        }
    }

    v = bpf_this_cpu_ptr(p);
    v->c = 3;
    v = bpf_this_cpu_ptr(p);
    v->c = 0;

    v = bpf_per_cpu_ptr(p, 0);
    if (!v)
        goto out;
    v->c = 1;
    v->d = 2;

    /* delete */
    p1 = bpf_kptr_xchg(&e->pc, NULL);
    if (!p1)
        goto out;

    bpf_for(i, 0, nr_cpus) {
        v = bpf_per_cpu_ptr(p, i);
        if (v) {
            if (i == 0)
                cpu0_field_d = v->d;
            sum_field_c += v->c;
        }
    }

    /* finally release p */
    bpf_percpu_obj_drop(p1);
out:
    bpf_rcu_read_unlock();
    return 0;
}

char _license[] SEC("license") = "GPL";
```

--------------------------------

### BPF_SNPRINTF Usage Example

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_snprintf

Example of using BPF_SNPRINTF within a TC program to format packet data into a ring buffer.

```c
struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, 4096);
} ringbuf SEC(".maps");

SEC("tc")
int example_prog(struct __sk_buff *ctx)
{
    const int size = 100;
    char *str_out = bpf_ringbuf_reserve(&ringbuf, size, 0);
    if (!str_out)
        return TC_ACT_OK;

    // `len` is the length of the formatted string including NULL-termination char.
    // if `len` > `size` then the string was truncated.
    // `len` can also be -EBUSY if the per-CPU memory copy buffer is busy.
    long len = BPF_SNPRINTF(str_out, size,
        "Got a packet from interface %d, src: %pi4, dst: %pi4, src port: %d, dst port: %d\n", 
        ctx->ingress_ifindex, 
        ctx->remote_ip4, 
        ctx->local_ip4,
        ctx->remote_port,
        ctx->local_port
    );

    bpf_ringbuf_submit(str_out, 0);

    return TC_ACT_OK;
}
```

--------------------------------

### Basic usage of container_of

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/container_of

An artificial example demonstrating how to retrieve a parent structure pointer from a member pointer.

```c
struct a {
    int x;
    int y;
    struct b b;
}

struct b {
    int z;
}

int some_func(struct b *b) {
    struct a *a = container_of(b, struct a, b);
    return a->y;
}
```

--------------------------------

### Use __kconfig in eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__kconfig

Example of declaring an external kernel configuration variable and using it to adjust logic at runtime.

```c
extern unsigned CONFIG_HZ __kconfig;

#define USER_HZ     100
#define NSEC_PER_SEC    1000000000ULL
static clock_t jiffies_to_clock_t(unsigned long x)
{
    /* The implementation here tailored to a particular
     * setting of USER_HZ.
     */
    u64 tick_nsec = (NSEC_PER_SEC + CONFIG_HZ/2) / CONFIG_HZ;
    u64 user_hz_nsec = NSEC_PER_SEC / USER_HZ;

    if ((tick_nsec % user_hz_nsec) == 0) {
        if (CONFIG_HZ < USER_HZ)
            return x * (USER_HZ / CONFIG_HZ);
        else
            return x / (CONFIG_HZ / USER_HZ);
    }
    return x * tick_nsec/user_hz_nsec;
}
```

--------------------------------

### Usage of bpf_core_type_matches in eBPF

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_core_type_matches

Example demonstrating conditional logic based on type matching for different kernel versions of a structure.

```c
struct rw_semaphore___old {
    struct task_struct *owner;
} __attribute__((preserve_access_index));

struct rw_semaphore___new {
    atomic_long_t owner;
} __attribute__((preserve_access_index));

static inline struct task_struct *get_lock_owner(__u64 lock, __u32 flags)
{
    struct task_struct *task;
    __u64 owner = 0;

    if (flags & LCB_F_MUTEX) {
        struct mutex *mutex = (void *)lock;
        owner = BPF_CORE_READ(mutex, owner.counter);
    } else if (flags == LCB_F_READ || flags == LCB_F_WRITE) {
        if (bpf_core_type_matches(struct rw_semaphore___old)) {
            struct rw_semaphore___old *rwsem = (void *)lock;
            owner = (unsigned long)BPF_CORE_READ(rwsem, owner);
        } else if (bpf_core_type_matches(struct rw_semaphore___new)) {
            struct rw_semaphore___new *rwsem = (void *)lock;
            owner = BPF_CORE_READ(rwsem, owner.counter);
        }
    }

    if (!owner)
        return NULL;

    task = (void *)(owner & ~7UL);
    return task;
}
```

--------------------------------

### Conditional Type Usage Example

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_core_type_exists

Demonstrates using existence checks to implement fallback logic for kernel structures.

```c
struct some_kernel_struct {
    int a;
    int b;
};

SEC("kprobe")
int kprobe__example(struct pt_regs *ctx)
{
    int b;

    // Depending on if some_kernel_struct exists on the kernel we are running on
    // one or the other branch is taken. The verifier will only evaluate the branch
    // that is taken, and will optimize the if statement away, so this does not
    // impact the program's performance.
    if (bpf_core_field_exists(struct some_kernel_struct)) {
        struct some_kernel_struct *a = PT_REGS_PARM1(ctx);
        int b = BPF_CORE_READ(a, b);
    } else {
        int b = more_complex_fallback_to_get_b();
    }

    bpf_printk("Value of field 'a' = %d", b);

    return 0;
}
```

--------------------------------

### Implement USDT Probe with BPF_USDT

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_USDT

Example of using BPF_USDT to define a program attached to a USDT tracepoint, allowing direct access to tracepoint arguments.

```c
// SPDX-License-Identifier: GPL-2.0
/* Copyright (c) 2022 Meta Platforms, Inc. and affiliates. */
SEC("usdt/./urandom_read:urand:read_without_sema")
int BPF_USDT(urand_read_without_sema, int iter_num, int iter_cnt, int buf_sz)
{
    if (urand_pid != (bpf_get_current_pid_tgid() >> 32))
        return 0;

    __sync_fetch_and_add(&urand_read_without_sema_call_cnt, 1);
    __sync_fetch_and_add(&urand_read_without_sema_buf_sz_sum, buf_sz);

    return 0;
}
```

--------------------------------

### Simplified iteration with bpf_for_each

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_for_each

Usage of the macro to iterate over tasks, which abstracts away the manual setup and cleanup steps.

```c
SEC("raw_tp/sys_enter")
int my_example(const void *ctx)
{
    struct task_struct *task_ptr;
    bpf_for_each(task, task_ptr, NULL, BPF_TASK_ITER_ALL_PROCS) {
        // Do something with the task pointer

        if (/* We found the task we are looking for*/)
            break;
    }

    return 0;
}
```

--------------------------------

### Usage of bpf_printk in eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_printk

Example demonstrating how to use bpf_printk to log messages with varying numbers of arguments in an eBPF program.

```c
SEC("tc")
int example_prog(struct __sk_buff *ctx)
{
    // Will use bpf_trace_printk
    bpf_printk(
        "Got a packet from interface %d, src: %pi4, dst: %pi4\n", 
        ctx->ingress_ifindex, 
        ctx->remote_ip4, 
        ctx->local_ip4,
    );

    // Will use bpf_trace_vprintk
    bpf_printk(
        "Got a packet from interface %d, src: %pi4, dst: %pi4, src port: %d, dst port: %d\n", 
        ctx->ingress_ifindex, 
        ctx->remote_ip4, 
        ctx->local_ip4,
        ctx->remote_port,
        ctx->local_port,
    );

    return TC_ACT_OK;
}
```

--------------------------------

### Use PT_REGS_SYSCALL_REGS in a kprobe

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/PT_REGS_SYSCALL_REGS

Example of attaching a kprobe to a syscall wrapper and extracting the syscall registers to read parameters.

```c
SEC("kprobe/" SYS_PREFIX "open")
int trace_sys_open(struct pt_regs *ctx)
{
    struct pt_regs *realregs = PT_REGS_SYSCALL_REGS(ctx);

    int flags;
    bpf_probe_read_kernel(&flags, sizeof(flags), &PT_REGS_PARM2_SYSCALL(realregs));
    if (flags & O_CREAT) {
        bpf_printk("Creating a file");
    }

    return 0;
}
```

--------------------------------

### Using BPF_PROG in eBPF Programs

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_PROG

Example of defining an eBPF program with typed arguments using the BPF_PROG macro.

```c
SEC("struct_ops/hid_device_event")
int BPF_PROG(filter_switch, struct hid_bpf_ctx *hid_ctx)
{
    __u8 *data = hid_bpf_get_data(hid_ctx, 0 /* offset */, 192 /* size */);
    __u8 *buf;

    if (!data)
        return 0; /* EPERM check */

    if (current_value != data[152]) {
        buf = bpf_ringbuf_reserve(&ringbuf, 1, 0);
        if (!buf)
            return 0;

        *buf = data[152];

        bpf_ringbuf_commit(buf, 0);

        current_value = data[152];
    }

    return 0;
}
```

--------------------------------

### Use __arg_ctx in global functions

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__arg_ctx

Example showing a global function accepting a generic context and its usage within different program types.

```c
struct {
    __uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY);
    __uint(key_size, sizeof(__u32));
    __uint(value_size, sizeof(int));
} events SEC(".maps");

int send_msg(void *ctx __arg_ctx)
{
    char msg[] = "Some common message";
    return bpf_perf_event_output(ctx, &events, 0, msg, sizeof(msg));
}

SEC("kprobe/eth_type_trans")
int kprobe__sys_open(struct pt_regs *ctx)
{
    send_msg(ctx);
    return 0;
}

SEC("fentry/eth_type_trans")
int BPF_PROG(fentry_eth_type_trans, struct sk_buff *skb,
         struct net_device *dev, unsigned short protocol)
{
    // Note: The BPF_PROG does some magic to give us typed arguments, but `ctx` is still preserved as the
    // context passed into the program.
    send_msg(ctx);
    return 0;
}
```

--------------------------------

### Apply SEC macro to an XDP program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/SEC

Example of using the SEC macro to place an XDP program into the xdp ELF section.

```c
SEC("xdp")
int example_prog(struct xdp_md *ctx)
{
    void *data_end = (void *)(long)ctx->data_end;
    void *data = (void *)(long)ctx->data;

    if (data + sizeof(struct ethhdr) > data_end)
        return XDP_DROP;

    struct ethhdr *eth = data;
    if (eth->h_proto == htons(ETH_P_IP))
        return XDP_PASS;
}
```

--------------------------------

### Usage of bpf_tail_call_static in XDP

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_tail_call_static

Example demonstrating the definition of a BPF_MAP_TYPE_PROG_ARRAY and its usage within an XDP program to perform static tail calls.

```c
#define TAIL_CALL_ZERO 0
#define TAIL_CALL_ONE 1

struct {
    __uint(type, BPF_MAP_TYPE_PROG_ARRAY);
    __uint(max_entries, 2);
    __uint(key_size, sizeof(__u32));
    __array(values, int (void *));
} prog_array_map SEC(".maps") = {
    .values = {
        [TAIL_CALL_ZERO] = (void *)&tailcall_0,
        [TAIL_CALL_ONE] = (void *)&tailcall_1,
    },
};

SEC("xdp")
int tailcall_0(struct xdp_md *ctx)
{
    return XDP_PASS;
}

SEC("xdp")
int tailcall_1(struct xdp_md *ctx)
{
    return XDP_DROP;
}

SEC("xdp")
int xdp_prog(struct xdp_md *ctx)
{
    void *data_end = (void *)(long)ctx->data_end;
    void *data = (void *)(long)ctx->data;

    if (data + sizeof(struct ethhdr) > data_end)
        return bpf_tail_call_static(skb, &prog_array_map, TAIL_CALL_ONE);

    return bpf_tail_call_static(skb, &prog_array_map, TAIL_CALL_ZERO);
}
```

--------------------------------

### Use __ksym to resolve kernel symbols

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__ksym

Example demonstrating the use of __ksym to access a kernel symbol and read its value within an eBPF program.

```c
// SPDX-License-Identifier: GPL-2.0
/* Copyright (C) 2022. Huawei Technologies Co., Ltd */
#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_tracing.h>

extern bool CONFIG_PREEMPT __kconfig __weak;
extern const int bpf_task_storage_busy __ksym;

char _license[] SEC("license") = "GPL";

int pid = 0;
int busy = 0;

struct {
    __uint(type, BPF_MAP_TYPE_TASK_STORAGE);
    __uint(map_flags, BPF_F_NO_PREALLOC);
    __type(key, int);
    __type(value, long);
} task SEC(".maps");

SEC("raw_tp/sys_enter")
int BPF_PROG(read_bpf_task_storage_busy)
{
    int *value;

    if (!CONFIG_PREEMPT)
        return 0;

    if (bpf_get_current_pid_tgid() >> 32 != pid)
        return 0;

    value = bpf_this_cpu_ptr(&bpf_task_storage_busy);
    if (value)
        busy = *value;

    return 0;
}
```

--------------------------------

### Usage of bpf_repeat in eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_repeat

Example showing the macro used within a raw tracepoint program to repeat an operation 64 times.

```c
SEC("raw_tp/sys_enter")
int iter_next_rcu(const void *ctx)
{
    bpf_repeat(64) {
        if (try_to_do_something())
            break;
    }
}
```

--------------------------------

### Implement arena-based hash table operations

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__arg_arena

Example demonstrating the use of __arg_arena in global function signatures for hash table lookup and update operations within an eBPF arena.

```c
/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
/* Copyright (c) 2024 Meta Platforms, Inc. and affiliates. */
#pragma once
#include <errno.h>
#include "bpf_arena_alloc.h"
#include "bpf_arena_list.h"

struct htab_bucket {
    struct arena_list_head head;
};
typedef struct htab_bucket __arena htab_bucket_t;

struct htab {
    htab_bucket_t *buckets;
    int n_buckets;
};
typedef struct htab __arena htab_t;

static inline htab_bucket_t *__select_bucket(htab_t *htab, __u32 hash)
{
    htab_bucket_t *b = htab->buckets;

    cast_kern(b);
    return &b[hash & (htab->n_buckets - 1)];
}

static inline arena_list_head_t *select_bucket(htab_t *htab, __u32 hash)
{
    return &__select_bucket(htab, hash)->head;
}

struct hashtab_elem {
    int hash;
    int key;
    int value;
    struct arena_list_node hash_node;
};
typedef struct hashtab_elem __arena hashtab_elem_t;

static hashtab_elem_t *lookup_elem_raw(arena_list_head_t *head, __u32 hash, int key)
{
    hashtab_elem_t *l;

    list_for_each_entry(l, head, hash_node)
        if (l->hash == hash && l->key == key)
            return l;

    return NULL;
}

static int htab_hash(int key)
{
    return key;
}

__weak int htab_lookup_elem(htab_t *htab __arg_arena, int key)
{
    hashtab_elem_t *l_old;
    arena_list_head_t *head;

    cast_kern(htab);
    head = select_bucket(htab, key);
    l_old = lookup_elem_raw(head, htab_hash(key), key);
    if (l_old)
        return l_old->value;
    return 0;
}

__weak int htab_update_elem(htab_t *htab __arg_arena, int key, int value)
{
    hashtab_elem_t *l_new = NULL, *l_old;
    arena_list_head_t *head;

    cast_kern(htab);
    head = select_bucket(htab, key);
    l_old = lookup_elem_raw(head, htab_hash(key), key);

    l_new = bpf_alloc(sizeof(*l_new));
    if (!l_new)
        return -ENOMEM;
    l_new->key = key;
    l_new->hash = htab_hash(key);
    l_new->value = value;

    list_add_head(&l_new->hash_node, head);
    if (l_old) {
        list_del(&l_old->hash_node);
        bpf_free(l_old);
    }
    return 0;
}

void htab_init(htab_t *htab)
{
    void __arena *buckets = bpf_arena_alloc_pages(&arena, NULL, 2, NUMA_NO_NODE, 0);

    cast_user(buckets);
    htab->buckets = buckets;
    htab->n_buckets = 2 * PAGE_SIZE / sizeof(struct htab_bucket);
}
```

--------------------------------

### Define libbpf_prog_setup_fn_t callback

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/struct-libbpf_prog_handler_opts

Callback signature for BPF program initialization during bpf_object__open.

```c
typedef int (*libbpf_prog_setup_fn_t)(struct bpf_program *prog, long cookie);
```

--------------------------------

### Define libbpf_prog_prepare_load_fn_t callback

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/struct-libbpf_prog_handler_opts

Callback signature for BPF program loading, executed before bpf_prog_load.

```c
typedef int (*libbpf_prog_prepare_load_fn_t)(struct bpf_program *prog,
                         struct bpf_prog_load_opts *opts, long cookie);
```

--------------------------------

### bpf_linker__new

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_linker__new

Initializes a new BPF linker instance from a specified file path and optional configuration.

```APIDOC
## bpf_linker__new

### Definition
`struct bpf_linker *bpf_linker__new(const char *filename, struct bpf_linker_opts *opts);`

### Description
Creates a new `struct bpf_linker` object from a file. The linker is used to statically link multiple BPF objects together into a single ELF file.

### Parameters
- **filename** (const char *) - Required - The name of the first file to load the BPF object from. On `bpf_linker__finalize`, the linker will write the linked ELF file to this path.
- **opts** (struct bpf_linker_opts *) - Optional - A pointer to a `struct bpf_linker_opts` object that contains options for the linker.

### struct bpf_linker_opts
```c
struct bpf_linker_opts {
    size_t sz; /* size of this struct, for forward/backward compatibility */
};
```
```

--------------------------------

### Read task parent pointer

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_core_read

Practical example of reading the parent task pointer from a task_struct.

```c
struct task_struct *task = (void *)bpf_get_current_task();
struct task_struct *parent_task;
int err;

err = bpf_core_read(&parent_task, sizeof(void *), &task->parent);
if (err) {
    /* handle error */
}

/* parent_task contains the value of task->parent pointer */
```

--------------------------------

### Use __noinline in an eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__noinline

Example of applying the macro to a function to ensure it is not inlined by the compiler.

```c
static int __noinline add(int a, int b)
{
    return a + b;
}

SEC("xdp")
int example_prog(struct xdp_md *ctx)
{
    if (add(1, 2) == 3)
        return XDP_PASS;
    else
        return XDP_DROP;
}
```

--------------------------------

### int bpf_raw_tracepoint_open(const char *name, int prog_fd)

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_raw_tracepoint_open

Opens a raw tracepoint and attaches a BPF program to it.

```APIDOC
## int bpf_raw_tracepoint_open(const char *name, int prog_fd)

### Description
Low level wrapper around the BPF_RAW_TRACEPOINT_OPEN syscall command. This function should only be used if you need precise control over the raw tracepoint opening process.

### Parameters
- **name** (const char *) - Required - Name of the raw tracepoint.
- **prog_fd** (int) - Required - BPF program file descriptor.

### Return
- **int** - Returns a file descriptor of the raw tracepoint if successful (>0), or a negative error code on failure.
```

--------------------------------

### Use bpf_core_field_offset in eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_core_field_offset

Example demonstrating how to retrieve the offset of a struct field within a kprobe.

```c
struct some_kernel_struct {
    __u16 field1; // This field might be smaller or larger on the target kernel
    __u32 field2;
}

SEC("kprobe")
int kprobe__example(struct pt_regs *ctx)
{
    struct some_kernel_struct *a = PT_REGS_PARM1(ctx);
    int field_offset = bpf_core_field_offset(a->field2)

    // Do something with field_offset
    // ...

    return 0;
}
```

--------------------------------

### Attach BPF program to cgroup

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_program__attach_cgroup

Demonstrates opening a cgroup directory and attaching a BPF program using bpf_program__attach_cgroup.

```c
int main(int argc, char **argv)
{
    if (argc != 2) {
        fprintf(stderr, "Usage: %s <cgroup_path> (e.g '/sys/fs/cgroup/system.slice/'\n", argv[0]);
        return 1;
    }

    // Obtain cgroup fd
    const char *cgroup_path = argv[1];
    int cgroup_fd = open(cgroup_path, O_RDONLY);
    if (cgroup_fd < 0) {
        perror("open");
        return 1;
    }

    LIBBPF_OPTS(bpf_object_open_opts, opts);

    struct perf_buffer *pb = NULL;
    struct file_lsm_bpf *obj;
    int err;

    obj = file_lsm_bpf__open_opts(&opts);
    err = bpf_object__load(obj->obj);
    struct bpf_link *link = bpf_program__attach_cgroup(obj->progs.lsm_file, cgroup_fd);
    if (!link) {
        fprintf(stderr, "failed to attach BPF program to cgroup\n");
        goto cleanup;
    }
}
```

--------------------------------

### Definition of ___bpf_fill macros

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/___bpf_fill

These macros recursively assign variadic arguments to an array starting at a specified index.

```c
#define ___bpf_fill0(arr, p, x) do {} while (0)
#define ___bpf_fill1(arr, p, x) arr[p] = x
#define ___bpf_fill2(arr, p, x, args...) arr[p] = x; ___bpf_fill1(arr, p + 1, args)
#define ___bpf_fill3(arr, p, x, args...) arr[p] = x; ___bpf_fill2(arr, p + 1, args)
#define ___bpf_fill4(arr, p, x, args...) arr[p] = x; ___bpf_fill3(arr, p + 1, args)
#define ___bpf_fill5(arr, p, x, args...) arr[p] = x; ___bpf_fill4(arr, p + 1, args)
#define ___bpf_fill6(arr, p, x, args...) arr[p] = x; ___bpf_fill5(arr, p + 1, args)
#define ___bpf_fill7(arr, p, x, args...) arr[p] = x; ___bpf_fill6(arr, p + 1, args)
#define ___bpf_fill8(arr, p, x, args...) arr[p] = x; ___bpf_fill7(arr, p + 1, args)
#define ___bpf_fill9(arr, p, x, args...) arr[p] = x; ___bpf_fill8(arr, p + 1, args)
#define ___bpf_fill10(arr, p, x, args...) arr[p] = x; ___bpf_fill9(arr, p + 1, args)
#define ___bpf_fill11(arr, p, x, args...) arr[p] = x; ___bpf_fill10(arr, p + 1, args)
#define ___bpf_fill12(arr, p, x, args...) arr[p] = x; ___bpf_fill11(arr, p + 1, args)
#define ___bpf_fill(arr, args...) \
    ___bpf_apply(___bpf_fill, ___bpf_narg(args))(arr, 0, args)
```

--------------------------------

### int bpf_btf_load(const void *btf_data, size_t btf_size, struct bpf_btf_load_opts *opts)

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_btf_load

Loads BTF data into the kernel using the BPF_BTF_LOAD syscall command.

```APIDOC
## int bpf_btf_load(const void *btf_data, size_t btf_size, struct bpf_btf_load_opts *opts)

### Description
Low-level wrapper around the BPF_BTF_LOAD syscall command. This function should only be used if you need precise control over the BTF loading process.

### Parameters
- **btf_data** (const void *) - Pointer to the BTF data to load.
- **btf_size** (size_t) - Size of the BTF data.
- **opts** (struct bpf_btf_load_opts *) - Options for the BTF load.

### struct bpf_btf_load_opts
- **sz** (size_t) - Size of this struct for forward/backward compatibility.
- **log_buf** (char *) - Kernel log buffer.
- **log_level** (__u32) - Kernel log level.
- **log_size** (__u32) - Size of the log buffer.
- **log_true_size** (__u32) - Output: actual total log contents size.
- **btf_flags** (__u32) - BTF loading flags.
- **token_fd** (__u32) - Token file descriptor.
```

--------------------------------

### Compare BPF_PROBE_READ_INTO and BPF_PROBE_READ usage

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_PROBE_READ_INTO

Demonstrates the functional equivalence between BPF_PROBE_READ_INTO and the standard BPF_PROBE_READ macro.

```c
int x = BPF_PROBE_READ_INTO(s, a.b.c, d.e, f, g);
```

```c
int x;
BPF_PROBE_READ(&x, s, a.b.c, d.e, f, g);
```

--------------------------------

### Setting an inner map file descriptor

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_map__set_inner_map_fd

Demonstrates creating a template map and associating its file descriptor with an outer map before loading the BPF skeleton.

```c
// outer map
// struct {
//         __uint(type, BPF_MAP_TYPE_HASH_OF_MAPS);
//         __uint(max_entries, 8);
//         __type(key, u32);
//         __type(value, u32);
// } outer_map SEC(".maps");

// we will create this map in user space
// struct inner_map {
//         __uint(type, BPF_MAP_TYPE_HASH);
//         __uint(max_entries, 10);
//         __type(key, __u32);
//         __type(value, __u32);
// };

int create_template_map(){
    int fd = bpf_map_create(
        BPF_MAP_TYPE_HASH,
        NULL,
        sizeof(__u32),
        sizeof(__u32),
        10,
        NULL
    );
    return fd;
}
int main(){
    struct tracer_bpf *skel = tracer_bpf__open();

    int fd = create_template_map();

    bpf_map__set_inner_map_fd(skel->maps.outer_map, fd);

    tracer_bpf__load(skel);
    close(fd); //we don't need template map fd anymore

    tracer_bpf__attach(skel);

    puts("looping forever");
    while(1){}

    return 0;
}
```

--------------------------------

### Use __always_inline in an eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/__always_inline

Example of applying the __always_inline macro to a helper function within an XDP program.

```c
static int __always_inline add(int a, int b)
{
    return a + b;
}

SEC("xdp")
int example_prog(struct xdp_md *ctx)
{
    if (add(1, 2) == 3)
        return XDP_PASS;
    else
        return XDP_DROP;
}
```

--------------------------------

### Use BPF_PROG2 in an eBPF program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_PROG2

Example of using BPF_PROG2 to define a program that handles a 16-byte argument correctly.

```c
SEC("fexit/__sys_bpf")
int BPF_PROG2(sys_bpf, int, cmd, bpfptr_t, uattr, unsigned int, size, int, ret)
{
    bpf_printf("BPF syscall returned with: %d", ret);
    return 0;
}
```

--------------------------------

### struct btf *libbpf_find_kernel_btf(void)

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/libbpf_find_kernel_btf

This function is an alias for btf__load_vmlinux_btf and is used to find and load the kernel BTF.

```APIDOC
## struct btf *libbpf_find_kernel_btf(void)

### Description
Finds and loads the kernel BTF. Note that this function has been renamed to `btf__load_vmlinux_btf` as of libbpf v0.5.0 and is maintained as an alias.

### Signature
`struct btf *libbpf_find_kernel_btf(void);`
```

--------------------------------

### BPF_CORE_READ_USER vs BPF_CORE_READ_USER_INTO Usage

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/BPF_CORE_READ_USER_INTO

Comparison showing how BPF_CORE_READ_USER_INTO writes to a destination pointer instead of returning a value.

```c
int x = BPF_CORE_READ_USER(s, a.b.c, d.e, f, g);
```

```c
int x;
BPF_CORE_READ_USER_INTO(&x, s, a.b.c, d.e, f, g);
```

--------------------------------

### bpf_object__next_program

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_object__next_program

Iterates over the programs in a BPF object. Pass NULL as the second argument to start the iteration from the first program.

```APIDOC
## bpf_object__next_program

### Definition
`struct bpf_program * bpf_object__next_program(const struct bpf_object *obj, struct bpf_program *prog);`

### Parameters
- **obj** (const struct bpf_object *) - Required - The BPF object to iterate over.
- **prog** (struct bpf_program *) - Required - The current program, or NULL to start iteration.

### Returns
- **struct bpf_program*** - The next program in the object, or NULL if there are no more programs.
```

--------------------------------

### int bpf_raw_tracepoint_open_opts(int prog_fd, struct bpf_raw_tp_opts *opts)

Source: https://docs.ebpf.io/ebpf-library/libbpf/userspace/bpf_raw_tracepoint_open_opts

Opens a raw tracepoint using the provided BPF program file descriptor and configuration options.

```APIDOC
## int bpf_raw_tracepoint_open_opts(int prog_fd, struct bpf_raw_tp_opts *opts)

### Description
Low-level wrapper around the BPF_RAW_TRACEPOINT_OPEN syscall command. This function should only be used if precise control over the raw tracepoint opening process is required.

### Parameters
- **prog_fd** (int) - BPF program file descriptor.
- **opts** (struct bpf_raw_tp_opts*) - Options for configuring the raw tracepoint.

### Return
- Returns a file descriptor (>0) of the raw tracepoint on success, or a negative error code on failure.

### Struct bpf_raw_tp_opts
```c
struct bpf_raw_tp_opts {
    size_t sz; /* size of this struct for forward/backward compatibility */
    const char *tp_name;
    __u64 cookie;
    size_t :0;
};
```
```

--------------------------------

### Usage of bpf_htonl in eBPF bind program

Source: https://docs.ebpf.io/ebpf-library/libbpf/ebpf/bpf_htonl

Example demonstrating the use of bpf_htonl to convert an IP address for a cgroup/bind4 program.

```c
#define SERV4_IP        0xc0a801feU /* 192.168.1.254 */
#define SERV4_PORT      4040

SEC("cgroup/bind4")
int bind_v4_prog(struct bpf_sock_addr *ctx)
{
    struct bpf_sock *sk;

    sk = ctx->sk;
    if (!sk)
        return 0;

    if (sk->family != AF_INET)
        return 0;

    if (ctx->user_ip4 != bpf_htonl(SERV4_IP) ||
        ctx->user_port != bpf_htons(SERV4_PORT))
        return 0;

    return 1;
}
```
Tokens:
Raw