Function hook_function 

pub unsafe fn hook_function<T>(
    symbol: *mut T,
    replace: *mut T,
) -> Result<*mut T>

Type-safe Rust wrapper for hooking functions.

This is a generic wrapper around the C API that provides type safety and Result-based error handling. It’s the recommended way to use the hooking functionality from Rust code.

Type Parameters

• T - The function type to hook (typically a function pointer)

Arguments

• symbol - Pointer to the function to hook
• replace - Pointer to your replacement function

Returns

Ok(*mut T) containing the trampoline pointer to call the original function. Err(SubstrateError) if the hook installation fails.

Safety

This function is unsafe because it modifies executable code at runtime. Both pointers must be valid function pointers of the correct type.

Examples

use substrate::hook_function;

extern "C" fn original_func(x: i32) -> i32 { x }
extern "C" fn hooked_func(x: i32) -> i32 { x + 1 }

unsafe {
    let trampoline = hook_function(
        original_func as *mut _,
        hooked_func as *mut _
    ).expect("Hook failed");
}

Examples found in repository

examples/basic_hook.rs (line 38)

fn main() {
    println!("=== Basic Function Hook Example ===\n");

    unsafe {
        let target = original_add as *mut u8;
        let hook = hooked_add as *mut u8;

        println!("Target function: {:p}", target);
        println!("Hook function: {:p}", hook);

        let result = original_add(5, 3);
        println!("Before hook: 5 + 3 = {}", result);

        match hook_function(target, hook) {
            Ok(original) => {
                ORIGINAL_ADD = original;
                println!("\n✓ Hook installed successfully!");
                println!("Trampoline (original): {:p}\n", original);

                let result = original_add(5, 3);
                println!("After hook: 5 + 3 = {}", result);

                let calls = CALL_COUNT.load(Ordering::Relaxed);
                println!("\nTotal hooked calls: {}", calls);
            }
            Err(e) => {
                eprintln!("✗ Hook failed: {}", e);
            }
        }
    }
}

examples/error_handling.rs (line 9)

fn demonstrate_error_handling() {
    println!("=== Error Handling Example ===\n");

    unsafe {
        println!("1. Testing null pointer hook:");
        match hook_function(std::ptr::null_mut::<u8>(), std::ptr::null_mut()) {
            Ok(_) => println!("  Unexpected success"),
            Err(SubstrateError::NullPointer) => println!("  ✓ Correctly caught null pointer"),
            Err(e) => println!("  Different error: {}", e),
        }

        println!("\n2. Testing library not found:");
        match utils::find_library("nonexistent.so") {
            Ok(_) => println!("  Unexpected success"),
            Err(SubstrateError::LibraryNotFound(name)) => {
                println!("  ✓ Correctly caught missing library: {}", name)
            }
            Err(e) => println!("  Different error: {}", e),
        }

        println!("\n3. Testing invalid offset string:");
        match utils::string_to_offset("not_a_hex") {
            Ok(_) => println!("  Unexpected success"),
            Err(SubstrateError::ParseError(msg)) => {
                println!("  ✓ Correctly caught parse error: {}", msg)
            }
            Err(e) => println!("  Different error: {}", e),
        }

        println!("\n4. Testing valid hex parsing:");
        match utils::string_to_offset("0x123ABC") {
            Ok(offset) => println!("  ✓ Successfully parsed: 0x{:X}", offset),
            Err(e) => println!("  ✗ Unexpected error: {}", e),
        }
    }

    println!("\n=== All Error Cases Handled ===");
}