Retour

https://docs.rs/retour/latest/
Admin
Retour is a cross-platform, thread-safe inline detouring library written in Rust that disassembles...
Tokens:27,653
Snippets:179
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### static_detour Usage Examples

Source: https://docs.rs/retour/latest/retour/macro.static_detour.html

Examples demonstrating simple, unsafe, and visibility-restricted static detour definitions.

```rust
static_detour! {
  // The simplest detour
  static Foo: fn();

  // An unsafe public detour with a different calling convention
  pub static PubFoo: unsafe extern "C" fn(i32) -> i32;

  // A specific visibility modifier
  pub(crate) static PubSelf: unsafe extern "C" fn();
}
```

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

### Chaining Initialization and Activation

Source: https://docs.rs/retour/latest/retour/struct.StaticDetour.html

Example of chaining the initialize and enable methods.

```rust
unsafe { Test.initialize(add5, |x| x - 5)?.enable()? };
```

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

### StaticDetour Usage Example

Source: https://docs.rs/retour/latest/retour/struct.StaticDetour.html

A complete example demonstrating how to define, initialize, enable, and use a static detour.

```rust
use std::error::Error;
use retour::static_detour;

static_detour! {
  static Test: fn(i32) -> i32;
}

fn add5(val: i32) -> i32 {
  val + 5
}

fn add10(val: i32) -> i32 {
  val + 10
}

fn main() -> Result<(), Box<dyn Error>> {
  // Replace the 'add5' function with 'add10' (can also be a closure)
  unsafe { Test.initialize(add5, add10)? };

  assert_eq!(add5(1), 6);
  assert_eq!(Test.call(1), 6);

  unsafe { Test.enable()? };

  // The original function is detoured to 'add10'
  assert_eq!(add5(1), 11);

 // The original function can still be invoked using 'call'
  assert_eq!(Test.call(1), 6);

  // It is also possible to change the detour whilst hooked
  Test.set_detour(|val| val - 5);
  assert_eq!(add5(5), 0);

  unsafe { Test.disable()? };

  assert_eq!(add5(1), 6);
  Ok(())
}
```

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

### GenericDetour Usage Example

Source: https://docs.rs/retour/latest/retour/struct.GenericDetour.html

Demonstrates creating, enabling, and disabling a hook using GenericDetour.

```rust
use retour::GenericDetour;

fn add5(val: i32) -> i32 {
  val + 5
}

fn add10(val: i32) -> i32 {
  val + 10
}

let mut hook = unsafe { GenericDetour::<fn(i32) -> i32>::new(add5, add10)? };

assert_eq!(add5(5), 10);
assert_eq!(hook.call(5), 10);

unsafe { hook.enable()? };

assert_eq!(add5(5), 15);
assert_eq!(hook.call(5), 10);

unsafe { hook.disable()? };

assert_eq!(add5(5), 10);
```

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

### FromIterator Implementation Examples

Source: https://docs.rs/retour/latest/retour/type.Result.html

Shows how FromIterator collects results, stopping at the first Err encountered.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

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

### RIP Relative Displacement Example

Source: https://docs.rs/retour/latest/src/retour/arch/x86/trampoline/mod.rs.html

An assembly example illustrating how RIP-relative operand offsets are adjusted during relocation.

```asm
mov eax, [rip+0x10]   ; the displacement before relocation
mov eax, [rip+0x4892] ; theoretical adjustment after relocation
```

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

### x86 Detour Procedure Example

Source: https://docs.rs/retour/latest/index.html

Illustrates the memory layout of a function before and after applying a detour, showing the replacement of the function prologue with a relative jump.

```assembly
0 int return_five() {
1     return 5;
00400020 [b8 05 00 00 00] mov eax, 5
00400025 [c3]             ret
2 }
3
4 int detour_function() {
5     return 10;
00400040 [b8 0A 00 00 00] mov eax, 10
00400045 [c3]             ret
6 }
```

```assembly
0 int return_five() {
1     return detour_function();
00400020 [e9 16 00 00 00] jmp 1b <detour_function>
00400025 [c3]             ret
2 }
3
4 int detour_function() {
5     return 10;
00400040 [b8 0a 00 00 00] mov eax, 10
00400045 [c3]             ret
6 }
```

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

### IntoIterator Implementation Examples

Source: https://docs.rs/retour/latest/retour/type.Result.html

Demonstrates converting a Result into an iterator that yields the contained value if Ok, or nothing if Err.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

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

### Cloning Result Contents

Source: https://docs.rs/retour/latest/retour/type.Result.html

Examples of cloning the contents of an Ok variant from a Result containing a reference.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

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

### Copying Result Contents

Source: https://docs.rs/retour/latest/retour/type.Result.html

Examples of copying the contents of an Ok variant from a Result containing a reference.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

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

### Unwrap Unchecked Examples

Source: https://docs.rs/retour/latest/retour/type.Result.html

Demonstrates the use of unwrap_unchecked, which is unsafe and causes undefined behavior if called on an Err variant.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked(); } // Undefined behavior!
```

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

### Unwrap Err Unchecked Examples

Source: https://docs.rs/retour/latest/retour/type.Result.html

Demonstrates the use of unwrap_err_unchecked, which is unsafe and causes undefined behavior if called on an Ok variant.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

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

### StaticDetour initialization chaining

Source: https://docs.rs/retour/latest/src/retour/detours/statik.rs.html

Shows how to chain initialization and activation for a static detour.

```rust
# use retour::{Result, static_detour};
# static_detour! {
#   static Test: fn(i32) -> i32;
# }
#
# fn add5(val: i32) -> i32 {
#   val + 5
# }
#
# fn main() -> Result<()> {
unsafe { Test.initialize(add5, |x| x - 5)?.enable()? };
# Ok(())
# }
```

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

### Create and manage a RawDetour

Source: https://docs.rs/retour/latest/src/retour/detours/raw.rs.html

Demonstrates initializing a RawDetour, enabling/disabling the hook, and using the trampoline to invoke the original function.

```rust
# use retour::Result;
use retour::RawDetour;
use std::mem;

fn add5(val: i32) -> i32 {
  val + 5
}

fn add10(val: i32) -> i32 {
  val + 10
}

# fn main() -> Result<()> {
let mut hook = unsafe { RawDetour::new(add5 as *const (), add10 as *const ())? };

assert_eq!(add5(5), 10);
assert_eq!(hook.is_enabled(), false);

unsafe { hook.enable()? };
assert!(hook.is_enabled());

let original: fn(i32) -> i32 = unsafe { mem::transmute(hook.trampoline()) };

assert_eq!(add5(5), 15);
assert_eq!(original(5), 10);

unsafe { hook.disable()? };
assert_eq!(add5(5), 10);
# Ok(())
# }
```

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

### initialize

Source: https://docs.rs/retour/latest/retour/struct.StaticDetour.html

Creates a new hook given a target function and a compatible detour closure. This method can only be called once per static instance.

```APIDOC
## pub unsafe fn initialize<D>(&self, target: T, closure: D) -> Result<&Self>

### Description
Initializes the static detour with a target function and a replacement closure. Returns a reference to self to allow for method chaining.

### Parameters
- **target** (T) - The original function to be hooked.
- **closure** (D) - The replacement function or closure to execute.
```

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

### StaticDetour::enable

Source: https://docs.rs/retour/latest/src/retour/detours/statik.rs.html

Enables the detour for the initialized function.

```APIDOC
## enable

### Description
Enables the detour, causing the target function to redirect to the provided closure.

### Returns
- **Result<()>** - Returns success or an error if not initialized.
```

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

### GenericDetour::enable

Source: https://docs.rs/retour/latest/retour/struct.GenericDetour.html

Enables the detour hook.

```APIDOC
## pub unsafe fn enable(&self) -> Result<()>

### Description
Enables the detour, redirecting calls from the target function to the detour function.
```

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

### RawDetour::enable

Source: https://docs.rs/retour/latest/retour/struct.RawDetour.html

Enables the detour.

```APIDOC
## pub unsafe fn enable(&self) -> Result<()>

### Description
Enables the detour, allowing the detour function to intercept calls to the target function.

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

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

### Compiler Configuration

Source: https://docs.rs/retour/latest/src/retour/lib.rs.html

Required feature flags and recursion limits for the library, including nightly-only features.

```rust
1#![recursion_limit = "1024"]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![cfg_attr(
4  feature = "static-detour",
5  feature(unboxed_closures, tuple_trait)
6)]
7#![cfg_attr(
8  all(feature = "static-detour", test),
9  feature(naked_functions)
10)]
11#![cfg_attr(
12  feature = "thiscall-abi",
13  feature(abi_thiscall)
14)]
```

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

### Initialize and Use Disassembler

Source: https://docs.rs/retour/latest/src/retour/arch/x86/trampoline/disasm.rs.html

Defines the Disassembler struct and its initialization logic using udis86 bindings.

```rust
//! The underlying disassembler should be opaque to the outside.
use std::slice;

/// A x86/x64 disassembler.
pub struct Disassembler(udis::ud);

impl Disassembler {
  /// Creates a default x86 disassembler.
  pub fn new(target: *const ()) -> Disassembler {
    unsafe {
      let mut ud = ::std::mem::zeroed();
      udis::ud_init(&mut ud);
      udis::ud_set_user_opaque_data(&mut ud, target as *mut _);
      udis::ud_set_input_hook(&mut ud, Some(Self::udis_read_address));
      udis::ud_set_mode(&mut ud, (::std::mem::size_of::<usize>() * 8) as u8);
      Disassembler(ud)
    }
  }

  /// Reads one byte from a pointer and advances it.
  unsafe extern "C" fn udis_read_address(ud: *mut udis::ud) -> libc::c_int {
    let pointer = udis::ud_get_user_opaque_data(ud) as *mut u8;
    let result = *pointer;
    udis::ud_set_user_opaque_data(ud, pointer.offset(1) as *mut _);
    libc::c_int::from(result)
  }
}
```

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

### Into Ok (Nightly)

Source: https://docs.rs/retour/latest/retour/type.Result.html

Extracts the Ok value from a Result that is guaranteed not to contain an error.

```rust

fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

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

### Create and manage a function detour

Source: https://docs.rs/retour/latest/retour/struct.RawDetour.html

Demonstrates creating a detour between two functions, enabling it, and using the trampoline to call the original function.

```rust
use retour::RawDetour;
use std::mem;

fn add5(val: i32) -> i32 {
  val + 5
}

fn add10(val: i32) -> i32 {
  val + 10
}

let mut hook = unsafe { RawDetour::new(add5 as *const (), add10 as *const ())? };

assert_eq!(add5(5), 10);
assert_eq!(hook.is_enabled(), false);

unsafe { hook.enable()? };
assert!(hook.is_enabled());

let original: fn(i32) -> i32 = unsafe { mem::transmute(hook.trampoline()) };

assert_eq!(add5(5), 15);
assert_eq!(original(5), 10);

unsafe { hook.disable()? };
assert_eq!(add5(5), 10);
```

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

### Instruction Wrapper and Analysis

Source: https://docs.rs/retour/latest/src/retour/arch/x86/trampoline/disasm.rs.html

Provides a safe wrapper for disassembled instructions and methods to analyze mnemonic types and operand displacements.

```rust
/// Safe wrapper around an instruction.
pub struct Instruction {
  address: usize,
  mnemonic: udis::ud_mnemonic_code,
  operands: Vec<udis::ud_operand>,
  bytes: &'static [u8],
}

impl Instruction {
  /// Disassembles a new instruction at the specified address.
  pub unsafe fn new(disasm: &mut Disassembler, address: *const ()) -> Option<Self> {
    let instruction_bytes = udis::ud_disassemble(&mut disasm.0) as usize;
    if instruction_bytes > 0 {
      Some(Instruction {
        address: address as usize,
        mnemonic: udis::ud_insn_mnemonic(&disasm.0),
        operands: disasm.0.operand.to_vec(),
        bytes: slice::from_raw_parts(address as *const _, instruction_bytes),
      })
    } else {
      None
    }
  }

  /// Returns the instruction's address.
  pub fn address(&self) -> usize {
    self.address
  }

  /// Returns the next instruction's address.
  pub fn next_instruction_address(&self) -> usize {
    self.address() + self.len()
  }

  /// Returns the instructions relative branch offset, if applicable.
  pub fn relative_branch_displacement(&self) -> Option<isize> {
    unsafe {
      self
        .operands
        .iter()
        .find(|op| op.otype == udis::ud_type::UD_OP_JIMM)
        .map(|op| match op.size {
          8 => op.lval.sbyte as isize,
          32 => op.lval.sdword as isize,
          _ => unreachable!("Operand size: {}", op.size),
        })
    }
  }

  /// Returns the instructions RIP operand displacement if applicable.
  pub fn rip_operand_displacement(&self) -> Option<isize> {
    unsafe {
      // The operands displacement (e.g `mov eax, [rip+0x10]` ⟶ 0x10)
      self
        .operands
        .iter()
        .find(|op| op.otype == udis::ud_type::UD_OP_MEM && op.base == udis::ud_type::UD_R_RIP)
        .map(|op| op.lval.sdword as isize)
    }
  }

  /// Returns true if this instruction any type of a loop.
  pub fn is_loop(&self) -> bool {
    matches!(
      self.mnemonic,
      udis::ud_mnemonic_code::UD_Iloop
        | udis::ud_mnemonic_code::UD_Iloope
        | udis::ud_mnemonic_code::UD_Iloopne
        | udis::ud_mnemonic_code::UD_Ijecxz
        | udis::ud_mnemonic_code::UD_Ijcxz
    )
  }

  /// Returns true if this instruction is an unconditional jump.
  pub fn is_unconditional_jump(&self) -> bool {
    self.mnemonic == udis::ud_mnemonic_code::UD_Ijmp
  }

  /// Returns true if this instruction is a function call.
  pub fn is_call(&self) -> bool {
    self.mnemonic == udis::ud_mnemonic_code::UD_Icall
  }

  /// Returns true if this instruction is a return.
  pub fn is_return(&self) -> bool {
    self.mnemonic == udis::ud_mnemonic_code::UD_Iret
  }

  /// Returns the instruction's bytes.
  pub unsafe fn as_slice(&self) -> &[u8] {
    self.bytes
  }

  /// Returns the size of the instruction in bytes.
  pub fn len(&self) -> usize {
    self.bytes.len()
  }
}
```

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

### RawDetour::new

Source: https://docs.rs/retour/latest/retour/struct.RawDetour.html

Constructs a new inline detour patcher. The hook is disabled by default.

```APIDOC
## pub unsafe fn new(target: *const (), detour: *const ()) -> Result<Self>

### Description
Constructs a new inline detour patcher. The hook is disabled by default. Note that there is no guarantee the detour function will be called if the target function is inlined.

### Parameters
- **target** (*const ()) - The address of the function to hook.
- **detour** (*const ()) - The address of the detour function.

### Returns
- **Result<Self>** - A new RawDetour instance or an error if the hook could not be created.
```

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

### enable

Source: https://docs.rs/retour/latest/retour/struct.StaticDetour.html

Enables the detour, redirecting calls from the target function to the detour closure.

```APIDOC
## pub unsafe fn enable(&self) -> Result<()>

### Description
Activates the hook, causing the target function to execute the detour logic.
```

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

### Create References with as_ref and as_mut

Source: https://docs.rs/retour/latest/retour/type.Result.html

Converts a Result into a Result containing references to the original values.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### Trampoline::new

Source: https://docs.rs/retour/latest/src/retour/arch/x86/trampoline/mod.rs.html

Constructs a new trampoline for a given target address with a specified margin.

```APIDOC
## Trampoline::new

### Description
Constructs a new trampoline for an address. This is an unsafe operation that builds a trampoline based on the target memory address and a required margin.

### Signature
`pub unsafe fn new(target: *const (), margin: usize) -> Result<Trampoline>`

### Parameters
- **target** (*const ()) - Required - The memory address to create a trampoline for.
- **margin** (usize) - Required - The preferred minimum amount of bytes to disassemble.

### Returns
- **Result<Trampoline>** - A Result containing the initialized Trampoline or an error if the build fails.
```

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

### GenericDetour::new

Source: https://docs.rs/retour/latest/retour/struct.GenericDetour.html

Creates a new hook instance given a target function and a compatible detour function.

```APIDOC
## pub unsafe fn new<D>(target: T, detour: D) -> Result<Self>

### Description
Creates a new hook given a target function and a compatible detour function.

### Signature
`pub unsafe fn new<D>(target: T, detour: D) -> Result<Self> where T: HookableWith<D>, D: Function`
```

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

### Unwrap Result or Default

Source: https://docs.rs/retour/latest/retour/type.Result.html

Returns the Ok value or the default value of the type if the result is Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

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

### Handling SameAddress Error in Retour

Source: https://docs.rs/retour/latest/src/retour/lib.rs.html

Demonstrates how to catch and assert the SameAddress error when attempting to detour a function to itself.

```rust
extern "C" fn add(x: i32, y: i32) -> i32 {
  unsafe { std::ptr::read_volatile(&x as *const i32) + y }
}

let err = unsafe { RawDetour::new(add as *const (), add as *const ()).unwrap_err() };
assert_matches!(err, Error::SameAddress);
}
```

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

### And Then Chaining

Source: https://docs.rs/retour/latest/retour/type.Result.html

Calls a function to produce a new Result if the current one is Ok.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}
```

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

### And Chaining

Source: https://docs.rs/retour/latest/retour/type.Result.html

Returns the provided Result if the current one is Ok, otherwise returns the Err value.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

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

### GenericDetour::call

Source: https://docs.rs/retour/latest/retour/struct.GenericDetour.html

Calls the original function.

```APIDOC
## fn call(&self, T::Arguments) -> T::Output

### Description
Calls the original function regardless of whether it's hooked or not.
```

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

### StaticDetour Definition

Source: https://docs.rs/retour/latest/retour/struct.StaticDetour.html

The basic structure definition for StaticDetour.

```rust
pub struct StaticDetour<T: Function> { /* private fields */ }
```

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

### Hookable Trait Implementation Macros

Source: https://docs.rs/retour/latest/src/retour/macros.rs.html

Macros for recursively generating hookable implementations for various function pointer types and calling conventions.

```rust
macro_rules! impl_hookable {
  (@recurse () ($($nm:ident : $ty:ident),*)) => {
    impl_hookable!(@impl_all ($($nm : $ty),*));
  };
  (@recurse
      ($hd_nm:ident : $hd_ty:ident $(, $tl_nm:ident : $tl_ty:ident)*)
      ($($nm:ident : $ty:ident),*)) => {
    impl_hookable!(@impl_all ($($nm : $ty),*));
    impl_hookable!(@recurse ($($tl_nm : $tl_ty),*) ($($nm : $ty,)* $hd_nm : $hd_ty));
  };

  (@impl_all ($($nm:ident : $ty:ident),*)) => {
    impl_hookable!(@impl_pair ($($nm : $ty),*) (                  fn($($ty),*) -> Ret));
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "cdecl"    fn($($ty),*) -> Ret));
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "stdcall"  fn($($ty),*) -> Ret));
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "fastcall" fn($($ty),*) -> Ret));
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "win64"    fn($($ty),*) -> Ret));
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "C"        fn($($ty),*) -> Ret));
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "system"   fn($($ty),*) -> Ret));

    #[cfg(feature = "thiscall-abi")]
    #[cfg_attr(docsrs, doc(cfg(feature = "thiscall-abi")))]
    impl_hookable!(@impl_pair ($($nm : $ty),*) (extern "thiscall" fn($($ty),*) -> Ret));
  };
```

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

### Fallback to another Result with or

Source: https://docs.rs/retour/latest/retour/type.Result.html

Returns the current Result if Ok, otherwise returns the provided alternative Result.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

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

### x86 Detour Test Cases

Source: https://docs.rs/retour/latest/src/retour/arch/x86/mod.rs.html

Various test cases demonstrating detour application on different x86 instruction patterns.

```rust
#[test]
  fn detour_relative_branch() -> Result<()> {
    #[naked]
    unsafe extern "C" fn branch_ret5() -> i32 {
      asm!(
        "
            xor eax, eax
            je 5f
            mov eax, 2
            jmp 2f
          5:
            mov eax, 5
          2:
            ret",
        options(noreturn)
      );
    }

    unsafe { detour_test(mem::transmute(branch_ret5 as usize), 5) }
  }
```

```rust
#[test]
  fn detour_hotpatch() -> Result<()> {
    #[naked]
    unsafe extern "C" fn hotpatch_ret0() -> i32 {
      asm!(
        "
            nop
            nop
            nop
            nop
            nop
            xor eax, eax
            ret
            mov eax, 5",
        options(noreturn)
      );
    }

    unsafe { detour_test(mem::transmute(hotpatch_ret0 as usize + 5), 0) }
  }
```

```rust
#[test]
  fn detour_padding_after() -> Result<()> {
    #[naked]
    unsafe extern "C" fn padding_after_ret0() -> i32 {
      asm!(
        "
            mov edi, edi
            xor eax, eax
            ret
            nop
            nop",
        options(noreturn)
      );
    }

    unsafe { detour_test(mem::transmute(padding_after_ret0 as usize + 2), 0) }
  }
```

```rust
#[test]
  fn detour_external_loop() {
    #[naked]
    unsafe extern "C" fn external_loop() -> i32 {
      asm!(
        "
            loop 2f
            nop
            nop
            nop
            2:",
        options(noreturn)
      );
    }

    let error =
      unsafe { RawDetour::new(external_loop as *const (), ret10 as *const ()) }.unwrap_err();
    assert_matches!(error, Error::UnsupportedInstruction);
  }
```

```rust
#[test]
  #[cfg(target_arch = "x86_64")]
  fn detour_rip_relative_pos() -> Result<()> {
    #[naked]
    unsafe extern "C" fn rip_relative_ret195() -> i32 {
      asm!(
        "
            xor eax, eax
            mov al, [rip+0x3]
            nop
            nop
            nop
            ret",
        options(noreturn)
      );
    }

    unsafe { detour_test(rip_relative_ret195, 195) }
  }
```

```rust
#[test]
  #[cfg(target_arch = "x86_64")]
  fn detour_rip_relative_neg() -> Result<()> {
    #[naked]
    unsafe extern "C" fn rip_relative_prolog_ret49() -> i32 {
      asm!(
        "
            xor eax, eax
            mov al, [rip-0x8]
            ret",
        options(noreturn)
      );
    }

    unsafe { detour_test(rip_relative_prolog_ret49, 49) }
  }
```

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

### RawDetour::trampoline

Source: https://docs.rs/retour/latest/retour/struct.RawDetour.html

Returns a reference to the generated trampoline.

```APIDOC
## pub fn trampoline(&self) -> &()

### Description
Returns a reference to the generated trampoline, which can be used to call the original function.

### Returns
- **&()** - A reference to the trampoline.
```

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

### static_detour Syntax

Source: https://docs.rs/retour/latest/retour/macro.static_detour.html

The syntax template for defining static detours using the macro.

```rust
static_detour! {
  [pub] static NAME_1: [unsafe] [extern "cc"] fn([argument]...) [-> ret];
  [pub] static NAME_2: [unsafe] [extern "cc"] fn([argument]...) [-> ret];
  ...
  [pub] static NAME_N: [unsafe] [extern "cc"] fn([argument]...) [-> ret];
}
```

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

### Architecture-specific thunk module implementation

Source: https://docs.rs/retour/latest/src/retour/arch/x86/thunk/mod.rs.html

Defines the architecture-specific modules and exports the appropriate functions based on the target architecture.

```rust
1#![allow(dead_code)]

/// Implements x86 operations
pub mod x86;

/// Implements x64 operations
#[cfg(target_arch = "x86_64")]
pub mod x64;

#[cfg(target_arch = "x86")]
mod arch {
  pub use super::x86::call_rel32 as call;
  pub use super::x86::jcc_rel32 as jcc;
  pub use super::x86::jmp_rel32 as jmp;
}

#[cfg(target_arch = "x86_64")]
mod arch {
  pub use super::x64::call_abs as call;
  pub use super::x64::jcc_abs as jcc;
  pub use super::x64::jmp_abs as jmp;
}

// Export the default architecture
pub use self::arch::*;
```

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

### ProximityAllocator Implementation

Source: https://docs.rs/retour/latest/src/retour/alloc/proximity.rs.html

The core structure and methods for managing memory pools within a defined proximity range.

```rust
use std::ops::Range;
use std::slice;

use slice_pool::sync::{SliceBox, SlicePool};

use super::search as region_search;
use crate::error::{Error, Result};

/// Defines the allocation type.
pub type Allocation = SliceBox<u8>;

/// Shared instance containing all pools
pub struct ProximityAllocator {
  pub max_distance: usize,
  pub pools: Vec<SlicePool<u8>>,
}

impl ProximityAllocator {
  /// Allocates a slice in an eligible memory map.
  pub fn allocate(&mut self, origin: *const (), size: usize) -> Result<Allocation> {
    let memory_range = ((origin as usize).saturating_sub(self.max_distance))
      ..((origin as usize).saturating_add(self.max_distance));

    // Check if an existing pool can handle the allocation request
    self.allocate_memory(&memory_range, size).or_else(|_| {
      // ... otherwise allocate a pool within the memory range
      self.allocate_pool(&memory_range, origin, size).map(|pool| {
        // Use the newly allocated pool for the request
        let allocation = pool.alloc(size).unwrap();
        self.pools.push(pool);
        allocation
      })
    })
  }

  /// Releases the memory pool associated with an allocation.
  pub fn release(&mut self, value: &Allocation) {
    // Find the associated memory pool
    let index = self
      .pools
      .iter()
      .position(|pool| {
        let lower = pool.as_ptr() as usize;
        let upper = lower + pool.len();

        // Determine if this is the associated memory pool
        (lower..upper).contains(&(value.as_ptr() as usize))
      })
      .expect("retrieving associated memory pool");

    // Release the pool if the associated allocation is unique
    if self.pools[index].len() == 1 {
      self.pools.remove(index);
    }
  }

  /// Allocates a chunk using any of the existing pools.
  fn allocate_memory(&mut self, range: &Range<usize>, size: usize) -> Result<Allocation> {
    // Returns true if the pool's memory is within the range
    let is_pool_in_range = |pool: &SlicePool<u8>| {
      let lower = pool.as_ptr() as usize;
      let upper = lower + pool.len();
      range.contains(&lower) && range.contains(&(upper - 1))
    };

    // Tries to allocate a slice within any eligible pool
    self
      .pools
      .iter_mut()
      .filter_map(|pool| {
        if is_pool_in_range(pool) {
          pool.alloc(size)
        } else {
          None
        }
      })
      .next()
      .ok_or(Error::OutOfMemory)
  }

  /// Allocates a new pool close to `origin`.
  fn allocate_pool(
    &mut self,
    range: &Range<usize>,
    origin: *const (),
    size: usize,
  ) -> Result<SlicePool<u8>> {
    let before = region_search::before(origin, Some(range.clone()));
    let after = region_search::after(origin, Some(range.clone()));

    // TODO: Part of the pool can be out of range
    // Try to allocate after the specified address first (mostly because
    // macOS cannot allocate memory before the process's address).
    after
      .chain(before)
      .filter_map(|result| match result {
        Ok(address) => Self::allocate_fixed_pool(address, size).map(Ok),
        Err(error) => Some(Err(error)),
      })
      .next()
      .unwrap_or(Err(Error::OutOfMemory))
  }

  /// Tries to allocate fixed memory at the specified address.
  fn allocate_fixed_pool(address: *const (), size: usize) -> Option<SlicePool<u8>> {
    // Try to allocate memory at the specified address
    mmap::MemoryMap::new(
      size,
      &[
        mmap::MapOption::MapReadable,
        mmap::MapOption::MapWritable,
        mmap::MapOption::MapExecutable,
        mmap::MapOption::MapAddr(address as *const _),
      ],
    )
    .ok()
    .map(SliceableMemoryMap)
    .map(SlicePool::new)
  }
}

// TODO: Use memmap-rs instead
/// A wrapper for making a memory map compatible with `SlicePool`.
struct SliceableMemoryMap(mmap::MemoryMap);

impl SliceableMemoryMap {
  pub fn as_slice(&self) -> &[u8] {
    unsafe { slice::from_raw_parts(self.0.data(), self.0.len()) }
  }

  pub fn as_mut_slice(&mut self) -> &mut [u8] {
    unsafe { slice::from_raw_parts_mut(self.0.data(), self.0.len()) }
  }
}

impl AsRef<[u8]> for SliceableMemoryMap {
  fn as_ref(&self) -> &[u8] {
    self.as_slice()
  }
}

impl AsMut<[u8]> for SliceableMemoryMap {
  fn as_mut(&mut self) -> &mut [u8] {
    self.as_mut_slice()
  }
}

unsafe impl Send for SliceableMemoryMap {}
unsafe impl Sync for SliceableMemoryMap {}
```

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

### Provide a default value with unwrap_or

Source: https://docs.rs/retour/latest/retour/type.Result.html

Returns the contained value or a provided default value if the Result is Err.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

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

### RawDetour::disable

Source: https://docs.rs/retour/latest/retour/struct.RawDetour.html

Disables the detour.

```APIDOC
## pub unsafe fn disable(&self) -> Result<()>

### Description
Disables the detour, restoring the original behavior of the target function.

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

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

### Trampoline Generation Module

Source: https://docs.rs/retour/latest/src/retour/arch/x86/trampoline/mod.rs.html

The core implementation for creating trampolines, including the Trampoline struct and the Builder logic for processing instructions.

```rust
1use self::disasm::*;
2use crate::arch::x86::thunk;
3use crate::error::{Error, Result};
4use crate::pic;
5use std::mem;
6
7mod disasm;
8
9/// A trampoline generator (x86/x64).
10pub struct Trampoline {
11  emitter: pic::CodeEmitter,
12  prolog_size: usize,
13}
14
15impl Trampoline {
16  /// Constructs a new trampoline for an address.
17  pub unsafe fn new(target: *const (), margin: usize) -> Result<Trampoline> {
18    Builder::new(target, margin).build()
19  }
20
21  /// Returns a reference to the trampoline's code emitter.
22  pub fn emitter(&self) -> &pic::CodeEmitter {
23    &self.emitter
24  }
25
26  /// Returns the size of the prolog (i.e the amount of disassembled bytes).
27  pub fn prolog_size(&self) -> usize {
28    self.prolog_size
29  }
30}
31
32/// A trampoline builder.
33struct Builder {
34  /// Disassembler for x86/x64.
35  disassembler: Disassembler,
36  /// Target destination for a potential internal branch.
37  branch_address: Option<usize>,
38  /// Total amount of bytes disassembled.
39  total_bytes_disassembled: usize,
40  /// The preferred minimum amount of bytes disassembled.
41  margin: usize,
42  /// Whether disassembling has finished or not.
43  finished: bool,
44  /// The target the trampoline is adapted for.
45  target: *const (),
46}
47
48impl Builder {
49  /// Returns a trampoline builder.
50  pub fn new(target: *const (), margin: usize) -> Self {
51    Builder {
52      disassembler: Disassembler::new(target),
53      branch_address: None,
54      total_bytes_disassembled: 0,
55      finished: false,
56      target,
57      margin,
58    }
59  }
60
61  /// Creates a trampoline with the supplied settings.
62  ///
63  /// Margins larger than five bytes may lead to undefined behavior.
64  pub unsafe fn build(mut self) -> Result<Trampoline> {
65    let mut emitter = pic::CodeEmitter::new();
66
67    while !self.finished {
68      let instruction = self.next_instruction()?;
69      let thunk = self.process_instruction(&instruction)?;
70
71      // If the trampoline displacement is larger than the target
72      // function, all instructions will be displaced, and if there is
73      // internal branching, it will end up at the wrong instructions.
74      if self.is_instruction_in_branch(&instruction) && instruction.len() != thunk.len() {
75        Err(Error::UnsupportedInstruction)?;
76      } else {
77        emitter.add_thunk(thunk);
78      }
79
80      // Determine whether enough bytes for the margin has been disassembled
81      if self.total_bytes_disassembled >= self.margin && !self.finished {
82        // Add a jump to the first instruction after the prolog
83        emitter.add_thunk(thunk::jmp(instruction.next_instruction_address()));
84        self.finished = true;
85      }
86    }
87
88    Ok(Trampoline {
89      prolog_size: self.total_bytes_disassembled,
90      emitter,
91    })
92  }
93
94  /// Disassembles the next instruction and returns its properties.
95  unsafe fn next_instruction(&mut self) -> Result<Instruction> {
96    let instruction_address = self.target as usize + self.total_bytes_disassembled;
97
98    // Disassemble the next instruction
99    match Instruction::new(&mut self.disassembler, instruction_address as *const _) {
100      None => Err(Error::InvalidCode)?,
101      Some(instruction) => {
102        // Keep track of the total amount of bytes
103        self.total_bytes_disassembled += instruction.len();
104        Ok(instruction)
105      },
106    }
107  }
108
109  /// Returns an instruction after analysing and potentially modifies it.
110  unsafe fn process_instruction(
111    &mut self,
112    instruction: &Instruction,
113  ) -> Result<Box<dyn pic::Thunkable>> {
114    if let Some(displacement) = instruction.rip_operand_displacement() {
115      return self.handle_rip_relative_instruction(instruction, displacement);
116    } else if let Some(displacement) = instruction.relative_branch_displacement() {
117      return self.handle_relative_branch(instruction, displacement);
118    } else if instruction.is_return() {
119      // In case the operand is not placed in a branch, the function
120      // returns unconditionally (i.e it terminates here).
121      self.finished = !self.is_instruction_in_branch(instruction);
122    }
123
124    // The instruction does not use any position-dependant operands,
125    // therefore the bytes can be copied directly from source.
126    Ok(Box::new(instruction.as_slice().to_vec()))
127  }
```

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

### StaticDetour Call Method

Source: https://docs.rs/retour/latest/retour/struct.StaticDetour.html

The signature for the call method used to invoke the original function.

```rust
/// Calls the original function regardless of whether it's hooked or not.
///
/// Panics if called when the static detour has not yet been initialized.
fn call(&self, T::Arguments) -> T::Output
```

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

### GenericDetour Usage Test

Source: https://docs.rs/retour/latest/src/retour/lib.rs.html

Demonstrates using GenericDetour to hook a function and manage multiple detours on the same target.

```rust
  #[test]
  fn detours_share_target() -> Result<()> {
    #[inline(never)]
    extern "C" fn add(x: i32, y: i32) -> i32 {
      unsafe { std::ptr::read_volatile(&x as *const i32) + y }
    }

    let hook1 = unsafe {
      extern "C" fn sub(x: i32, y: i32) -> i32 {
        x - y
      }
      GenericDetour::<extern "C" fn(i32, i32) -> i32>::new(add, sub)?
    };

    unsafe { hook1.enable()? };
    assert_eq!(add(5, 5), 0);

    let hook2 = unsafe {
      extern "C" fn div(x: i32, y: i32) -> i32 {
        x / y
      }
      GenericDetour::<extern "C" fn(i32, i32) -> i32>::new(add, div)?
    };

    unsafe { hook2.enable()? };

    // This will call the previous hook's detour
    assert_eq!(hook2.call(5, 5), 0);
    assert_eq!(add(10, 5), 2);
    Ok(())
  }
```

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

### Implement Drop for StaticDetour

Source: https://docs.rs/retour/latest/src/retour/detours/statik.rs.html

Handles the cleanup of the closure and detour pointers when the StaticDetour instance is dropped.

```rust
impl<T: Function> Drop for StaticDetour<T> {
  fn drop(&mut self) {
    let previous = self.closure.swap(ptr::null_mut(), Ordering::Relaxed);
    if !previous.is_null() {
      mem::drop(unsafe { Box::from_raw(previous) });
    }

    let previous = self.detour.swap(ptr::null_mut(), Ordering::Relaxed);
    if !previous.is_null() {
      unsafe { let _ = Box::from_raw(previous); };
    }
  }
}
```

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

### GenericDetour::disable

Source: https://docs.rs/retour/latest/retour/struct.GenericDetour.html

Disables the detour hook.

```APIDOC
## pub unsafe fn disable(&self) -> Result<()>

### Description
Disables the detour, restoring the original behavior of the target function.
```
Tokens:
Raw