mirror of
https://github.com/facebookexperimental/reverie.git
synced 2024-11-28 01:06:45 +00:00
531faf7a34
Summary: * Adds a `README.md` file. * Adds optional features to enable memory access and the async API. `safeptrace` depends on `reverie-process` and `reverie-memory`, so those will need to be published as crates too. Reviewed By: VladimirMakaev Differential Revision: D44386559 fbshipit-source-id: e74c55d5d26239aa09aedac130dca880eb5f1206
45 lines
1.4 KiB
Markdown
45 lines
1.4 KiB
Markdown
# 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"] }
|
|
```
|