Sighook

https://docs.rs/sighook/0.10.0/sighook/
Admin
Sighook is a Rust runtime patching crate for instruction-level instrumentation and function-entry...
Tokens:22,727
Snippets:239
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic usage of instrument

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html

Demonstrates the basic setup for installing a hook at a specific memory address.

```rust
use sighook::{instrument, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let target = 0x1000_0000u64;
let original = instrument(target, on_hit)?;
let _ = original;
```

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

### instrument

Source: https://docs.rs/sighook/0.10.0/sighook/index.html?search=std%3A%3Avec

Installs an instruction-level hook and executes the original instruction afterward.

```APIDOC
## instrument

### Description
Installs an instruction-level hook and executes the original instruction afterward. Executes original instruction through an internal trampoline when needed.
```

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

### fn instrument

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html

Installs an instruction-level hook at the specified address and executes the original instruction afterward.

```APIDOC
## fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

### Description
Installs an instruction-level hook at the given memory address. The function patches the target instruction with a trap opcode and registers the provided callback. Upon triggering the trap, the callback receives a mutable `HookContext`. If the callback does not redirect control flow, the original instruction is executed via an internal trampoline.

### Parameters
- **address** (u64) - The memory address where the instruction hook should be installed.
- **callback** (InstrumentCallback) - The function to be executed when the trap is hit.

### Returns
- **Result<u32, SigHookError>** - Returns the original 4-byte value previously stored at the address on success, or a `SigHookError` on failure.

### Example
```rust
use sighook::{instrument, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let target = 0x1000_0000u64;
let original = instrument(target, on_hit)?;
```
```

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

### Basic usage of instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument_no_original.html?search=std%3A%3Avec

Demonstrates the basic setup for hooking a target address with a callback function.

```rust
use sighook::{instrument_no_original, HookContext};

extern "C" fn replace_logic(_address: u64, _ctx: *mut HookContext) {}

let target = 0x1000_0010u64;
let original = instrument_no_original(target, replace_logic)?;
let _ = original;
```

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

### pub fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Installs an instruction-level hook at the specified address. The original instruction is executed after the callback unless the callback redirects control flow.

```APIDOC
## pub fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

### Description
Installs an instruction-level hook and executes the original instruction afterward. This API patches the target instruction with a trap opcode and registers the provided callback.

### Parameters
- **address** (u64) - The memory address where the hook should be installed.
- **callback** (InstrumentCallback) - The function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the original 4-byte value previously stored at the address on success, or a SigHookError if the operation fails.
```

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

### fn instrument

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html?search=u32+-%3E+bool

Installs an instruction-level hook at the specified address. The provided callback is executed when the trap is hit, and the original instruction is executed afterward unless control flow is redirected.

```APIDOC
## fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

### Description
Installs an instruction-level hook and executes the original instruction afterward. This API patches the target instruction with a trap opcode and registers the provided callback.

### Parameters
- **address** (u64) - The memory address to patch.
- **callback** (InstrumentCallback) - The function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the original 4-byte value previously stored at the address on success, or a SigHookError on failure.
```

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

### instrument_no_original(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument_no_original.html?search=std%3A%3Avec

Installs an instruction-level hook at the specified address. The original instruction is skipped by default, and execution advances past the patched instruction after the callback returns, unless the callback modifies control flow.

```APIDOC
## fn instrument_no_original

### Description
Installs an instruction-level hook and skips the original instruction by default. After the callback returns, execution advances past the patched instruction unless the callback explicitly changes control flow.

### Signature
`pub fn instrument_no_original(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **address** (u64) - The memory address where the hook should be installed.
- **callback** (InstrumentCallback) - The function to execute when the hook is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the original 4-byte value previously stored at the address on success, or a SigHookError on failure.

### Example
```rust
use sighook::{instrument_no_original, HookContext};

extern "C" fn replace_logic(_address: u64, _ctx: *mut HookContext) {}

let target = 0x1000_0010u64;
let original = instrument_no_original(target, replace_logic)?;
```
```

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

### inline_hook

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Installs a signal-based inline entry hook at a function address.

```APIDOC
## inline_hook(address, callback)

### Description
Places an inline hook at the specified function entry point using signal-based interception.

### Parameters
- **address** (u64) - The function entry address to hook.
- **callback** (extern "C" fn) - The replacement function to execute.
```

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

### instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument_no_original.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Installs an instruction-level hook at a specific memory address. This function skips the original instruction by default and executes the provided callback, returning the original 4-byte value stored at the address.

```APIDOC
## instrument_no_original(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

### Description
Installs an instruction-level hook at the specified address. It skips the original instruction by default, meaning execution advances past the patched instruction after the callback returns, unless the callback modifies control flow.

### Parameters
- **address** (u64) - The memory address where the hook should be installed.
- **callback** (InstrumentCallback) - The function to execute when the hook is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the original 4-byte value previously stored at the address on success, or a SigHookError on failure.

### Example
```rust
use sighook::{instrument_no_original, HookContext};

extern "C" fn replace_logic(_address: u64, _ctx: *mut HookContext) {}

let target = 0x1000_0010u64;
let original = instrument_no_original(target, replace_logic)?;
```
```

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

### instrument_no_original(address: u64, callback: InstrumentCallback)

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument_no_original.html?search=

Installs an instruction-level hook at the specified address and skips the original instruction by default. After the callback returns, execution advances past the patched instruction unless the callback modifies the control flow.

```APIDOC
## instrument_no_original

### Signature
`pub fn instrument_no_original(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Description
Installs an instruction-level hook and skips the original instruction by default. This behaves like `instrument` except `execute_original = false`. After your callback returns, execution advances past the patched instruction unless the callback explicitly changes control flow (`pc`/`rip`).

### Parameters
- **address** (u64) - The memory address where the hook should be installed.
- **callback** (InstrumentCallback) - The function to execute when the hook is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the original 4-byte value previously stored at the address on success, or a `SigHookError` on failure.

### Example
```rust
use sighook::{instrument_no_original, HookContext};

extern "C" fn replace_logic(_address: u64, _ctx: *mut HookContext) {}

let target = 0x1000_0010u64;
let original = instrument_no_original(target, replace_logic)?;
```
```

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

### inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Installs a signal-based entry hook at the specified address. The callback is executed when the trap is triggered, allowing for register modification.

```APIDOC
## inline_hook

### Description
Installs a signal-based entry hook using trap instrumentation at the provided memory address. The hook allows for custom callbacks to modify registers (e.g., return values). If the callback does not redirect control flow, the hook automatically returns to the caller.

### Signature
`pub fn inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **addr** (u64) - The memory address where the function entry hook should be installed.
- **callback** (InstrumentCallback) - The function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the first 4 bytes of the original instruction at the specified address on success, or a SigHookError on failure.

### Example
```rust
use sighook::{inline_hook, HookContext};

extern "C" fn replacement(_address: u64, ctx: *mut HookContext) {
    unsafe {
        #[cfg(target_arch = "aarch64")]
        {
            (*ctx).regs.named.x0 = 42;
        }
        #[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
        {
            (*ctx).rax = 42;
        }
    }
}

let function_entry = 0x1000_1000u64;
let original = inline_hook(function_entry, replacement)?;
```
```

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

### unhook

Source: https://docs.rs/sighook/0.10.0/sighook/index.html?search=std%3A%3Avec

Restores a previously installed hook at address.

```APIDOC
## unhook

### Description
Restores patch bytes for runtime-patched hooks; for prepatched hooks, it removes runtime state only.
```

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

### Hooking a symbol with inline_hook

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook.html

Examples of resolving a symbol address via dlsym and applying an inline hook.

```rust
28extern "C" fn init() {
29    unsafe {
30        let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"target_add".as_ptr());
31        if symbol.is_null() {
32            return;
33        }
34
35        let function_entry = symbol as u64;
36        let _ = inline_hook(function_entry, replace_in_callback);
37    }
38}
```

```rust
61extern "C" fn init() {
62    unsafe {
63        let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"target_vec_add".as_ptr());
64        if symbol.is_null() {
65            return;
66        }
67
68        let function_entry = symbol as u64;
69        let _ = inline_hook(function_entry, replace_in_callback);
70    }
71}
```

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

### fn inline_hook

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook.html?search=std%3A%3Avec

Installs a signal-based entry hook at the specified address. The callback is invoked when the trap is triggered, allowing for register modification.

```APIDOC
## fn inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

### Description
Installs a signal-based entry hook using trap instrumentation at the provided memory address. If the callback does not redirect control flow, the hook returns to the caller automatically.

### Parameters
- **addr** (u64) - The memory address of the function entry to hook.
- **callback** (InstrumentCallback) - The function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns the first 4 bytes of the original instruction at the address on success, or a SigHookError on failure.
```

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

### Instrument function signature

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html?search=

The function signature for installing an instruction-level hook.

```rust
pub fn instrument(
    address: u64,
    callback: InstrumentCallback,
) -> Result<u32, SigHookError>
```

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

### pub fn unhook(address: u64) -> Result<(), SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.unhook.html

Restores a previously installed hook at the specified address. This function supports hooks created by various instrumentation methods and restores the original instruction bytes for runtime-patched hooks.

```APIDOC
## unhook(address: u64)

### Description
Restores a previously installed hook at the provided memory address. On success, the runtime state for that address is removed, and any patched instruction bytes are restored.

### Signature
`pub fn unhook(address: u64) -> Result<(), SigHookError>`

### Parameters
- **address** (u64) - The memory address where the hook was previously installed.

### Returns
- **Result<(), SigHookError>** - Returns `Ok(())` on success, or a `SigHookError` if the unhook operation fails.

### Example
```rust
use sighook::{instrument, unhook, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_0000u64;
let _ = instrument(addr, on_hit)?;
unhook(addr)?;
```
```

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

### Add sighook dependency

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Add the crate to your Cargo.toml file.

```toml
[dependencies]
sighook = "0.10.0"
```

```toml
[dependencies]
sighook = { version = "0.10.0", features = ["patch_asm"] }
```

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

### Basic usage of unhook

Source: https://docs.rs/sighook/0.10.0/sighook/fn.unhook.html

Demonstrates the standard workflow of instrumenting an address and subsequently removing the hook.

```rust
use sighook::{instrument, unhook, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_0000u64;
let _ = instrument(addr, on_hit)?;
unhook(addr)?;
```

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

### Basic inline_hook usage

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook.html

Demonstrates setting up a hook with a callback that modifies registers based on the target architecture.

```rust
use sighook::{inline_hook, HookContext};

extern "C" fn replacement(_address: u64, ctx: *mut HookContext) {
    unsafe {
        #[cfg(target_arch = "aarch64")]
        {
            (*ctx).regs.named.x0 = 42;
        }
        #[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
        {
            (*ctx).rax = 42;
        }
    }
}

let function_entry = 0x1000_1000u64;
let original = inline_hook(function_entry, replacement)?;
let _ = original;
```

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

### Basic Usage of inline_hook_jump

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook_jump.html

Demonstrates the basic invocation of inline_hook_jump to detour a function entry to a replacement function.

```rust
use sighook::inline_hook_jump;

extern "C" fn replacement() {}

let function_entry = 0x1000_1000u64;
let replacement_addr = replacement as usize as u64;
let original = inline_hook_jump(function_entry, replacement_addr)?;
let _ = original;
```

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

### Verify Library Dependencies

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Check the DT_NEEDED entries of the target library to confirm the injection.

```bash
readelf -d libtarget.so | grep NEEDED
```

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

### fn unhook(address: u64) -> Result<(), SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.unhook.html?search=

Restores a previously installed hook at the specified address. This function supports hooks created by various instrumentation methods provided by the library.

```APIDOC
## fn unhook(address: u64) -> Result<(), SigHookError>

### Description
Restores a previously installed hook at the provided `address`. This API supports hook points created by `instrument`, `instrument_no_original`, `inline_hook`, `prepatched::instrument`, `prepatched::instrument_no_original`, `prepatched::inline_hook`, and `inline_hook_jump`. On success, runtime state for that address is removed and patched instruction bytes are restored.

### Parameters
- **address** (u64) - The memory address where the hook was previously installed.

### Returns
- **Result<(), SigHookError>** - Returns `Ok(())` on success, or a `SigHookError` if the unhook operation fails.

### Example
```rust
use sighook::{instrument, unhook, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_0000u64;
let _ = instrument(addr, on_hit)?;
unhook(addr)?;
```
```

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

### Instrumenting and unhooking

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html

Demonstrates the full lifecycle of instrumenting a function, executing it, and then restoring the original state using unhook.

```rust
35extern "C" fn init() {
36    unsafe {
37        let calc_symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
38        if calc_symbol.is_null() {
39            return;
40        }
41        let calc_fn: extern "C" fn(i32, i32) -> i32 = std::mem::transmute(calc_symbol);
42
43        let target_address = {
44            #[cfg(all(
45                any(target_os = "linux", target_os = "android"),
46                target_arch = "aarch64"
47            ))]
48            {
49                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc_add_insn".as_ptr());
50                if symbol.is_null() {
51                    return;
52                }
53                symbol as u64
54            }
55
56            #[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
57            {
58                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
59                if symbol.is_null() {
60                    return;
61                }
62                symbol as u64 + X86_PATCHPOINT_OFFSET
63            }
64
65            #[cfg(all(any(target_os = "macos", target_os = "ios"), target_arch = "aarch64"))]
66            {
67                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
68                if symbol.is_null() {
69                    return;
70                }
71                symbol as u64 + ADD_INSN_OFFSET
72            }
73        };
74
75        if let Err(err) = instrument(target_address, on_hit_should_not_run) {
76            println!("instrument failed: {err}");
77            return;
78        }
79
80        let hooked = calc_fn(3, 4);
81        println!("hooked_calc(3, 4) = {hooked}");
82        if hooked != 123 {
83            return;
84        }
85
86        if let Err(err) = unhook(target_address) {
87            println!("unhook failed: {err}");
88        }
89    }
90}
```

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

### instrument

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Registers a prepatched trap point and executes the original instruction afterward.

```APIDOC
## Function: instrument

### Description
Registers a prepatched trap point and executes original instruction afterward.
```

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

### Instrumenting with platform-specific address resolution

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html

Shows how to resolve a target address using libc symbols across different architectures and operating systems before calling instrument.

```rust
35extern "C" fn init() {
36    unsafe {
37        let target_address = {
38            #[cfg(all(
39                any(target_os = "linux", target_os = "android"),
40                target_arch = "aarch64"
41            ))]
42            {
43                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc_add_insn".as_ptr());
44                if symbol.is_null() {
45                    return;
46                }
47                symbol as u64
48            }
49
50            #[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
51            {
52                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
53                if symbol.is_null() {
54                    return;
55                }
56                symbol as u64 + X86_PATCHPOINT_OFFSET
57            }
58
59            #[cfg(all(any(target_os = "macos", target_os = "ios"), target_arch = "aarch64"))]
60            {
61                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
62                if symbol.is_null() {
63                    return;
64                }
65                symbol as u64 + ADD_INSN_OFFSET
66            }
67        };
68
69        let _ = instrument(target_address, on_hit);
70    }
71}
```

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

### Build and inject hook payload for Android

Source: https://docs.rs/sighook/0.10.0/sighook/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Commands for building the hook payload and injecting it into a target library using patchelf.

```bash
cargo build --release --target aarch64-linux-android
```

```bash
patchelf --add-needed libsighook_payload.so libtarget.so
```

```bash
readelf -d libtarget.so | grep NEEDED
```

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

### Patch with assembly string

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Use patch_asm to assemble and apply instructions at a target address, requiring the patch_asm feature.

```rust
use sighook::patch_asm;

let target_instruction = 0x1000_0000_u64;
#[cfg(target_arch = "aarch64")]
let _original = patch_asm(target_instruction, "mul w0, w8, w9")?;

#[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
let _original = patch_asm(target_instruction, "imul %edx")?;
```

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

### Basic patchcode Usage

Source: https://docs.rs/sighook/0.10.0/sighook/fn.patchcode.html

Demonstrates the basic invocation of patchcode to replace an instruction at a specific memory address.

```rust
use sighook::patchcode;

let address = 0x7FFF_0000_0000u64;
let old = patchcode(address, 0x90C3_9090)?;
let _ = old;
```

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

### sighook::prepatched::instrument

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/fn.instrument.html?search=u32+-%3E+bool

Registers a prepatched trap point and executes the original instruction afterward.

```APIDOC
## Function: instrument

### Description
Registers a prepatched trap point and executes the original instruction afterward. This function does not write trap opcodes; the target address must already be patched to trap offline.

### Signature
`pub fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **address** (u64) - The memory address to register the trap point.
- **callback** (InstrumentCallback) - The callback to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns a result containing a u32 identifier on success, or a SigHookError on failure.

### Notes
- On `aarch64`, execution of the original instruction requires a preloaded original opcode. Use `cache_original_opcode` before calling this function.
```

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

### Instrument with BRK (execute original)

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Use instrument to trap an instruction and execute the original opcode after the callback.

```rust
use sighook::{instrument, HookContext};

extern "C" fn on_hit(_address: u64, ctx: *mut HookContext) {
    let _ = ctx;
}

let target_instruction = 0x1000_0000_u64;
let _original = instrument(target_instruction, on_hit)?;
```

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

### Dynamic Symbol Hooking with inline_hook_jump

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook_jump.html

Shows how to use inline_hook_jump in conjunction with dlsym to hook a dynamically resolved symbol.

```rust
18extern "C" fn init() {
19    unsafe {
20        let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"target_add".as_ptr());
21        if symbol.is_null() {
22            return;
23        }
24
25        let function_entry = symbol as u64;
26        let replacement_fn = replacement as *const () as usize as u64;
27        let _ = inline_hook_jump(function_entry, replacement_fn);
28    }
29}
```

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

### instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Registers a prepatched trap point and skips the original instruction by default.

```APIDOC
## Function: instrument_no_original

### Description
Registers a prepatched trap point and skips original instruction by default.
```

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

### instrument

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Instruments a target instruction by placing a trap, executing the provided callback, and then executing the original opcode.

```APIDOC
## instrument(address, callback)

### Description
Instruments a target instruction at the specified address. When the trap is hit, the callback is executed, followed by the original instruction.

### Parameters
- **address** (u64) - The memory address to instrument.
- **callback** (extern "C" fn) - The function to execute when the trap is triggered.
```

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

### Patching memory with patch_bytes

Source: https://docs.rs/sighook/0.10.0/sighook/fn.patch_bytes.html

Demonstrates how to use patch_bytes to overwrite memory at a specific address and retrieve the original bytes.

```rust
use sighook::patch_bytes;

let address = 0x7FFF_0000_0000u64;
let original = patch_bytes(address, &[0x90, 0x90, 0x90, 0x90])?;
let _ = original;
```

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

### FpRegisters Struct Definition

Source: https://docs.rs/sighook/0.10.0/sighook/struct.FpRegisters.html

The structure definition for FpRegisters, marked with #[repr(C)] for binary compatibility.

```rust
#[repr(C)]
pub struct FpRegisters {
    pub regs: VRegisters,
    pub fpsr: u32,
    pub fpcr: u32,
}
```

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

### instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Instruments a target instruction by placing a trap, executing the provided callback, and skipping the original opcode.

```APIDOC
## instrument_no_original(address, callback)

### Description
Instruments a target instruction at the specified address. When the trap is hit, the callback is executed, and the original instruction is skipped.

### Parameters
- **address** (u64) - The memory address to instrument.
- **callback** (extern "C" fn) - The function to execute when the trap is triggered.
```

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

### instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/fn.instrument_no_original.html?search=u32+-%3E+bool

Registers a prepatched trap point at a specific address with a callback, skipping the original instruction.

```APIDOC
## Function: instrument_no_original

### Description
Registers a prepatched trap point and skips the original instruction by default. This function does not write trap opcodes; the target address must already be patched to trap offline.

### Signature
`pub fn instrument_no_original(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **address** (u64) - The memory address where the trap point is registered.
- **callback** (InstrumentCallback) - The callback function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns a u32 identifier on success, or a SigHookError if the registration fails.
```

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

### Inject Payload into Target Library

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Use patchelf to add the hook payload as a dependency to the target library.

```bash
patchelf --add-needed libsighook_payload.so libtarget.so
```

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

### patchcode(address: u64, new_opcode: u32) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.patchcode.html

Replaces one machine instruction at the specified address with a new opcode and returns the previous 4-byte value.

```APIDOC
## patchcode

### Description
Replaces one machine instruction at `address` with `new_opcode`. The function returns the previously stored 4-byte value.

### Signature
`pub fn patchcode(address: u64, new_opcode: u32) -> Result<u32, SigHookError>`

### Parameters
- **address** (u64) - The memory address where the instruction should be replaced.
- **new_opcode** (u32) - The new opcode to write. On `aarch64`, this is a 32-bit ARM instruction word. On `x86_64`, this is interpreted as little-endian bytes.

### Returns
- **Result<u32, SigHookError>** - Returns the previously stored 4-byte value on success, or a `SigHookError` if the operation fails (e.g., `PatchTooLong` on x86_64).

### Example
```rust
use sighook::patchcode;

let address = 0x7FFF_0000_0000u64;
let old = patchcode(address, 0x90C3_9090)?;
let _ = old;
```
```

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

### inline_hook

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/index.html

Registers a prepatched function-entry trap.

```APIDOC
## inline_hook

### Description
Registers a prepatched function-entry trap and returns to the caller by default.
```

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

### pub fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/fn.instrument.html

Registers a prepatched trap point and executes the original instruction afterward. Note that this function does not write trap opcodes; the target address must already be patched to trap offline. On aarch64, ensure the original opcode is preloaded using cache_original_opcode before invocation.

```APIDOC
## Function: instrument

### Description
Registers a prepatched trap point and executes the original instruction afterward. This function assumes the target address is already patched to trap.

### Signature
`pub fn instrument(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **address** (u64) - The memory address to instrument.
- **callback** (InstrumentCallback) - The callback function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns a handle (u32) on success, or a SigHookError if registration fails.

### Notes
- Does not write trap opcodes.
- On aarch64, requires a preloaded original opcode via `cache_original_opcode`.
```

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

### Build Android Hook Payload

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Compile the hook payload for the AArch64 Android architecture.

```bash
cargo build --release --target aarch64-linux-android
```

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

### instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/index.html

Registers a prepatched trap point that skips the original instruction.

```APIDOC
## instrument_no_original

### Description
Registers a prepatched trap point and skips the original instruction by default.
```

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

### Platform-specific address resolution for instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument_no_original.html?search=std%3A%3Avec

Shows how to resolve a target address using platform-specific symbols before calling instrument_no_original.

```rust
34extern "C" fn init() {
35    unsafe {
36        let target_address = {
37            #[cfg(all(
38                any(target_os = "linux", target_os = "android"),
39                target_arch = "aarch64"
40            ))]
41            {
42                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc_add_insn".as_ptr());
43                if symbol.is_null() {
44                    return;
45                }
46                symbol as u64
47            }
48
49            #[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
50            {
51                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
52                if symbol.is_null() {
53                    return;
54                }
55                symbol as u64 + X86_PATCHPOINT_OFFSET
56            }
57
58            #[cfg(all(any(target_os = "macos", target_os = "ios"), target_arch = "aarch64"))]
59            {
60                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
61                if symbol.is_null() {
62                    return;
63                }
64                symbol as u64 + ADD_INSN_OFFSET
65            }
66        };
67
68        let _ = instrument_no_original(target_address, replace_logic);
69    }
70}
```

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

### pub fn inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/fn.inline_hook.html?search=

Registers a prepatched function-entry trap at the specified address. This function behaves similarly to the standard inline_hook but avoids patching executable code pages.

```APIDOC
## Function: inline_hook

### Description
Registers a prepatched function-entry trap and returns to the caller by default. This function is designed to avoid patching executable code pages.

### Signature
`pub fn inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **addr** (u64) - The memory address where the trap should be registered.
- **callback** (InstrumentCallback) - The callback function to be executed when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns a u32 identifier on success, or a SigHookError if the registration fails.
```

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

### patchcode in an FFI Context

Source: https://docs.rs/sighook/0.10.0/sighook/fn.patchcode.html

Shows how to use patchcode within an unsafe block to modify a function symbol resolved via dlsym.

```rust
26extern "C" fn init() {
27    unsafe {
28        let target_address = {
29            #[cfg(all(
30                any(target_os = "linux", target_os = "android"),
31                target_arch = "aarch64"
32            ))]
33            {
34                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc_add_insn".as_ptr());
35                if symbol.is_null() {
36                    return;
37                }
38                symbol as u64
39            }
40
41            #[cfg(all(target_arch = "x86_64", any(target_os = "linux", target_os = "macos")))]
42            {
43                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
44                if symbol.is_null() {
45                    return;
46                }
47                symbol as u64 + X86_PATCHPOINT_OFFSET
48            }
49
50            #[cfg(all(any(target_os = "macos", target_os = "ios"), target_arch = "aarch64"))]
51            {
52                let symbol = libc::dlsym(libc::RTLD_DEFAULT, c"calc".as_ptr());
53                if symbol.is_null() {
54                    return;
55                }
56                symbol as u64 + ADD_INSN_OFFSET
57            }
58        };
59
60        let _ = patchcode(target_address, PATCH_ADD_TO_MUL_OPCODE);
61    }
62}
```

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

### inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/fn.inline_hook.html

Registers a prepatched function-entry trap and returns to the caller by default. This function behaves like the standard inline_hook but avoids patching executable code pages.

```APIDOC
## fn inline_hook

### Description
Registers a prepatched function-entry trap and returns to the caller by default. This function is designed to avoid patching executable code pages.

### Signature
`pub fn inline_hook(addr: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **addr** (u64) - The memory address to hook.
- **callback** (InstrumentCallback) - The callback function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns a result containing a u32 identifier on success, or a SigHookError on failure.
```

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

### original_opcode(address: u64) -> Option<u32>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.original_opcode.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the saved original 4-byte value for a previously patched address. This value is available after a successful call to patchcode, instrument, instrument_no_original, inline_hook, or inline_hook_jump on the same address.

```APIDOC
## Function: original_opcode

### Description
Returns the saved original 4-byte value for a previously patched address. The value is available after a successful call to `patchcode`, `instrument`, `instrument_no_original`, `inline_hook`, or `inline_hook_jump` on the same address.

### Signature
`pub fn original_opcode(address: u64) -> Option<u32>`

### Parameters
- **address** (u64) - The memory address to query for the original opcode.

### Returns
- **Option<u32>** - Returns `Some(u32)` containing the original opcode if available, otherwise `None`.

### Example
```rust
use sighook::{instrument, original_opcode, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_2000u64;
let _ = instrument(addr, on_hit)?;
let maybe_old = original_opcode(addr);
```
```

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

### original_opcode(address: u64) -> Option<u32>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.original_opcode.html?search=

Retrieves the saved original 4-byte value for a previously patched address. This value is available after a successful call to patchcode, instrument, instrument_no_original, inline_hook, or inline_hook_jump on the same address.

```APIDOC
## Function: original_opcode

### Description
Returns the saved original 4-byte value for a previously patched address. The value is available after a successful call to `patchcode`, `instrument`, `instrument_no_original`, `inline_hook`, or `inline_hook_jump` on the same address.

### Signature
`pub fn original_opcode(address: u64) -> Option<u32>`

### Parameters
- **address** (u64) - The memory address to query for the original opcode.

### Returns
- **Option<u32>** - Returns `Some(u32)` containing the original opcode if found, or `None` if no original opcode is associated with the address.

### Example
```rust
use sighook::{instrument, original_opcode, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_2000u64;
let _ = instrument(addr, on_hit)?;
let maybe_old = original_opcode(addr);
```
```

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

### Instrument with BRK (skip original)

Source: https://docs.rs/sighook/0.10.0/sighook/index.html

Use instrument_no_original to trap an instruction and prevent the original opcode from executing.

```rust
use sighook::{instrument_no_original, HookContext};

extern "C" fn replace_logic(_address: u64, ctx: *mut HookContext) {
    let _ = ctx;
}

let target_instruction = 0x1000_0010_u64;
let _original = instrument_no_original(target_instruction, replace_logic)?;
```

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

### instrument(target: u64, hook: extern "C" fn(u64, *mut HookContext)) -> Result<Original, Error>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Instruments a target memory address with a provided hook function. Returns an Original handle that can be used to manage the hook.

```APIDOC
## instrument(target, hook)

### Description
Instruments a specific memory address with a hook function. When the execution reaches the target address, the provided hook function is executed.

### Parameters
- **target** (u64) - The memory address to instrument.
- **hook** (extern "C" fn(u64, *mut HookContext)) - The function to execute when the target is hit.

### Returns
- **Result<Original, Error>** - Returns an Original handle on success, or an error if instrumentation fails.
```

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

### inline_hook_jump(addr: u64, replace_fn: u64) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook_jump.html

Detours a function entry to a specified replacement function using inline jump patching. It attempts a near jump first and falls back to a far jump sequence if necessary.

```APIDOC
## Function: inline_hook_jump

### Description
Detours a function entry to `replace_fn` with inline jump patching. The function attempts a near jump first and falls back to an architecture-specific far jump sequence if the target is out of range.

### Signature
`pub fn inline_hook_jump(addr: u64, replace_fn: u64) -> Result<u32, SigHookError>`

### Parameters
- **addr** (u64) - The memory address of the function entry to hook.
- **replace_fn** (u64) - The memory address of the replacement function.

### Returns
- **Result<u32, SigHookError>** - Returns the first 4 bytes of the original instruction bytes at `addr` on success, or a `SigHookError` on failure.

### Example
```rust
use sighook::inline_hook_jump;

extern "C" fn replacement() {}

let function_entry = 0x1000_1000u64;
let replacement_addr = replacement as usize as u64;
let original = inline_hook_jump(function_entry, replacement_addr)?;
```
```

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

### Function Signature

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook.html?search=std%3A%3Avec

The signature for the inline_hook function.

```rust
pub fn inline_hook(
    addr: u64,
    callback: InstrumentCallback,
) -> Result<u32, SigHookError>
```

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

### original_opcode(address: u64) -> Option<u32>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.original_opcode.html

Retrieves the saved original 4-byte value for a previously patched address. This value is available after successful calls to patchcode, instrument, instrument_no_original, inline_hook, or inline_hook_jump.

```APIDOC
## Function: original_opcode

### Description
Returns the saved original 4-byte value for a previously patched address. The value is available after a successful call to `patchcode`, `instrument`, `instrument_no_original`, `inline_hook`, or `inline_hook_jump` on the same address.

### Signature
`pub fn original_opcode(address: u64) -> Option<u32>`

### Parameters
- **address** (u64) - The memory address to query for the original opcode.

### Returns
- **Option<u32>** - Returns `Some(u32)` containing the original 4-byte opcode if available, otherwise `None`.

### Example
```rust
use sighook::{instrument, original_opcode, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_2000u64;
let _ = instrument(addr, on_hit)?;
let maybe_old = original_opcode(addr);
let _ = maybe_old;
```
```

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

### inline_hook_jump(addr: u64, replace_fn: u64) -> Result<u32, SigHookError>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.inline_hook_jump.html?search=std%3A%3Avec

Detours a function entry to a specified replacement function using inline jump patching. It attempts a near jump first and falls back to an architecture-specific far jump sequence if necessary.

```APIDOC
## Function: inline_hook_jump

### Description
Detours a function entry to `replace_fn` with inline jump patching. The function attempts a near jump first for efficiency and falls back to an architecture-specific far jump sequence if the target is out of range.

### Signature
`pub fn inline_hook_jump(addr: u64, replace_fn: u64) -> Result<u32, SigHookError>`

### Parameters
- **addr** (u64) - The memory address of the function entry to be hooked.
- **replace_fn** (u64) - The memory address of the replacement function.

### Returns
- **Result<u32, SigHookError>** - Returns the first 4 bytes of the original instruction bytes at the target address on success, or a `SigHookError` if the operation fails.
```

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

### instrument_no_original

Source: https://docs.rs/sighook/0.10.0/sighook/prepatched/fn.instrument_no_original.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Registers a prepatched trap point and skips the original instruction by default. This function assumes the target address is already patched to trap.

```APIDOC
## Function: instrument_no_original

### Description
Registers a prepatched trap point and skips the original instruction by default. This API does not write trap opcodes; the target address must already be patched to trap offline.

### Signature
`pub fn instrument_no_original(address: u64, callback: InstrumentCallback) -> Result<u32, SigHookError>`

### Parameters
- **address** (u64) - The memory address where the trap point is registered.
- **callback** (InstrumentCallback) - The callback function to execute when the trap is triggered.

### Returns
- **Result<u32, SigHookError>** - Returns a result containing a u32 identifier on success, or a SigHookError if the registration fails.
```

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

### unhook(target: u64) -> Result<(), Error>

Source: https://docs.rs/sighook/0.10.0/sighook/fn.instrument.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Removes an existing hook from the specified memory address.

```APIDOC
## unhook(target)

### Description
Removes a previously applied hook from the specified memory address, restoring the original instruction flow.

### Parameters
- **target** (u64) - The memory address from which to remove the hook.

### Returns
- **Result<(), Error>** - Returns Ok(()) on success, or an error if the unhook operation fails.
```

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

### Retrieve original opcode at a patched address

Source: https://docs.rs/sighook/0.10.0/sighook/fn.original_opcode.html

Demonstrates usage of original_opcode after successfully instrumenting a memory address. Requires a prior successful call to an instrumentation or hooking function.

```rust
use sighook::{instrument, original_opcode, HookContext};

extern "C" fn on_hit(_address: u64, _ctx: *mut HookContext) {}

let addr = 0x1000_2000u64;
let _ = instrument(addr, on_hit)?;
let maybe_old = original_opcode(addr);
let _ = maybe_old;
```
Tokens:
Raw