reverie/safeptrace/README.md

A safe ptrace interface

This crate provides a safe and Rustic alternative to the infamous ptrace API. There are many extremely subtle aspects of the raw ptrace API and this crate helps avoid common pitfalls.

Note that this library is still rather low-level and does not claim to solve all your ptrace problems. You have been warned!

Features

• Ergonomic interface that provides a state machine for ptrace states. This avoids the infamous ESRCH errors that can happen when you use the ptrace API incorrectly.
• Provides an interface to read/write guest's memory (see "memory" feature flag).
• Provides an optional and semi-experimental async interface, which can be used with tokio (see "notifier" feature).

Usage

Add this to your Cargo.toml file:

safeptrace = "0.1"

Feature Flags

"memory" (off by default)

Provides access to the guest's memory. Memory can only be safely accessed when the guest is in a stopped state, thus the MemoryAccess trait is only implemented for the Stopped type.

"notifier" (off by default)

Provides an async interface for ptrace using notifier threads. This is semi-experimental, but testing shows that it has very good performance. It works by spawning a separate thread for each thread being traced, waiting for ptrace events in a loop. Thus, there will be 1 thread per guest thread.

Use with:

safeptrace = { version = "0.1", features = ["async"] }