Skip to content

Commit 849d3bf

Browse files
committed
define UB and give some context to soundness
1 parent f7a0a3a commit 849d3bf

File tree

1 file changed

+19
-1
lines changed

1 file changed

+19
-1
lines changed

Diff for: reference/src/glossary.md

+19-1
Original file line numberDiff line numberDiff line change
@@ -146,10 +146,28 @@ Moreover, such unsafe code must not return a non-UTF-8 string to the "outside" o
146146
To summarize: *Data must always be valid, but it only must be safe in safe code.*
147147
For some more information, see [this blog post](https://www.ralfj.de/blog/2018/08/22/two-kinds-of-invariants.html).
148148

149+
#### Undefined Behavior
150+
[ub]: #undefined-behavior
151+
152+
*Undefined Behavior* is a concept of the contract between the Rust programmer and the compiler:
153+
The programmer promises that the code exhibits no undefined behavior.
154+
In return, the compiler promises to compile the code in a way that the final program does on the real hardware what the source program does according to the Rust Abstract Machine.
155+
If it turns out the program *does* have undefined behavior, the contract is void, and the program produced by the compiler is essentially garbage (in particular, it is not bound by any specification; the program does not even have to be well-formed executable code).
156+
157+
In Rust, the [Nomicon](https://doc.rust-lang.org/nomicon/what-unsafe-does.html) and the [Reference](https://doc.rust-lang.org/reference/behavior-considered-undefined.html) both have a list of behavior that the language considers undefined.
158+
Rust promises that safe code cannot cause Undefined Behavior---it takes the burden of this contract on itself.
159+
For unsafe code, however, the burden is still on the programmer.
160+
161+
Also see: [Soundness][soundness].
162+
149163
#### Soundness (of code / of a library)
150164
[soundness]: #soundness-of-code--of-a-library
151165

152-
We say that a library (or an individual function) is *sound* if it is impossible for safe code to cause Undefined Behavior using its public API.
166+
*Soundness* is a type system concept (actually originating from the study of logics) and means that the type system is "correct" in the sense that well-typed programs actually have the desired properties.
167+
For Rust, this means well-typed programs cannot cause [Undefined Behavior][ub].
168+
This promise only extends to safe code however; for `unsafe` code, it is up to the programmer to uphold this contract.
169+
170+
Accordingly, we say that a library (or an individual function) is *sound* if it is impossible for safe code to cause Undefined Behavior using its public API.
153171
Conversely, the library/function is *unsound* if safe code *can* cause Undefined Behavior.
154172

155173
#### Layout

0 commit comments

Comments
 (0)