clj-ebpf.syscall — org.clojars.pgdad/clj-ebpf 0.9.0

Low-level BPF syscall interface using Java Panama FFI (Java 25+)

allocate-zeroed clj

(allocate-zeroed size)

Allocate zeroed memory segment. Must be called within a with-bpf-syscall block.

AT_FDCWD clj

bpf-iter-create clj

(bpf-iter-create link-fd flags)

Create an iterator file descriptor from a BPF link.

BPF_ITER_CREATE takes a link FD and returns a file descriptor that can be read() to iterate over kernel data structures.

Parameters:

• link-fd: BPF link file descriptor (from bpf-link-create-iter)
• flags: Flags (usually 0)

Returns iterator FD on success, throws on error.

Usage: ;; Create iterator (def iter-fd (bpf-iter-create link-fd 0)) ;; Read from it (using Java FileInputStream or read syscall) ;; Each read() invokes the BPF program for the next batch

bpf-link-create-fentry clj

(bpf-link-create-fentry prog-fd btf-id attach-type)

Create a BPF link for fentry/fexit using BPF_LINK_CREATE attach-type should be :trace-fentry or :trace-fexit Returns link FD

Note: For programs loaded with attach_btf_id set (via load-fentry-program), target_fd and target_btf_id should both be 0. The kernel uses the BTF ID that was set during program load.

bpf-link-create-iter clj

(bpf-link-create-iter prog-fd
                      {:keys [iter-type map-fd cgroup-fd]
                       :or {map-fd 0 cgroup-fd 0}})

Create a BPF link for an iterator program.

BPF iterators use BPF_LINK_CREATE with iter-specific information in the link_create.iter_info union.

Parameters:

• prog-fd: BPF program file descriptor (tracing type)
• iter-info: Map with iterator configuration:
  • :iter-type - Iterator type name (e.g., "task", "bpf_map", "tcp")
  • :map-fd - (optional) Map FD for bpf_map_elem iterator
  • :cgroup-fd - (optional) Cgroup FD for cgroup iterators

Returns link FD on success, throws on error.

Note: The iterator type is typically encoded via BTF ID of the iterator target type (e.g., bpf_iter__task).

bpf-link-create-kprobe clj

(bpf-link-create-kprobe prog-fd function-name retprobe?)

Create a BPF link for kprobe using BPF_LINK_CREATE (modern method) Returns link FD

bpf-link-create-netns clj

(bpf-link-create-netns prog-fd netns-fd attach-type)

Create a BPF link for network namespace attachment using BPF_LINK_CREATE.

Used for SK_LOOKUP programs that need to attach to a network namespace.

Parameters:

• prog-fd: BPF program file descriptor
• netns-fd: Network namespace file descriptor (from /proc/self/ns/net or similar)
• attach-type: Attachment type keyword (e.g., :sk-lookup)

Returns link FD on success, throws on error.

bpf-link-create-struct-ops clj

(bpf-link-create-struct-ops map-fd)

Create a BPF link for a STRUCT_OPS map.

STRUCT_OPS links register the struct_ops implementation with the kernel, making it available for use (e.g., as a TCP congestion control algorithm).

Parameters:

• map-fd: STRUCT_OPS map file descriptor

Returns link FD on success, throws on error.

Note: For struct_ops, the link is created from the map, not from a program. The programs are referenced via the map's value structure.

bpf-syscall clj

(bpf-syscall cmd attr-mem)

Make a BPF syscall with the given command and attributes

close-fd clj

(close-fd fd)

Close a file descriptor

errno->keyword clj

(errno->keyword errno-num)

Convert errno number to keyword

file-open clj

(file-open path flags)

(file-open path flags mode)

Open a file using the openat syscall.

Arguments:

• path: File path (string)
• flags: Open flags (e.g., O_RDONLY, O_RDWR, O_CREAT | O_WRONLY)
• mode: File mode for creation (default 0644, only used with O_CREAT)

Returns file descriptor on success, throws on error.

Examples: (file-open "/tmp/test.txt" O_RDONLY) (file-open "/tmp/new.txt" (bit-or O_CREAT O_WRONLY) 0644)

file-read clj

(file-read fd size)

Read from a file descriptor using the read syscall.

Arguments:

• fd: File descriptor (from file-open)
• size: Maximum number of bytes to read

Returns a byte array containing the data read, or empty array on EOF. Throws on error.

Examples: (let [fd (file-open "/etc/passwd" O_RDONLY)] (try (let [data (file-read fd 1024)] (println (String. data))) (finally (close-fd fd))))

file-read-all clj

(file-read-all path)

Read entire contents of a file.

Arguments:

• path: File path (string)

Returns byte array with file contents. Throws on error.

Example: (String. (file-read-all "/etc/hostname"))

file-write clj

(file-write fd data)

Write to a file descriptor using the write syscall.

Arguments:

• fd: File descriptor (from file-open)
• data: Byte array or string to write

Returns the number of bytes written. Throws on error.

Examples: (let [fd (file-open "/tmp/test.txt" (bit-or O_CREAT O_WRONLY) 0644)] (try (file-write fd "Hello, World!\n") (finally (close-fd fd))))

file-write-all clj

(file-write-all path data)

(file-write-all path data mode)

Write data to a file, creating or truncating it.

Arguments:

• path: File path (string)
• data: Byte array or string to write
• mode: File permissions (default 0644)

Returns number of bytes written. Throws on error.

Example: (file-write-all "/tmp/hello.txt" "Hello, World!\n")

get-errno clj

(get-errno)

Get the last errno value

ioctl clj

(ioctl fd request)

(ioctl fd request arg)

Make an ioctl syscall

map-batch-attr->segment clj

(map-batch-attr->segment attr)

Convert MapBatchAttr to MemorySegment for syscall

Layout (offsets for batch operations):

• map_fd: offset 0 (u32)
• batch union: offset 8 (u64)
  • in_batch: pointer
  • out_batch: pointer
  • keys: pointer
• values: offset 16 (u64 pointer)
• count: offset 24 (u32)
• elem_flags: offset 32 (u64)

map-create clj

(map-create {:keys [map-type key-size value-size max-entries map-flags
                    inner-map-fd numa-node map-name map-ifindex btf-fd
                    btf-key-type-id btf-value-type-id btf-vmlinux-value-type-id
                    map-extra]
             :or {map-flags 0}})

Create a BPF map

map-create-attr->segment clj

(map-create-attr->segment attr)

Convert MapCreateAttr to MemorySegment for syscall

map-delete-batch clj

(map-delete-batch map-fd
                  keys-seg
                  count
                  &
                  {:keys [elem-flags] :or {elem-flags 0}})

Batch delete elements from BPF map

Parameters:

• map-fd: Map file descriptor
• keys-seg: MemorySegment for keys array
• count: Number of elements to delete
• elem-flags: Flags for elements (default 0)

Returns the number of elements successfully deleted.

map-delete-elem clj

(map-delete-elem map-fd key-seg)

Delete element from BPF map

map-elem-attr->segment clj

(map-elem-attr->segment attr)

Convert MapElemAttr to MemorySegment for syscall

map-get-next-key clj

(map-get-next-key map-fd key-seg next-key-seg)

Get next key in BPF map (for iteration)

map-lookup-and-delete-batch clj

(map-lookup-and-delete-batch map-fd
                             keys-seg
                             values-seg
                             count
                             &
                             {:keys [elem-flags] :or {elem-flags 0}})

Batch lookup and delete elements in BPF map

Parameters:

• map-fd: Map file descriptor
• keys-seg: MemorySegment for keys array
• values-seg: MemorySegment for values array
• count: Number of elements to lookup and delete
• elem-flags: Flags for elements (default 0)

Returns the number of elements successfully processed. Elements are deleted from the map after being read.

map-lookup-and-delete-elem clj

(map-lookup-and-delete-elem map-fd key-seg value-seg)

Atomically lookup and delete element from BPF map.

This is required for stack and queue maps where pop operations must be atomic. Regular maps can also use this for atomic lookup-and-delete operations.

map-lookup-batch clj

(map-lookup-batch map-fd
                  keys-seg
                  values-seg
                  count
                  &
                  {:keys [elem-flags] :or {elem-flags 0}})

Batch lookup elements in BPF map

Parameters:

• map-fd: Map file descriptor
• keys-seg: MemorySegment for keys array
• values-seg: MemorySegment for values array
• count: Number of elements to lookup
• elem-flags: Flags for elements (default 0)

Returns the number of elements successfully looked up. The count field in the attr structure is updated with the actual count.

map-lookup-elem clj

(map-lookup-elem map-fd key-seg value-seg)

Lookup element in BPF map

map-next-key-attr->segment clj

(map-next-key-attr->segment attr)

Convert MapNextKeyAttr to MemorySegment for syscall

map-update-batch clj

(map-update-batch map-fd
                  keys-seg
                  values-seg
                  count
                  &
                  {:keys [elem-flags] :or {elem-flags 0}})

Batch update elements in BPF map

Parameters:

• map-fd: Map file descriptor
• keys-seg: MemorySegment for keys array
• values-seg: MemorySegment for values array
• count: Number of elements to update
• elem-flags: Flags for elements (default 0, can be BPF_ANY, BPF_NOEXIST, BPF_EXIST)

Returns the number of elements successfully updated.

map-update-elem clj

(map-update-elem map-fd key-seg value-seg flags)

Update element in BPF map

O_APPEND clj

O_CLOEXEC clj

O_CREAT clj

O_EXCL clj

O_NONBLOCK clj

O_RDONLY clj

O_RDWR clj

O_TRUNC clj

O_WRONLY clj

obj-get clj

(obj-get pathname & {:keys [file-flags] :or {file-flags 0}})

Get BPF object from filesystem

obj-pin clj

(obj-pin pathname bpf-fd & {:keys [file-flags] :or {file-flags 0}})

Pin BPF object to filesystem

obj-pin-attr->segment clj

(obj-pin-attr->segment attr)

Convert ObjPinAttr to MemorySegment for syscall. Must be called within a with-bpf-syscall block.

parse-btf-vmlinux clj

(parse-btf-vmlinux func-name)

Parse vmlinux BTF to find function type ID by name. Returns the BTF type ID (1-based) or nil if not found.

perf-event-open clj

(perf-event-open event-type config pid cpu group-fd flags)

Open a perf event (used for kprobes/uprobes/tracepoints)

prog-load clj

(prog-load {:keys [prog-type insn-cnt insns license log-level log-size log-buf
                   kern-version prog-flags prog-name prog-ifindex
                   expected-attach-type prog-btf-fd func-info-rec-size func-info
                   func-info-cnt line-info-rec-size line-info line-info-cnt
                   attach-btf-id attach-prog-fd]
            :or {log-level 0 log-size 0 kern-version 0 prog-flags 0}})

Load a BPF program

prog-load-attr->segment clj

(prog-load-attr->segment attr)

Convert ProgLoadAttr to MemorySegment for syscall. Must be called within a with-bpf-syscall block.

prog-test-run clj

(prog-test-run
  prog-fd
  {:keys [data-in data-size-out ctx-in ctx-size-out repeat flags cpu]
   :or {data-size-out nil ctx-in nil ctx-size-out 0 repeat 1 flags 0 cpu 0}})

Run a BPF program in test mode with synthetic input.

This uses the BPF_PROG_TEST_RUN command to execute a BPF program without attaching it to a real hook.

Parameters:

• prog-fd: Program file descriptor
• opts: Map with:
  • :data-in - Input data as byte array (e.g., packet data)
  • :data-size-out - Size of output buffer (default: size of data-in or 256)
  • :ctx-in - Context data as byte array (program-type specific)
  • :ctx-size-out - Size of context output buffer (default: 0)
  • :repeat - Number of times to run (default: 1, for benchmarking)
  • :flags - Test run flags (default: 0)
  • :cpu - CPU to run on (default: 0, use -1 for any)

Returns a map with:

• :retval - Return value from BPF program (e.g., XDP_PASS=2, XDP_DROP=1)
• :data-out - Output data (byte array, modified packet)
• :ctx-out - Output context (byte array, if ctx-size-out > 0)
• :duration-ns - Execution time in nanoseconds (average if repeat > 1)
• :data-size-out - Actual size of output data

Example:

;; Test an XDP program
(let [packet (byte-array [...])
      result (prog-test-run prog-fd {:data-in packet :repeat 1000})]
  (println "Return value:" (:retval result))
  (println "Duration:" (:duration-ns result) "ns"))

Supported program types:

• XDP (xdp_md context)
• Sched CLS/ACT (sk_buff context)
• Socket filter
• Raw tracepoint
• Flow dissector

prog-test-run-attr->segment clj

(prog-test-run-attr->segment attr)

Convert ProgTestRunAttr to MemorySegment for syscall.

bpf_attr for BPF_PROG_TEST_RUN layout: offset 0: prog_fd (u32) offset 4: retval (u32) - output offset 8: data_size_in (u32) offset 12: data_size_out (u32) - input/output offset 16: data_in (u64 pointer) offset 24: data_out (u64 pointer) offset 32: repeat (u32) offset 36: duration (u32) - output, nanoseconds offset 40: ctx_size_in (u32) offset 44: ctx_size_out (u32) - input/output offset 48: ctx_in (u64 pointer) offset 56: ctx_out (u64 pointer) offset 64: flags (u32) offset 68: cpu (u32)

raw-syscall clj

(raw-syscall nr & args)

Make a raw syscall with variable arguments.

Parameters:

• nr: syscall number
• args: variable arguments (integers or MemorySegments)

Returns the syscall result (may be negative on error)

raw-tracepoint-attr->segment clj

(raw-tracepoint-attr->segment attr)

Convert RawTracepointAttr to MemorySegment for syscall. Must be called within a with-bpf-syscall block.

raw-tracepoint-open clj

(raw-tracepoint-open name prog-fd)

Open a raw tracepoint and attach BPF program

with-arena clj

(with-arena f)

Execute function with a confined arena for memory allocations

with-bpf-syscall clj macro

(with-bpf-syscall & body)

Execute body with a confined arena for safe memory allocation. All memory allocated within the body remains valid until the syscall completes and the arena is closed. This prevents GC from reclaiming memory prematurely.

CRITICAL: All BPF syscall functions must be wrapped with this macro to prevent memory corruption when loading multiple programs.