> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rust Unsafe Function
An unsafe function in Rust is a function prefixed with the `unsafe` keyword, indicating that it possesses preconditions that the Rust compiler cannot statically verify. By marking a function as `unsafe`, the author establishes an API-level contract signaling that invoking the function requires the caller to manually uphold specific memory safety and soundness guarantees to prevent Undefined Behavior (UB).
## Syntax and Declaration
To declare an unsafe function, the `unsafe` keyword is placed immediately before the `fn` keyword.
```rust theme={"dark"}
unsafe fn perform_unchecked_operation(ptr: *const u8) -> u8 {
// The body of an unsafe function implicitly acts as an `unsafe` block
*ptr
}
```
## Invocation Rules
The Rust compiler enforces strict isolation for unsafe functions. You cannot call an unsafe function from normal, safe Rust code. It must be invoked within an explicit `unsafe` block or from within the body of another `unsafe` function. This forces the caller to explicitly acknowledge and accept the responsibility of the safety contract.
```rust theme={"dark"}
unsafe fn dangerous_call() {}
fn safe_context() {
// Compilation error: call to unsafe function requires unsafe function or block
// dangerous_call();
// Correct: The programmer asserts that preconditions are met
unsafe {
dangerous_call();
}
}
unsafe fn another_unsafe_context() {
// Valid: implicitly inside an unsafe scope
dangerous_call();
}
```
## The Unsafe Contract and Compiler Behavior
Marking a function as `unsafe` alters compiler behavior and developer responsibility in specific ways:
1. **Contract Definition, Not Suspension of Rules:** The `unsafe` keyword does **not** disable the borrow checker or Rust's standard type checking within the function body. Variables are still subject to ownership and lifetime rules.
2. **Implicit Unsafe Scope:** Historically, the entire body of an `unsafe fn` is treated as an `unsafe` block, allowing the use of unsafe operations (e.g., dereferencing raw pointers, accessing mutable statics, or calling other unsafe functions) without additional `unsafe` blocks. *(Note: The `unsafe_op_in_unsafe_fn` lint, standard in newer editions, requires explicit `unsafe` blocks even inside unsafe functions to narrow the scope of unsafe operations).*
3. **Foreign Function Interface (FFI):** Functions declared inside an `extern` block are implicitly unsafe to call. Because the Rust compiler cannot analyze the implementation of functions written in C, C++, or assembly, it assumes all FFI calls carry the risk of UB.
```rust theme={"dark"}
extern "C" {
// Implicitly unsafe to invoke
fn c_library_function(input: i32) -> i32;
}
fn call_ffi() {
unsafe {
c_library_function(42);
}
}
```
## Safety Documentation Convention
Because the compiler cannot enforce the preconditions of an unsafe function, standard Rust tooling (like `rustdoc`) and community conventions dictate that every `unsafe fn` must include a `# Safety` section in its documentation. This section explicitly details the invariants the caller must uphold to avoid UB.
```rust theme={"dark"}
/// Reads an integer from a raw pointer.
///
/// # Safety
///
/// The caller must guarantee that:
/// - `ptr` is not null.
/// - `ptr` is properly aligned for an `i32`.
/// - `ptr` points to initialized memory valid for reads.
pub unsafe fn read_int(ptr: *const i32) -> i32 {
*ptr
}
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
