Skip to content

Commit

Permalink
Rewrite docs section about unsafe code
Browse files Browse the repository at this point in the history
This addresses feedback from #30
  • Loading branch information
cole14 committed Feb 9, 2023
1 parent dea6edf commit db0c393
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 26 deletions.
22 changes: 8 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,16 @@ The `elf` crate provides a pure-safe-rust interface for reading ELF object files

# Capabilities

### ✨ No unsafe code ✨
With memory safety a core goal, this crate contains zero unsafe code blocks, so you
can trust in rust's memory safety guarantees without also having to trust this
library developer as having truly been "right" in why some unsafe block was safe. 💃

Many of the other rust ELF parsers out there contain bits of unsafe code deep
down or in dependencies to reinterpret/transmute byte contents as structures in
order to drive zero-copy parsing. They're slick, and there's typically
appropriate checking to validate the assumptions to make that unsafe code work,
but nevertheless it introduces unsafe code blocks at the core of the parsers. This
crate strives to serve as an alternate implementation with zero unsafe blocks, while
also biasing for performance.
### ✨ Uses only safe interfaces ✨
With memory safety a core goal, this crate contains zero unsafe code blocks of
its own and only uses safe interface methods from core and std, so you can
trust in rust's memory safety guarantees without also having to trust this
library developer as having truly been "right" in why some unsafe block was
safe. 💃

Note: I'd love to see this crate be enhanced further once rust provides safe transmutes.

See <https://github.com/rust-lang/project-safe-transmute>
See: <https://github.com/rust-lang/project-safe-transmute>

### ✨ Fuzz Tested ✨
Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`).
Expand Down Expand Up @@ -140,4 +134,4 @@ let (sym_idx, sym) = hash_table.find(name, &dynsyms, &strtab)
assert_eq!(sym_idx, 2);
assert_eq!(strtab.get(sym.st_name as usize).unwrap(), "memset");
assert_eq!(sym, dynsyms.get(sym_idx).unwrap());
```
```
18 changes: 6 additions & 12 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,12 @@
//!
//! # Capabilities
//!
//! ### ✨ No unsafe code ✨
//! With memory safety a core goal, this crate contains zero unsafe code blocks, so you
//! can trust in rust's memory safety guarantees without also having to trust this
//! library developer as having truly been "right" in why some unsafe block was safe. 💃
//!
//! Many of the other rust ELF parsers out there contain bits of unsafe code deep
//! down or in dependencies to reinterpret/transmute byte contents as structures in
//! order to drive zero-copy parsing. They're slick, and there's typically
//! appropriate checking to validate the assumptions to make that unsafe code work,
//! but nevertheless it introduces unsafe code blocks at the core of the parsers. This
//! crate strives to serve as an alternate implementation with zero unsafe blocks, while
//! also biasing for performance.
//! ### ✨ Uses only safe interfaces ✨
//! With memory safety a core goal, this crate contains zero unsafe code blocks
//! of its own and only uses safe interface methods from core and std, so you can
//! trust in rust's memory safety guarantees without also having to trust this
//! library developer as having truly been "right" in why some unsafe block was
//! safe. 💃
//!
//! Note: I'd love to see this crate be enhanced further once rust provides safe transmutes.
//!
Expand Down

0 comments on commit db0c393

Please sign in to comment.