C API

Apr 22, 2026 00:00:00

Frida C API Reference

Overview

Frida exposes its core instrumentation capabilities through a C API via three separately-compiled devkit libraries. Use devkit downloads (from the releases page) as the primary build artifact — each devkit ships with a working example.

Libraries

Library	Purpose	GitHub
`frida-core`	Process injection, thread creation, JavaScript execution via QuickJS	frida/frida-core
`frida-gum`	Low-level: function interception, code tracing (Stalker), memory ops — all from C	frida/frida-gum
`frida-gumjs`	JavaScript bindings for Gum (QuickJS/V8 backend)	frida/frida-gum

Prerequisites: GLib 2.x (all types prefixed g/G are GLib types). GObject is the base type for all Frida objects — call g_object_unref() to release references unless documented otherwise.

frida-gum

Initialization (`gum.h`)

1#include <gum/gum.h>

Function	Description
`void gum_init(void)`	Initialize Gum (standalone use)
`void gum_shutdown(void)`	Begin teardown
`void gum_deinit(void)`	Finalize teardown
`void gum_init_embedded(void)`	Initialize when embedding in another process (no GLib mainloop)
`void gum_deinit_embedded(void)`	Deinitialize embedded mode
`void gum_prepare_to_fork(void)`	Call before `fork()`
`void gum_recover_from_fork_in_parent(void)`	Call in parent after `fork()`
`void gum_recover_from_fork_in_child(void)`	Call in child after `fork()`

Pattern: Use gum_init_embedded / gum_deinit_embedded when injecting into a running process. Use gum_init / gum_deinit in standalone tools.

Core Types (`gumdefs.h`)

GumAddress

1typedef guint64 GumAddress;
2#define GUM_ADDRESS(a) ((GumAddress)(guintptr)(a))

A 64-bit address type used throughout the API. Cast native pointers with GUM_ADDRESS(ptr).

GumCpuContext (platform-specific alias)

GumCpuContext is a typedef that resolves to the CPU-specific struct for the current build target:

Architecture	Struct	Key Fields
x86 (32-bit)	`GumIA32CpuContext`	`eip`, `eax`–`edi`, `esp`, `ebp`
x86-64	`GumX64CpuContext`	`rip`, `rax`–`rdi`, `r8`–`r15`, `rsp`, `rbp`
ARM 32-bit	`GumArmCpuContext`	`pc`, `sp`, `cpsr`, `r[0..7]`, `lr`, `v[16]` (VFP)
ARM64	`GumArm64CpuContext`	`pc`, `sp`, `nzcv`, `x[29]`, `fp`, `lr`, `v[32]`
MIPS	`GumMipsCpuContext`	`pc`, `gp`–`k1`, `a0`–`a3`, `t0`–`t9`, `s0`–`s7`

Portable access macros (x86/x86-64 only):

1GUM_CPU_CONTEXT_XAX(ctx)   // rax on 64-bit, eax on 32-bit
2GUM_CPU_CONTEXT_XIP(ctx)   // rip / eip
3GUM_CPU_CONTEXT_XSP(ctx)   // rsp / esp
4// etc. for XCX, XDX, XBX, XBP, XSI, XDI

GumError

 1typedef enum {
 2  GUM_ERROR_FAILED,
 3  GUM_ERROR_NOT_FOUND,
 4  GUM_ERROR_EXISTS,
 5  GUM_ERROR_PERMISSION_DENIED,
 6  GUM_ERROR_INVALID_ARGUMENT,
 7  GUM_ERROR_NOT_SUPPORTED,
 8  GUM_ERROR_INVALID_DATA,
 9} GumError;
10
11GQuark gum_error_quark(void);  // Use with GError domain: GUM_ERROR

GumPageProtection flags

1GUM_PAGE_NO_ACCESS = 0
2GUM_PAGE_READ      = (1 << 0)
3GUM_PAGE_WRITE     = (1 << 1)
4GUM_PAGE_EXECUTE   = (1 << 2)
5
6// Convenience composites:
7GUM_PAGE_RW   = GUM_PAGE_READ | GUM_PAGE_WRITE
8GUM_PAGE_RX   = GUM_PAGE_READ | GUM_PAGE_EXECUTE
9GUM_PAGE_RWX  = GUM_PAGE_READ | GUM_PAGE_WRITE | GUM_PAGE_EXECUTE

GumInterceptor (`guminterceptor.h`)

Intercept (attach listener) or replace functions at arbitrary addresses. Thread-safe; uses transactions to batch changes.

Attach / Detach

 1GumInterceptor *gum_interceptor_obtain(void);
 2// Returns singleton; call g_object_unref() when done.
 3
 4GumAttachReturn gum_interceptor_attach(
 5    GumInterceptor *self,
 6    gpointer        function_address,
 7    GumInvocationListener *listener,
 8    gpointer        listener_function_data,
 9    GumAttachFlags  flags);
10
11void gum_interceptor_detach(
12    GumInterceptor *self,
13    GumInvocationListener *listener);

GumAttachReturn values:

Value	Meaning
`GUM_ATTACH_OK` (0)	Success
`GUM_ATTACH_WRONG_SIGNATURE` (-1)	Couldn’t instrument target
`GUM_ATTACH_ALREADY_ATTACHED` (-2)	Same listener already attached
`GUM_ATTACH_POLICY_VIOLATION` (-3)	Code-signing policy blocked it
`GUM_ATTACH_WRONG_TYPE` (-4)	Target is not a function

GumAttachFlags:

1GUM_ATTACH_FLAGS_NONE        = 0
2GUM_ATTACH_FLAGS_UNIGNORABLE = (1 << 0)  // Cannot be suppressed by ignore_current_thread
3GUM_ATTACH_FLAGS_FORCE       = (1 << 1)  // Force even on already-instrumented code

Replace / Revert

 1GumReplaceReturn gum_interceptor_replace(
 2    GumInterceptor *self,
 3    gpointer        function_address,
 4    gpointer        replacement_function,
 5    gpointer        replacement_data,
 6    gpointer       *original_function);   // [out] pointer to trampoline for calling original
 7
 8void gum_interceptor_revert(
 9    GumInterceptor *self,
10    gpointer        function_address);

GumReplaceReturn mirrors GumAttachReturn: GUM_REPLACE_OK, GUM_REPLACE_WRONG_SIGNATURE, GUM_REPLACE_ALREADY_REPLACED, GUM_REPLACE_POLICY_VIOLATION, GUM_REPLACE_WRONG_TYPE.

Transactions

Batch multiple attach/replace operations atomically to minimize performance impact:

1void gum_interceptor_begin_transaction(GumInterceptor *self);
2void gum_interceptor_end_transaction(GumInterceptor *self);
3gboolean gum_interceptor_flush(GumInterceptor *self);

Thread Ignoring

Prevent the interceptor from firing for the current thread (useful inside listeners to avoid recursion):

1void gum_interceptor_ignore_current_thread(GumInterceptor *self);
2void gum_interceptor_unignore_current_thread(GumInterceptor *self);
3gboolean gum_interceptor_maybe_unignore_current_thread(GumInterceptor *self);
4// Returns TRUE if unignored (was ignored); use to guard against double-unignore
5
6void gum_interceptor_ignore_other_threads(GumInterceptor *self);
7void gum_interceptor_unignore_other_threads(GumInterceptor *self);

Current Invocation

1GumInvocationContext *gum_interceptor_get_current_invocation(void);
2GumInvocationContext *gum_interceptor_get_live_replacement_invocation(
3    gpointer replacement_function);
4GumInvocationStack *gum_interceptor_get_current_stack(void);
5
6gpointer gum_invocation_stack_translate(
7    GumInvocationStack *self,
8    gpointer            return_address);

State Save/Restore

1typedef guint GumInvocationState;
2void gum_interceptor_save(GumInvocationState *state);
3void gum_interceptor_restore(GumInvocationState *state);

GumInvocationListener (`guminvocationlistener.h`)

Interface called on function enter/leave. Either implement the interface or use the convenience constructors.

Convenience constructors

 1typedef void (*GumInvocationCallback)(GumInvocationContext *context,
 2                                      gpointer user_data);
 3
 4GumInvocationListener *gum_make_call_listener(
 5    GumInvocationCallback on_enter,     // called on function entry (NULL to skip)
 6    GumInvocationCallback on_leave,     // called on function return (NULL to skip)
 7    gpointer              data,
 8    GDestroyNotify        data_destroy);
 9
10GumInvocationListener *gum_make_probe_listener(
11    GumInvocationCallback on_hit,       // called on entry only
12    gpointer              data,
13    GDestroyNotify        data_destroy);

Interface (custom subclass)

1struct _GumInvocationListenerInterface {
2  GTypeInterface parent;
3  void (*on_enter)(GumInvocationListener *self, GumInvocationContext *context);
4  void (*on_leave)(GumInvocationListener *self, GumInvocationContext *context);
5};

GumInvocationContext (`guminvocationcontext.h`)

Passed to every listener callback. Provides access to arguments, return value, CPU state, and per-thread/per-invocation data.

Struct layout

1struct _GumInvocationContext {
2  gpointer       function;       // address of intercepted function
3  GumCpuContext *cpu_context;    // live CPU register state
4  gint           system_error;   // errno / GetLastError() at time of call
5  // private backend field
6};

Access helpers

 1GumPointCut gum_invocation_context_get_point_cut(GumInvocationContext *ctx);
 2// Returns GUM_POINT_ENTER or GUM_POINT_LEAVE
 3
 4gpointer gum_invocation_context_get_nth_argument(GumInvocationContext *ctx, guint n);
 5void     gum_invocation_context_replace_nth_argument(GumInvocationContext *ctx, guint n, gpointer value);
 6
 7gpointer gum_invocation_context_get_return_value(GumInvocationContext *ctx);
 8void     gum_invocation_context_replace_return_value(GumInvocationContext *ctx, gpointer value);
 9
10gpointer gum_invocation_context_get_return_address(GumInvocationContext *ctx);
11
12guint gum_invocation_context_get_thread_id(GumInvocationContext *ctx);
13guint gum_invocation_context_get_depth(GumInvocationContext *ctx);

Per-listener storage (allocated lazily, zero-initialized)

 1// Thread-local storage (shared across all invocations of this listener on this thread):
 2gpointer gum_invocation_context_get_listener_thread_data(GumInvocationContext *ctx, gsize required_size);
 3
 4// Per-function-address data (set via listener_function_data in gum_interceptor_attach):
 5gpointer gum_invocation_context_get_listener_function_data(GumInvocationContext *ctx);
 6
 7// Per-invocation data (unique to each call instance, available on_enter AND on_leave):
 8gpointer gum_invocation_context_get_listener_invocation_data(GumInvocationContext *ctx, gsize required_size);
 9
10// Replacement function data (set via replacement_data in gum_interceptor_replace):
11gpointer gum_invocation_context_get_replacement_data(GumInvocationContext *ctx);

Convenience macros:

1// Cast pointer to a typed struct pointer:
2GUM_IC_GET_THREAD_DATA(ctx, MyThreadState)       // → MyThreadState *
3GUM_IC_GET_FUNC_DATA(ctx, MyFuncDataType)        // → MyFuncDataType (cast only)
4GUM_IC_GET_INVOCATION_DATA(ctx, MyCallState)     // → MyCallState *
5GUM_IC_GET_REPLACEMENT_DATA(ctx, MyReplData)     // → MyReplData (cast only)

GumStalker (`gumstalker.h`)

Code tracing engine that follows execution and rewrites code blocks for observation and transformation. Works at basic-block granularity.

Supported platforms: x86, x86-64, ARM32, ARM64, MIPS. Check at runtime with gum_stalker_is_supported().

Lifecycle

1gboolean     gum_stalker_is_supported(void);
2GumStalker  *gum_stalker_new(void);         // Returns GObject; unref to destroy
3void         gum_stalker_flush(GumStalker *self);
4void         gum_stalker_stop(GumStalker *self);
5gboolean     gum_stalker_garbage_collect(GumStalker *self);
6// Call garbage_collect periodically (e.g., on every n-th event) to reclaim memory

Following Threads

1void gum_stalker_follow_me(GumStalker *self,
2    GumStalkerTransformer *transformer,   // NULL for default (pass-through)
3    GumEventSink          *sink);         // NULL to suppress events
4void gum_stalker_unfollow_me(GumStalker *self);
5gboolean gum_stalker_is_following_me(GumStalker *self);
6
7void gum_stalker_follow(GumStalker *self, GumThreadId thread_id,
8    GumStalkerTransformer *transformer, GumEventSink *sink);
9void gum_stalker_unfollow(GumStalker *self, GumThreadId thread_id);

Activation / Deactivation (lazy following)

1void gum_stalker_activate(GumStalker *self, gconstpointer target);
2// Begin following when execution reaches `target` address
3void gum_stalker_deactivate(GumStalker *self);

Configuration

1void gum_stalker_exclude(GumStalker *self, const GumMemoryRange *range);
2// Exclude a memory range from instrumentation
3
4gint gum_stalker_get_trust_threshold(GumStalker *self);
5void gum_stalker_set_trust_threshold(GumStalker *self, gint trust_threshold);
6// -1 = always recompile; 0 = compile once; n = reuse after n executions

Code Cache Management

 1void     gum_stalker_invalidate(GumStalker *self, gconstpointer address);
 2void     gum_stalker_invalidate_for_thread(GumStalker *self,
 3             GumThreadId thread_id, gconstpointer address);
 4void     gum_stalker_prefetch(GumStalker *self, gconstpointer address,
 5             gint recycle_count);
 6void     gum_stalker_prefetch_backpatch(GumStalker *self,
 7             const GumBackpatch *notification);
 8void     gum_stalker_recompile(GumStalker *self, gconstpointer address);
 9
10gpointer gum_stalker_backpatch_get_from(const GumBackpatch *backpatch);
11gpointer gum_stalker_backpatch_get_to(const GumBackpatch *backpatch);

Call Probes

 1typedef void (*GumCallProbeCallback)(GumCallDetails *details, gpointer user_data);
 2
 3struct _GumCallDetails {
 4  gpointer       target_address;
 5  gpointer       return_address;
 6  gpointer       stack_data;
 7  GumCpuContext *cpu_context;
 8};
 9
10GumProbeId gum_stalker_add_call_probe(GumStalker *self,
11    gpointer            target_address,
12    GumCallProbeCallback callback,
13    gpointer            data,
14    GDestroyNotify      notify);
15void       gum_stalker_remove_call_probe(GumStalker *self, GumProbeId id);

Run on Thread

1typedef void (*GumStalkerRunOnThreadFunc)(const GumCpuContext *cpu_context,
2                                          gpointer user_data);
3
4gboolean gum_stalker_run_on_thread(GumStalker *self, GumThreadId thread_id,
5    GumStalkerRunOnThreadFunc func, gpointer data, GDestroyNotify data_destroy);
6gboolean gum_stalker_run_on_thread_sync(GumStalker *self, GumThreadId thread_id,
7    GumStalkerRunOnThreadFunc func, gpointer data);

GumStalkerTransformer

Plug-in that rewrites each basic block as Stalker recompiles it.

 1typedef void (*GumStalkerTransformerCallback)(
 2    GumStalkerIterator *iterator,
 3    GumStalkerOutput   *output,
 4    gpointer            user_data);
 5
 6GumStalkerTransformer *gum_stalker_transformer_make_default(void);
 7GumStalkerTransformer *gum_stalker_transformer_make_from_callback(
 8    GumStalkerTransformerCallback callback,
 9    gpointer                      data,
10    GDestroyNotify                data_destroy);

GumStalkerIterator

Used inside a transformer callback to iterate instructions in a block:

 1gboolean gum_stalker_iterator_next(GumStalkerIterator *self,
 2    const cs_insn **insn);   // Capstone instruction struct
 3void     gum_stalker_iterator_keep(GumStalkerIterator *self);
 4// Must call keep() or the instruction is dropped
 5
 6GumMemoryAccess gum_stalker_iterator_get_memory_access(GumStalkerIterator *self);
 7
 8void gum_stalker_iterator_put_callout(GumStalkerIterator *self,
 9    GumStalkerCallout callout, gpointer data, GDestroyNotify data_destroy);
10void gum_stalker_iterator_put_chaining_return(GumStalkerIterator *self);
11csh  gum_stalker_iterator_get_capstone(GumStalkerIterator *self);

Callout callback:

1typedef void (*GumStalkerCallout)(GumCpuContext *cpu_context, gpointer user_data);

GumStalkerOutput

 1union _GumStalkerWriter {
 2  gpointer       instance;
 3  GumX86Writer  *x86;
 4  GumArmWriter  *arm;
 5  GumThumbWriter *thumb;
 6  GumArm64Writer *arm64;
 7  GumMipsWriter  *mips;
 8};
 9
10struct _GumStalkerOutput {
11  GumStalkerWriter    writer;
12  GumInstructionEncoding encoding;  // GUM_INSTRUCTION_DEFAULT or GUM_INSTRUCTION_SPECIAL
13};

Memory API (`gummemory.h`)

Memory Ranges

 1struct _GumMemoryRange {
 2  GumAddress base_address;
 3  gsize      size;
 4};
 5
 6struct _GumFileMapping {
 7  const gchar *path;
 8  guint64      offset;
 9  gsize        size;
10};
11
12struct _GumRangeDetails {
13  const GumMemoryRange *range;
14  GumPageProtection     protection;
15  const GumFileMapping *file;   // NULL if not file-backed
16};
17
18GumMemoryRange *gum_memory_range_copy(const GumMemoryRange *range);
19void            gum_memory_range_free(GumMemoryRange *range);
20
21#define GUM_MEMORY_RANGE_INCLUDES(r, a) \
22    ((a) >= (r)->base_address && (a) < ((r)->base_address + (r)->size))

Read / Write / Patch

 1gboolean gum_memory_is_readable(gconstpointer address, gsize len);
 2gboolean gum_memory_query_protection(gconstpointer address, GumPageProtection *prot);
 3
 4guint8  *gum_memory_read(gconstpointer address, gsize len, gsize *n_bytes_read);
 5// Caller must g_free() the returned buffer.
 6
 7gboolean gum_memory_write(gpointer address, const guint8 *bytes, gsize len);
 8
 9typedef void (*GumMemoryPatchApplyFunc)(gpointer mem, gpointer user_data);
10gboolean gum_memory_patch_code(gpointer address, gsize size,
11    GumMemoryPatchApplyFunc apply, gpointer apply_data);
12// Temporarily makes `size` bytes writable, calls apply(), then restores protection
13// and flushes i-cache. Preferred over manual mprotect for code patching.
14
15gboolean gum_memory_mark_code(gpointer address, gsize size);

Scanning

 1typedef gboolean (*GumMemoryScanMatchFunc)(GumAddress address, gsize size,
 2                                           gpointer user_data);
 3
 4void gum_memory_scan(const GumMemoryRange *range,
 5    const GumMatchPattern *pattern, GumMemoryScanMatchFunc func,
 6    gpointer user_data);
 7
 8GumMatchPattern *gum_match_pattern_new_from_string(const gchar *pattern_str);
 9// Pattern format: hex bytes with optional "??" wildcards, e.g. "48 8b ?? ?? 90"
10GumMatchPattern *gum_match_pattern_ref(GumMatchPattern *pattern);
11void             gum_match_pattern_unref(GumMatchPattern *pattern);
12guint            gum_match_pattern_get_size(const GumMatchPattern *pattern);
13GPtrArray       *gum_match_pattern_get_tokens(const GumMatchPattern *pattern);

Page Protection

1void     gum_mprotect(gpointer address, gsize size, GumPageProtection prot);
2gboolean gum_try_mprotect(gpointer address, gsize size, GumPageProtection prot);
3void     gum_clear_cache(gpointer address, gsize size);   // flush i-cache
4void     gum_ensure_code_readable(gconstpointer address, gsize size);

Memory Allocation

 1// Page-granularity:
 2gpointer gum_alloc_n_pages(guint n_pages, GumPageProtection prot);
 3gpointer gum_try_alloc_n_pages(guint n_pages, GumPageProtection prot);
 4gpointer gum_alloc_n_pages_near(guint n_pages, GumPageProtection prot,
 5             const GumAddressSpec *spec);
 6gpointer gum_try_alloc_n_pages_near(guint n_pages, GumPageProtection prot,
 7             const GumAddressSpec *spec);
 8void     gum_free_pages(gpointer mem);
 9
10struct _GumAddressSpec {
11  gpointer near_address;
12  gsize    max_distance;
13};
14
15// Low-level virtual memory:
16gpointer gum_memory_allocate(gpointer address, gsize size,
17             gsize alignment, GumPageProtection prot);
18gpointer gum_memory_allocate_near(const GumAddressSpec *spec,
19             gsize size, gsize alignment, GumPageProtection prot);
20gboolean gum_memory_free(gpointer address, gsize size);
21gboolean gum_memory_release(gpointer address, gsize size);
22gboolean gum_memory_recommit(gpointer address, gsize size, GumPageProtection prot);
23gboolean gum_memory_discard(gpointer address, gsize size);
24gboolean gum_memory_decommit(gpointer address, gsize size);
25
26// Heap (Gum internal allocator):
27gpointer gum_malloc(gsize size);
28gpointer gum_malloc0(gsize size);
29gpointer gum_calloc(gsize count, gsize size);
30gpointer gum_realloc(gpointer mem, gsize size);
31gpointer gum_memalign(gsize alignment, gsize size);
32gpointer gum_memdup(gconstpointer mem, gsize byte_size);
33void     gum_free(gpointer mem);
34gsize    gum_malloc_usable_size(gconstpointer mem);
35
36// Convenience macros:
37gum_new(struct_type, n)    // typed gum_malloc
38gum_new0(struct_type, n)   // typed gum_malloc0 (zero-initialized)

Pointer Authentication (Apple Silicon)

1gpointer       gum_sign_code_pointer(gpointer value);
2gpointer       gum_strip_code_pointer(gpointer value);
3GumAddress     gum_sign_code_address(GumAddress value);
4GumAddress     gum_strip_code_address(GumAddress value);
5GumPtrauthSupport gum_query_ptrauth_support(void);
6// GUM_PTRAUTH_INVALID, GUM_PTRAUTH_UNSUPPORTED, GUM_PTRAUTH_SUPPORTED

Queries

1guint    gum_query_page_size(void);
2gboolean gum_query_is_rwx_supported(void);
3GumRwxSupport gum_query_rwx_support(void);
4// GUM_RWX_NONE, GUM_RWX_ALLOCATIONS_ONLY, GUM_RWX_FULL
5GumCpuFeatures gum_query_cpu_features(void);

Process API (`gumprocess.h`)

Process Info

1GumOS                gum_process_get_native_os(void);
2GumTeardownRequirement gum_process_get_teardown_requirement(void);
3void                 gum_process_set_teardown_requirement(GumTeardownRequirement r);
4GumCodeSigningPolicy gum_process_get_code_signing_policy(void);
5void                 gum_process_set_code_signing_policy(GumCodeSigningPolicy p);
6gboolean             gum_process_is_debugger_attached(void);
7GumProcessId         gum_process_get_id(void);
8GumThreadId          gum_process_get_current_thread_id(void);
9gboolean             gum_process_has_thread(GumThreadId thread_id);

Thread Enumeration and Manipulation

 1typedef enum {
 2  GUM_THREAD_RUNNING = 1,
 3  GUM_THREAD_STOPPED,
 4  GUM_THREAD_WAITING,
 5  GUM_THREAD_UNINTERRUPTIBLE,
 6  GUM_THREAD_HALTED
 7} GumThreadState;
 8
 9typedef enum {
10  GUM_THREAD_FLAGS_NAME                 = (1 << 0),
11  GUM_THREAD_FLAGS_STATE                = (1 << 1),
12  GUM_THREAD_FLAGS_CPU_CONTEXT          = (1 << 2),
13  GUM_THREAD_FLAGS_ENTRYPOINT_ROUTINE   = (1 << 3),
14  GUM_THREAD_FLAGS_ENTRYPOINT_PARAMETER = (1 << 4),
15  GUM_THREAD_FLAGS_ALL  = /* all above combined */,
16  GUM_THREAD_FLAGS_NONE = 0,
17} GumThreadFlags;
18
19struct _GumThreadDetails {
20  GumThreadFlags    flags;
21  GumThreadId       id;
22  const gchar      *name;
23  GumThreadState    state;
24  GumCpuContext     cpu_context;
25  GumThreadEntrypoint entrypoint;  // {routine: GumAddress, parameter: GumAddress}
26};
27
28typedef gboolean (*GumFoundThreadFunc)(const GumThreadDetails *details,
29                                       gpointer user_data);
30// Return FALSE from callback to stop enumeration
31
32void     gum_process_enumerate_threads(GumFoundThreadFunc func,
33             gpointer user_data, GumThreadFlags flags);
34
35typedef void (*GumModifyThreadFunc)(GumThreadId thread_id,
36                                    GumCpuContext *cpu_context,
37                                    gpointer user_data);
38
39gboolean gum_process_modify_thread(GumThreadId thread_id,
40    GumModifyThreadFunc func, gpointer user_data, GumModifyThreadFlags flags);
41// GUM_MODIFY_THREAD_FLAGS_NONE or GUM_MODIFY_THREAD_FLAGS_ABORT_SAFELY
42
43gboolean gum_thread_suspend(GumThreadId thread_id, GError **error);
44gboolean gum_thread_resume(GumThreadId thread_id, GError **error);
45gint     gum_thread_get_system_error(void);
46void     gum_thread_set_system_error(gint value);
47guint    gum_thread_try_get_ranges(GumMemoryRange *ranges, guint max_length);

Hardware Breakpoints / Watchpoints

 1gboolean gum_thread_set_hardware_breakpoint(GumThreadId thread_id,
 2    guint breakpoint_id, GumAddress address, GError **error);
 3gboolean gum_thread_unset_hardware_breakpoint(GumThreadId thread_id,
 4    guint breakpoint_id, GError **error);
 5
 6typedef enum {
 7  GUM_WATCH_READ  = (1 << 0),
 8  GUM_WATCH_WRITE = (1 << 1),
 9} GumWatchConditions;
10
11gboolean gum_thread_set_hardware_watchpoint(GumThreadId thread_id,
12    guint watchpoint_id, GumAddress address, gsize size,
13    GumWatchConditions wc, GError **error);
14gboolean gum_thread_unset_hardware_watchpoint(GumThreadId thread_id,
15    guint watchpoint_id, GError **error);

Module Enumeration

1typedef gboolean (*GumFoundModuleFunc)(GumModule *module, gpointer user_data);
2
3GumModule *gum_process_get_main_module(void);
4GumModule *gum_process_get_libc_module(void);
5GumModule *gum_process_find_module_by_name(const gchar *name);
6GumModule *gum_process_find_module_by_address(GumAddress address);
7void       gum_process_enumerate_modules(GumFoundModuleFunc func,
8               gpointer user_data);

Memory Range Enumeration

1typedef gboolean (*GumFoundRangeFunc)(const GumRangeDetails *details,
2                                      gpointer user_data);
3typedef gboolean (*GumFoundMallocRangeFunc)(const GumMallocRangeDetails *details,
4                                             gpointer user_data);
5
6void gum_process_enumerate_ranges(GumPageProtection prot,
7         GumFoundRangeFunc func, gpointer user_data);
8void gum_process_enumerate_malloc_ranges(GumFoundMallocRangeFunc func,
9         gpointer user_data);

Module API (`gummodule.h`)

GumModule is a GObject interface. Retrieve instances via gum_process_* or gum_module_load().

Loading

1GumModule *gum_module_load(const gchar *module_name, GError **error);

Properties

1const gchar        *gum_module_get_name(GumModule *self);
2const gchar        *gum_module_get_version(GumModule *self);
3const gchar        *gum_module_get_path(GumModule *self);
4const GumMemoryRange *gum_module_get_range(GumModule *self);
5void                gum_module_ensure_initialized(GumModule *self);

Symbol Resolution

1GumAddress gum_module_find_export_by_name(GumModule *self,
2               const gchar *symbol_name);
3GumAddress gum_module_find_global_export_by_name(const gchar *symbol_name);
4// Searches all loaded modules
5GumAddress gum_module_find_symbol_by_name(GumModule *self,
6               const gchar *symbol_name);

Enumeration

 1typedef gboolean (*GumFoundImportFunc)(const GumImportDetails *details,
 2                                       gpointer user_data);
 3typedef gboolean (*GumFoundExportFunc)(const GumExportDetails *details,
 4                                       gpointer user_data);
 5typedef gboolean (*GumFoundSymbolFunc)(const GumSymbolDetails *details,
 6                                       gpointer user_data);
 7typedef gboolean (*GumFoundSectionFunc)(const GumSectionDetails *details,
 8                                        gpointer user_data);
 9typedef gboolean (*GumFoundDependencyFunc)(const GumDependencyDetails *details,
10                                           gpointer user_data);
11
12void gum_module_enumerate_imports(GumModule *self,
13         GumFoundImportFunc func, gpointer user_data);
14void gum_module_enumerate_exports(GumModule *self,
15         GumFoundExportFunc func, gpointer user_data);
16void gum_module_enumerate_symbols(GumModule *self,
17         GumFoundSymbolFunc func, gpointer user_data);
18void gum_module_enumerate_ranges(GumModule *self, GumPageProtection prot,
19         GumFoundRangeFunc func, gpointer user_data);
20void gum_module_enumerate_sections(GumModule *self,
21         GumFoundSectionFunc func, gpointer user_data);
22void gum_module_enumerate_dependencies(GumModule *self,
23         GumFoundDependencyFunc func, gpointer user_data);

Detail Structs

 1struct _GumImportDetails {
 2  GumImportType  type;    // GUM_IMPORT_UNKNOWN, GUM_IMPORT_FUNCTION, GUM_IMPORT_VARIABLE
 3  const gchar   *name;
 4  const gchar   *module;  // source module (may be NULL)
 5  GumAddress     address;
 6  GumAddress     slot;    // GOT/IAT slot address
 7};
 8
 9struct _GumExportDetails {
10  GumExportType  type;    // GUM_EXPORT_FUNCTION, GUM_EXPORT_VARIABLE
11  const gchar   *name;
12  GumAddress     address;
13};
14
15struct _GumSymbolDetails {
16  gboolean         is_global;
17  GumSymbolType    type;
18  const GumSymbolSection *section; // may be NULL
19  const gchar     *name;
20  GumAddress       address;
21  gssize           size;  // -1 if unknown
22};
23
24struct _GumSectionDetails {
25  const gchar *id;
26  const gchar *name;
27  GumAddress   address;
28  gsize        size;
29};
30
31struct _GumDependencyDetails {
32  const gchar       *name;
33  GumDependencyType  type;
34  // GUM_DEPENDENCY_REGULAR, GUM_DEPENDENCY_WEAK,
35  // GUM_DEPENDENCY_REEXPORT, GUM_DEPENDENCY_UPWARD
36};

API Resolver (`gumapiresolver.h`)

Enumerate exports/imports across loaded modules using query strings.

 1GumApiResolver *gum_api_resolver_make(const gchar *type);
 2// type: "module" (cross-platform) or "objc" (Apple only) or "swift" (Apple only)
 3
 4void gum_api_resolver_enumerate_matches(GumApiResolver *self,
 5    const gchar *query, GumFoundApiFunc func, gpointer user_data,
 6    GError **error);
 7
 8typedef gboolean (*GumFoundApiFunc)(const GumApiDetails *details,
 9                                    gpointer user_data);
10
11struct _GumApiDetails {
12  const gchar *name;
13  GumAddress   address;
14  gssize       size;     // GUM_API_SIZE_NONE (-1) if unavailable
15};

Query syntax for “module” resolver: exports:*!open* (glob pattern: module!symbol)

Exception Handling (`gumexceptor.h`)

Catch hardware exceptions (access violations, illegal instructions, etc.) within a guarded scope.

 1GumExceptor *gum_exceptor_obtain(void);   // singleton; unref when done
 2void         gum_exceptor_disable(void);
 3void         gum_exceptor_reset(GumExceptor *self);
 4
 5typedef gboolean (*GumExceptionHandler)(GumExceptionDetails *details,
 6                                         gpointer user_data);
 7
 8void gum_exceptor_add(GumExceptor *self, GumExceptionHandler func,
 9         gpointer user_data);
10void gum_exceptor_remove(GumExceptor *self, GumExceptionHandler func,
11         gpointer user_data);

Exception Types

1GUM_EXCEPTION_ABORT
2GUM_EXCEPTION_ACCESS_VIOLATION
3GUM_EXCEPTION_GUARD_PAGE
4GUM_EXCEPTION_ILLEGAL_INSTRUCTION
5GUM_EXCEPTION_STACK_OVERFLOW
6GUM_EXCEPTION_ARITHMETIC
7GUM_EXCEPTION_BREAKPOINT
8GUM_EXCEPTION_SINGLE_STEP
9GUM_EXCEPTION_SYSTEM

Exception Details

 1struct _GumExceptionDetails {
 2  GumThreadId               thread_id;
 3  GumExceptionType          type;
 4  gpointer                  address;    // instruction that caused the exception
 5  GumExceptionMemoryDetails memory;     // {operation, address} — valid for ACCESS_VIOLATION
 6  GumCpuContext             context;
 7  gpointer                  native_context;  // CONTEXT* on Windows, ucontext_t* elsewhere
 8};
 9
10gchar *gum_exception_details_to_string(const GumExceptionDetails *details);
11// Caller must g_free() the returned string.

Try/Catch Scope

 1// Pattern:
 2GumExceptorScope scope;
 3if (gum_exceptor_try(exceptor, &scope)) {
 4    // code that might throw
 5} else if (gum_exceptor_catch(exceptor, &scope)) {
 6    // scope.exception contains details
 7}
 8
 9gboolean gum_exceptor_catch(GumExceptor *self, GumExceptorScope *scope);
10gboolean gum_exceptor_has_scope(GumExceptor *self, GumThreadId thread_id);

frida-core

frida-core is a higher-level library for injecting into processes and managing Frida sessions (script loading, message passing). It exposes a Vala/C API generated from GIR definitions.

Note: The frida-core C API is primarily generated from Vala source. Use the devkit headers and included example (typically frida-core-example.c) as the canonical reference.

Key concepts:

FridaDeviceManager — enumerate and connect to local/remote/USB devices
FridaDevice — represents a target device
FridaSession — attached to a process on a device
FridaScript — JavaScript code loaded into a session
Messages between scripts and the host use frida_script_post() / on_message signal

frida-gadget

A shared library variant of the Frida agent that can be injected without a host process. Modes:

Mode	Mechanism
`DYLD_INSERT_LIBRARIES` / `LD_PRELOAD`	Environment variable injection
Bundled	Linked directly into the app or loaded by a loader shim
Remote	Exposes a Frida server socket; connects like `frida-server`

Configuration via a sidecar JSON file (same base name as the gadget, .config extension).

Build Notes

Download devkits from: https://github.com/frida/frida/releases
Devkit filenames: frida-gum-devkit-<version>-<os>-<arch>.tar.xz
Each devkit contains: one amalgamated .h header, one .a/.lib static library, and a frida-gum-example.c
Link order: -lfrida-gum -lresolv (Linux) or link the .a and add required system frameworks (macOS/iOS)
Requires GLib; devkit may bundle it statically