Skip to content
Branch: master
Find file History
ehuss and Gankro Fix some links.
rust-lang/rust does not allow bare directory links.
This unblocks updating the submodule.
Latest commit 341c221 Jun 18, 2019
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
img Add @aldeka's safe and unsafe Ferris Apr 14, 2017
README.md Fix some links. Jun 19, 2019
SUMMARY.md panic_implementation -> panic_handler; remove unstable features Sep 7, 2018
aliasing.md Fix double "the" in aliasing.md Dec 31, 2018
arc-and-mutex.md Port Nomicon to mdbook Mar 2, 2017
atomics.md fix typo Apr 14, 2017
beneath-std.md document #[panic_implementation] Jun 20, 2018
borrow-splitting.md Minor improvements Apr 7, 2019
casts.md Update description of float casts May 1, 2018
chapter_1.md Re-implement rustbook in terms of mdbook Mar 2, 2017
checked-uninit.md Minor improvements Apr 7, 2019
coercions.md Trivial updates to the coercions chapter Dec 29, 2018
concurrency.md Port Nomicon to mdbook Mar 2, 2017
constructors.md Port Nomicon to mdbook Mar 2, 2017
conversions.md Port Nomicon to mdbook Mar 2, 2017
data.md Fix link to type layout reference [skip ci] Jan 21, 2019
destructors.md Remove `unique` feature which doesn't exist anymore Aug 13, 2018
dot-operator.md Port Nomicon to mdbook Mar 2, 2017
drop-flags.md Add missing source code language hints in drop-flags and phantom-data. Nov 19, 2018
dropck.md dropck: The drop order is now defined Mar 25, 2019
exception-safety.md Update exception-safety.md Mar 2, 2017
exotic-sizes.md fixup Nov 23, 2018
ffi.md explain the empty type better, and explain to NOT use enums Aug 8, 2018
hrtb.md Port Nomicon to mdbook Mar 2, 2017
leaking.md Discuss thread::scoped API in past tense Oct 30, 2018
lifetime-elision.md Replace occurrences of `uint` with `usize` Apr 29, 2017
lifetime-mismatch.md Lifetimes: Updates to incorporate NLL Apr 24, 2019
lifetimes.md Lifetimes: Updates to incorporate NLL Apr 24, 2019
meet-safe-and-unsafe.md Cleanup the first chapter Aug 2, 2017
obrm.md Port Nomicon to mdbook Mar 2, 2017
other-reprs.md Merge pull request #112 from peter50216/patch-2 Feb 26, 2019
ownership.md Port Nomicon to mdbook Mar 2, 2017
panic-handler.md ignore tests Sep 7, 2018
phantom-data.md Merge pull request #131 from anderejd/master Apr 16, 2019
poisoning.md Port Nomicon to mdbook Mar 2, 2017
races.md Fix capitalization of Rust in races.md Nov 23, 2018
references.md rewrite references.md, splitting it out into aliasing.md Jun 11, 2017
repr-rust.md fixup Nov 23, 2018
safe-unsafe-meaning.md There are now 3 unsafe traits in rust Oct 29, 2018
send-and-sync.md fix typo, put quotes around Rc Jan 9, 2018
subtyping.md
transmutes.md Minor improvements Apr 7, 2019
unbounded-lifetimes.md Port Nomicon to mdbook Mar 2, 2017
unchecked-uninit.md Fix link to copy_nonoverlapping Apr 22, 2019
uninitialized.md Port Nomicon to mdbook Mar 2, 2017
unwinding.md Port Nomicon to mdbook Mar 2, 2017
vec-alloc.md Fix "illegal cpu instruction" in `vec-alloc.md` Apr 20, 2019
vec-dealloc.md use new Unique/heap APIs May 4, 2017
vec-deref.md use new Unique/heap APIs May 4, 2017
vec-drain.md Update vec-drain.md Nov 14, 2017
vec-final.md Use the alloc_layout_extra feature for Layout::array::<T> Nov 9, 2018
vec-insert-remove.md Port Nomicon to mdbook Mar 2, 2017
vec-into-iter.md use new Unique/heap APIs May 4, 2017
vec-layout.md Remove `unique` feature which doesn't exist anymore Aug 13, 2018
vec-push-pop.md Port Nomicon to mdbook Mar 2, 2017
vec-raw.md use new Unique/heap APIs May 4, 2017
vec-zsts.md use new Unique/heap APIs May 4, 2017
vec.md Port Nomicon to mdbook Mar 2, 2017
what-unsafe-does.md Updates to the data layout chapter Nov 11, 2018
working-with-unsafe.md Clarify "unsafe pollutes the module" Dec 24, 2017

README.md

The Rustonomicon

The Dark Arts of Unsafe Rust

THE KNOWLEDGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF UNLEASHING INDESCRIBABLE HORRORS THAT SHATTER YOUR PSYCHE AND SET YOUR MIND ADRIFT IN THE UNKNOWABLY INFINITE COSMOS.

The Rustonomicon digs into all the awful details that you need to understand when writing Unsafe Rust programs.

Should you wish a long and happy career of writing Rust programs, you should turn back now and forget you ever saw this book. It is not necessary. However if you intend to write unsafe code — or just want to dig into the guts of the language — this book contains lots of useful information.

Unlike The Rust Programming Language, we will be assuming considerable prior knowledge. In particular, you should be comfortable with basic systems programming and Rust. If you don't feel comfortable with these topics, you should consider reading The Book first. That said, we won't assume you have read it, and we will take care to occasionally give a refresher on the basics where appropriate. You can skip straight to this book if you want; just know that we won't be explaining everything from the ground up.

This book exists primarily as a high-level companion to The Reference. Where The Reference exists to detail the syntax and semantics of every part of the language, The Rustonomicon exists to describe how to use those pieces together, and the issues that you will have in doing so.

The Reference will tell you the syntax and semantics of references, destructors, and unwinding, but it won't tell you how combining them can lead to exception-safety issues, or how to deal with those issues.

It should be noted that when The Rustonomicon was originally written, The Reference was in a state of complete disrepair, and so many things that should have been covered by The Reference were originally only documented here. Since then, The Reference has been revitalized and is properly maintained, although it is still far from complete. In general, if the two documents disagree, The Reference should be assumed to be correct (it isn't yet considered normative, it's just better maintained).

Topics that are within the scope of this book include: the meaning of (un)safety, unsafe primitives provided by the language and standard library, techniques for creating safe abstractions with those unsafe primitives, subtyping and variance, exception-safety (panic/unwind-safety), working with uninitialized memory, type punning, concurrency, interoperating with other languages (FFI), optimization tricks, how constructs lower to compiler/OS/hardware primitives, how to not make the memory model people angry, how you're going to make the memory model people angry, and more.

The Rustonomicon is not a place to exhaustively describe the semantics and guarantees of every single API in the standard library, nor is it a place to exhaustively describe every feature of Rust.

You can’t perform that action at this time.