Skip to content
A `#[safe]` attribute for explaining why `unsafe { ... }` is OK.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Added a note on which nightly features are required and why Jun 8, 2019
tests Added examples to the README (and regression tests for them) Jun 17, 2019
.gitignore Created a no-op #[safe] attribute Jun 7, 2019
.travis.yml We use nightly features, it doesn't make sense to have a stable minim… Jun 16, 2019
Cargo.toml (cargo-release) start next development iteration 0.1.0 Jun 17, 2019
LICENSE_APACHE Switched to a MIT/Apache-2.0 dual license Jun 16, 2019
LICENSE_MIT Switched to a MIT/Apache-2.0 dual license Jun 16, 2019
README.md
README.md.skt.md Added examples to the README (and regression tests for them) Jun 17, 2019
build.rs Added examples to the README (and regression tests for them) Jun 17, 2019

README.md

rust-safe

Build Status Crates.io Docs.rs

A #[safe] attribute for explaining why unsafe { ... } is OK.

Getting Started

This crate is mainly meant as a way to document your unsafe code. The simplest usage is to use a #[safe(reason = "...")] attribute:

#[safe(reason = "All zeroes is a valid bit pattern for a `u8` array")]
unsafe {
  let buffer: [u8; 32] = std::mem::zeroed();
}

You can also provide pre- and post-conditions with the requires and ensures arguments.

const HELLO_WORLD: &[u8] = b"Hello, World!\0";

let mut buffer: *mut c_char = std::ptr::null_mut();

#[safe(reason = "This is a valid way to initialize a C-style string",
        requires = "buffer.is_null()",
        ensures = "libc::strlen(buffer) == HELLO_WORLD.len()-1")]
unsafe {
  buffer = libc::malloc(42) as *mut c_char;

  libc::strcpy(buffer, HELLO_WORLD.as_ptr() as *const c_char);
}

Nightly Rust

Unfortunately, you'll need to be using nightly when this custom attribute is applied to an expression. These feature flags are:

  • stmt_expr_attributes
  • proc_macro_hygiene

For more discussion, see #3.

License

This project is licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

You can’t perform that action at this time.