High-level uprobe definition macros for BPF programs.
Provides the defuprobe macro for defining uprobe handlers that trace userspace functions with automatic argument extraction.
Uprobes are like kprobes but for userspace applications. They allow tracing functions in user binaries, shared libraries, and interpreters.
Example: (defuprobe-instructions malloc-tracer {:binary "/lib/x86_64-linux-gnu/libc.so.6" :function "malloc" :args [:r6]} ; size argument (concat (helper-get-current-pid-tgid) [(mov-reg :r7 :r0)] [(exit-insn)]))
High-level uprobe definition macros for BPF programs.
Provides the defuprobe macro for defining uprobe handlers that trace
userspace functions with automatic argument extraction.
Uprobes are like kprobes but for userspace applications. They allow
tracing functions in user binaries, shared libraries, and interpreters.
Example:
(defuprobe-instructions malloc-tracer
{:binary "/lib/x86_64-linux-gnu/libc.so.6"
:function "malloc"
:args [:r6]} ; size argument
(concat
(helper-get-current-pid-tgid)
[(mov-reg :r7 :r0)]
[(exit-insn)]))(build-uprobe-program {:keys [args ctx-reg body return-value]
:or {args [] return-value 0}})Build a complete uprobe program with standard structure.
Combines prologue, body instructions, and epilogue.
Parameters:
Returns assembled program bytes.
Example: (build-uprobe-program {:args [:r6 :r7] :body [(mov :r0 42)] :return-value 0})
Build a complete uprobe program with standard structure.
Combines prologue, body instructions, and epilogue.
Parameters:
- opts: Map with:
:args - Vector of destination registers for function arguments
:ctx-reg - Register to save pt_regs pointer (optional)
:body - Vector of body instructions
:return-value - Value to return (default 0)
Returns assembled program bytes.
Example:
(build-uprobe-program
{:args [:r6 :r7]
:body [(mov :r0 42)]
:return-value 0})(build-uretprobe-program {:keys [ret-reg ctx-reg body return-value]
:or {return-value 0}})Build a complete uretprobe program with standard structure.
Similar to build-uprobe-program but for return probes.
Parameters:
Returns assembled program bytes.
Example: (build-uretprobe-program {:ret-reg :r6 :body [(jmp-imm :jeq :r6 0 skip) (mov :r0 0) (exit-insn)]})
Build a complete uretprobe program with standard structure.
Similar to build-uprobe-program but for return probes.
Parameters:
- opts: Map with:
:ret-reg - Register to store return value
:ctx-reg - Register to save pt_regs pointer (optional)
:body - Vector of body instructions
:return-value - Value to return (default 0)
Returns assembled program bytes.
Example:
(build-uretprobe-program
{:ret-reg :r6
:body [(jmp-imm :jeq :r6 0 skip)
(mov :r0 0)
(exit-insn)]})Common crypto library functions.
Common crypto library functions.
Common libc functions that are useful to trace.
Common libc functions that are useful to trace.
Common paths for system libraries.
Common paths for system libraries.
(defuprobe-instructions name options & body)Define a uprobe program as a function returning instructions.
This macro creates a function that returns a vector of BPF instructions for a uprobe handler. It sets up automatic argument loading.
Parameters:
Example: (defuprobe-instructions malloc-probe {:binary "/lib/x86_64-linux-gnu/libc.so.6" :function "malloc" :args [:r6]} ; r6 = size argument (concat (helper-get-current-pid-tgid) [(mov-reg :r7 :r0)] [(mov :r0 0) (exit-insn)]))
Define a uprobe program as a function returning instructions.
This macro creates a function that returns a vector of BPF instructions
for a uprobe handler. It sets up automatic argument loading.
Parameters:
- name: Name for the defined function
- options: Map with:
:binary - Path to the binary or library
:function - Function name to probe (or :offset for raw offset)
:offset - Raw offset if not using symbol name
:args - Vector of arg register bindings [:r6 :r7 ...]
:ctx-reg - Register to save context (optional)
- body: Body instructions (should return vector of instructions)
Example:
(defuprobe-instructions malloc-probe
{:binary "/lib/x86_64-linux-gnu/libc.so.6"
:function "malloc"
:args [:r6]} ; r6 = size argument
(concat
(helper-get-current-pid-tgid)
[(mov-reg :r7 :r0)]
[(mov :r0 0)
(exit-insn)]))(defuretprobe-instructions name options & body)Define a uretprobe program as a function returning instructions.
Similar to defuprobe-instructions but for return probes. Automatically loads the return value into the specified register.
Parameters:
Example: (defuretprobe-instructions malloc-ret-probe {:binary "/lib/x86_64-linux-gnu/libc.so.6" :function "malloc" :ret-reg :r6} ; r6 = returned pointer (concat [(jmp-imm :jeq :r6 0 skip)] ; Skip if NULL ;; ... handle success case [(mov :r0 0) (exit-insn)]))
Define a uretprobe program as a function returning instructions.
Similar to defuprobe-instructions but for return probes.
Automatically loads the return value into the specified register.
Parameters:
- name: Name for the defined function
- options: Map with:
:binary - Path to the binary
:function - Function name to probe
:ret-reg - Register for return value
:ctx-reg - Register to save context (optional)
- body: Body instructions
Example:
(defuretprobe-instructions malloc-ret-probe
{:binary "/lib/x86_64-linux-gnu/libc.so.6"
:function "malloc"
:ret-reg :r6} ; r6 = returned pointer
(concat
[(jmp-imm :jeq :r6 0 skip)] ; Skip if NULL
;; ... handle success case
[(mov :r0 0)
(exit-insn)]))(find-libc)Find the system's libc library.
Returns path to libc.so.6 or similar.
Find the system's libc library. Returns path to libc.so.6 or similar.
(find-library lib-name)Find a library by name in common system paths.
Parameters:
Returns full path or nil if not found.
Find a library by name in common system paths. Parameters: - lib-name: Library name (e.g., "libc.so.6" or just "libc") Returns full path or nil if not found.
(get-libc-function-offset function)Get the offset of a common libc function.
Parameters:
Returns offset or throws if libc or function not found.
Get the offset of a common libc function. Parameters: - function: Function name (e.g., "malloc") Returns offset or throws if libc or function not found.
(get-symbol-info binary-path symbol-name)Get detailed information about a symbol in a binary.
Parameters:
Returns map with :name, :offset, :size, :type, or nil if not found.
Get detailed information about a symbol in a binary. Parameters: - binary-path: Path to the ELF binary - symbol-name: Name of the symbol Returns map with :name, :offset, :size, :type, or nil if not found.
(list-symbols binary-path)(list-symbols binary-path filter-fn)List all function symbols in a binary.
Parameters:
Returns vector of symbol maps.
List all function symbols in a binary. Parameters: - binary-path: Path to the ELF binary - filter-fn: Optional predicate to filter symbols Returns vector of symbol maps.
(make-uprobe-program-info binary function offset program-name instructions)Create program metadata for a uprobe.
Parameters:
Returns map with program metadata for loading.
Create program metadata for a uprobe. Parameters: - binary: Path to the binary - function: Function name - offset: Symbol offset (optional, will be resolved if nil) - program-name: Name for the BPF program - instructions: Program instructions Returns map with program metadata for loading.
(make-uretprobe-program-info binary function offset program-name instructions)Create program metadata for a uretprobe.
Parameters:
Returns map with program metadata for loading.
Create program metadata for a uretprobe. Parameters: - binary: Path to the binary - function: Function name - offset: Symbol offset (optional) - program-name: Name for the BPF program - instructions: Program instructions Returns map with program metadata for loading.
(resolve-symbol-offset binary-path symbol-name)Resolve the offset of a symbol within a binary.
Uses ELF parsing to find the symbol's virtual address and converts it to an offset suitable for uprobe attachment.
Parameters:
Returns the symbol offset, or nil if not found.
Example: (resolve-symbol-offset "/lib/x86_64-linux-gnu/libc.so.6" "malloc") ;; => 0x9d850 (actual offset varies by libc version)
Resolve the offset of a symbol within a binary. Uses ELF parsing to find the symbol's virtual address and converts it to an offset suitable for uprobe attachment. Parameters: - binary-path: Path to the ELF binary or shared library - symbol-name: Name of the function/symbol to find Returns the symbol offset, or nil if not found. Example: (resolve-symbol-offset "/lib/x86_64-linux-gnu/libc.so.6" "malloc") ;; => 0x9d850 (actual offset varies by libc version)
(uprobe-attach-info binary target & {:keys [pid]})Build attachment information for a uprobe.
Parameters:
Returns map suitable for attachment functions.
Build attachment information for a uprobe. Parameters: - binary: Path to binary - target: Either a function name (string) or offset (number) - pid: Optional PID to filter (nil for all processes) Returns map suitable for attachment functions.
(uprobe-prologue arg-regs)(uprobe-prologue ctx-save-reg arg-regs)Generate standard uprobe prologue instructions.
Saves the pt_regs pointer and reads specified arguments. Uses the same mechanism as kprobe since both access pt_regs.
Parameters:
Returns vector of instructions.
Example: (uprobe-prologue :r9 [:r6 :r7]) ;; Generates: ;; mov r9, r1 ; Save pt_regs pointer ;; ldxdw r6, [r1 + offset] ; Load arg0 ;; ldxdw r7, [r1 + offset] ; Load arg1
Generate standard uprobe prologue instructions.
Saves the pt_regs pointer and reads specified arguments.
Uses the same mechanism as kprobe since both access pt_regs.
Parameters:
- ctx-save-reg: Register to save pt_regs pointer (optional)
- arg-regs: Vector of registers for arguments, e.g., [:r6 :r7 :r8]
Arg 0 goes to first register, arg 1 to second, etc.
Returns vector of instructions.
Example:
(uprobe-prologue :r9 [:r6 :r7])
;; Generates:
;; mov r9, r1 ; Save pt_regs pointer
;; ldxdw r6, [r1 + offset] ; Load arg0
;; ldxdw r7, [r1 + offset] ; Load arg1(uprobe-read-args ctx-reg arg-bindings)Generate instructions to read uprobe arguments into registers.
In uprobe handlers, r1 contains a pointer to pt_regs. This function generates instructions to load function arguments from pt_regs into the specified destination registers.
Note: Uses the same offsets as kprobe since both use pt_regs.
Parameters:
Returns vector of ldx instructions.
Example: (uprobe-read-args :r1 [[0 :r6] [1 :r7]]) ;; Generates instructions to load first two arguments
Generate instructions to read uprobe arguments into registers. In uprobe handlers, r1 contains a pointer to pt_regs. This function generates instructions to load function arguments from pt_regs into the specified destination registers. Note: Uses the same offsets as kprobe since both use pt_regs. Parameters: - ctx-reg: Register containing pt_regs pointer (typically :r1) - arg-bindings: Vector of [arg-index dest-reg] pairs Returns vector of ldx instructions. Example: (uprobe-read-args :r1 [[0 :r6] [1 :r7]]) ;; Generates instructions to load first two arguments
(uprobe-section-name binary function-or-offset)Generate ELF section name for a uprobe program.
Parameters:
Returns section name like "uprobe/libc.so.6:malloc"
Generate ELF section name for a uprobe program. Parameters: - binary: Path to the binary - function-or-offset: Function name or numeric offset Returns section name like "uprobe/libc.so.6:malloc"
(uretprobe-attach-info binary target & {:keys [pid]})Build attachment information for a uretprobe.
Parameters:
Returns map suitable for attachment functions.
Build attachment information for a uretprobe. Parameters: - binary: Path to binary - target: Either a function name (string) or offset (number) - pid: Optional PID to filter Returns map suitable for attachment functions.
(uretprobe-get-return-value ctx-reg dst-reg)Generate instruction to read the return value in uretprobe.
In uretprobe handlers, the function return value is accessed via the same mechanism as kretprobe (PT_REGS_RC).
Parameters:
Returns ldx instruction.
Example: (uretprobe-get-return-value :r1 :r6) ;; r6 = function return value
Generate instruction to read the return value in uretprobe. In uretprobe handlers, the function return value is accessed via the same mechanism as kretprobe (PT_REGS_RC). Parameters: - ctx-reg: Register containing pt_regs pointer - dst-reg: Destination register for return value Returns ldx instruction. Example: (uretprobe-get-return-value :r1 :r6) ;; r6 = function return value
(uretprobe-section-name binary function-or-offset)Generate ELF section name for a uretprobe program.
Parameters:
Returns section name like "uretprobe/libc.so.6:malloc"
Generate ELF section name for a uretprobe program. Parameters: - binary: Path to the binary - function-or-offset: Function name or numeric offset Returns section name like "uretprobe/libc.so.6:malloc"
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |