Rust Reference ยท Keywords and Statements
The unsafe keyword
Reference for Rust unsafe: the five unsafe superpowers, unsafe blocks, unsafe fn and traits, unsafe impl, unsafe_op_in_unsafe_fn, safety comments and what stays checked.
unsafe marks code where you, not the compiler, guarantee that the rules of Rust are respected. It does not switch off the borrow checker or type checking; it unlocks a short list of operations whose safety the compiler cannot prove.
The keyword has two roles. On a block, function, trait or impl it means "I am relying on a contract here". On a function or trait declaration it means "callers (or implementors) must uphold a contract that is described in the documentation".
let x = 7; let p = &x as *const i32; let y = unsafe { *p };
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
unsafe { ... } // block unsafe fn name(...) { ... } // function with a contract unsafe trait Name { ... } // trait with a contract for implementors unsafe impl Name for Type { ... } // implementor accepts the contract unsafe extern "C" { ... } // foreign block (2024 edition) #[unsafe(no_mangle)] // unsafe attributes (2024 edition)
The five operations allowed only in unsafe code: dereference a raw pointer, call an unsafe function or method, access or modify a mutable static, implement an unsafe trait, and access fields of a union.
Usage notes
- Keep blocks small and put a
// SAFETY:comment above each one that states why the contract holds. Document the contract of an unsafe function in a# Safetysection. unsafe_op_in_unsafe_fnis a warning in edition 2024: the body of anunsafe fnis not automatically an unsafe block.- Undefined behavior includes dangling or unaligned dereferences, data races, invalid values (a
boolthat is not 0/1), breaking aliasing rules and reading uninitialized memory. The program may misbehave anywhere, not only at the unsafe line. - Build safe wrappers. The goal is a safe API whose soundness depends on a small amount of unsafe code.
Vec,RcandMutexall work this way. SendandSyncare unsafe traits: implementing them manually asserts thread-safety the compiler cannot verify.- Mutable statics: taking a reference to a
static mutis denied by default since edition 2024 (static_mut_refs); use raw pointers with&raw mutor prefer atomics andMutex. - Tools: run tests under Miri to detect many kinds of undefined behavior in unsafe code. Miri output is read-only here; see the lesson below.
Related
extern,union,static,trait- Lessons: Unsafe Rust, Auditing unsafe and Miri, Send and Sync