You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
nomicon/src
Linus Färnstrand 9f131b5b9c
Use just `std::_` instead of `::std::_`
5 years ago
..
img Add @aldeka's safe and unsafe Ferris 8 years ago
README.md Move word "reading" out of the link to "The Book" 5 years ago
SUMMARY.md panic_implementation -> panic_handler; remove unstable features 6 years ago
aliasing.md Fix double "the" in aliasing.md 6 years ago
arc-and-mutex.md Port Nomicon to mdbook 8 years ago
atomics.md Remove illegal space. 5 years ago
beneath-std.md document #[panic_implementation] 7 years ago
borrow-splitting.md Minor improvements 6 years ago
casts.md Update description of float casts 7 years ago
chapter_1.md Re-implement rustbook in terms of mdbook 8 years ago
checked-uninit.md Minor improvements 6 years ago
coercions.md Trivial updates to the coercions chapter 6 years ago
concurrency.md Port Nomicon to mdbook 8 years ago
constructors.md Port Nomicon to mdbook 8 years ago
conversions.md Port Nomicon to mdbook 8 years ago
data.md Fix link to type layout reference [skip ci] 6 years ago
destructors.md Rename `Alloc` to `AllocRef` 5 years ago
dot-operator.md Port Nomicon to mdbook 8 years ago
drop-flags.md Add missing source code language hints in drop-flags and phantom-data. 6 years ago
dropck.md Fix link to rfc1857 5 years ago
exception-safety.md Update exception-safety.md 8 years ago
exotic-sizes.md fix and expand what we say about ZST 5 years ago
ffi.md Fix example in FFI section Calling Rust from C 5 years ago
hrtb.md Port Nomicon to mdbook 8 years ago
leaking.md Discuss thread::scoped API in past tense 6 years ago
lifetime-elision.md Replace occurrences of `uint` with `usize` 8 years ago
lifetime-mismatch.md chore: Remove redundant Eq import 5 years ago
lifetimes.md Lifetimes: explain how to fix destructor example 5 years ago
meet-safe-and-unsafe.md Cleanup the first chapter 7 years ago
obrm.md Port Nomicon to mdbook 8 years ago
other-reprs.md Update unsafe-code-guidelines link 5 years ago
ownership.md Port Nomicon to mdbook 8 years ago
panic-handler.md ignore tests 6 years ago
phantom-data.md Remove mention of contravariance possibly getting scrapped 5 years ago
poisoning.md Port Nomicon to mdbook 8 years ago
races.md Fix capitalization of Rust in races.md 6 years ago
references.md rewrite references.md, splitting it out into aliasing.md 8 years ago
repr-rust.md fixup 6 years ago
safe-unsafe-meaning.md mention soundness 5 years ago
send-and-sync.md Fix negative_impls feature. 5 years ago
subtyping.md follow-up to review from Centril 5 years ago
transmutes.md Fix transmute_copy link 5 years ago
unbounded-lifetimes.md Port Nomicon to mdbook 8 years ago
unchecked-uninit.md fix links for copy, copy_nonoverlapping 5 years ago
uninitialized.md Port Nomicon to mdbook 8 years ago
unwinding.md Update unwinding.md 5 years ago
vec-alloc.md Use isize::MAX directly on type instead of module 5 years ago
vec-dealloc.md use new Unique/heap APIs 8 years ago
vec-deref.md Use just `std::_` instead of `::std::_` 5 years ago
vec-drain.md Update vec-drain.md 7 years ago
vec-final.md Use just `std::_` instead of `::std::_` 5 years ago
vec-insert-remove.md Port Nomicon to mdbook 8 years ago
vec-into-iter.md use new Unique/heap APIs 8 years ago
vec-layout.md Remove `unique` feature which doesn't exist anymore 6 years ago
vec-push-pop.md Port Nomicon to mdbook 8 years ago
vec-raw.md use new Unique/heap APIs 8 years ago
vec-zsts.md use new Unique/heap APIs 8 years ago
vec.md Fix typo `str::mem` to `std::mem` 5 years ago
what-unsafe-does.md Update src/what-unsafe-does.md 5 years ago
working-with-unsafe.md use sound/unsound terminology 5 years ago

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.