You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/behavior-considered-undefined.md
+4-10
Original file line number
Diff line number
Diff line change
@@ -77,9 +77,7 @@ r[undefined.target-feature]
77
77
does not support (see [`target_feature`]), *except* if the platform explicitly documents this to be safe.
78
78
79
79
r[undefined.call]
80
-
* Calling a function with the wrong [call ABI][abi], or unwinding past a stack
81
-
frame that does not allow unwinding (e.g. by calling a `"C-unwind"` function
82
-
imported or transmuted as a `"C"` function or function pointer).
80
+
* Calling a function with the wrong [call ABI][abi], or unwinding past a stack frame that does not allow unwinding (e.g. by calling a `"C-unwind"` function imported or transmuted as a `"C"` function or function pointer).
83
81
84
82
r[undefined.invalid]
85
83
* Producing an [invalid value][invalid-values]. "Producing" a
cast, e.g. by doing raw pointer casts or using a union.
100
98
101
99
r[undefined.runtime]
102
-
* Violating assumptions of the Rust runtime. Most assumptions of the Rust
103
-
runtime are currently not explicitly documented.
104
-
* For assumptions specifically related to unwinding, see the [panic
105
-
documentation][unwinding-ffi].
106
-
* The runtime assumes that a Rust stack frame is not deallocated without
107
-
executing destructors for local variables owned by the stack frame. This assumption
108
-
can be violated by C functions like `longjmp`.
100
+
* Violating assumptions of the Rust runtime. Most assumptions of the Rust runtime are currently not explicitly documented.
101
+
* For assumptions specifically related to unwinding, see the [panic documentation][unwinding-ffi].
102
+
* The runtime assumes that a Rust stack frame is not deallocated without executing destructors for local variables owned by the stack frame. This assumption can be violated by C functions like `longjmp`.
109
103
110
104
> **Note**: Undefined behavior affects the entire program. For example, calling
111
105
> a function in C that exhibits undefined behavior of C means your entire
Copy file name to clipboardExpand all lines: src/crates-and-source-files.md
+2-9
Original file line number
Diff line number
Diff line change
@@ -125,21 +125,14 @@ use foo::bar as main;
125
125
r[crate.uncaught-foreign-unwinding]
126
126
### Uncaught foreign unwinding
127
127
128
-
When a "foreign" unwind (e.g. an exception thrown from C++ code, or a `panic!`
129
-
in Rust code using a different panic handler) propagates beyond
130
-
the `main` function, the process will be safely terminated. This may
131
-
take the form of an abort, in which case it is not guaranteed that any `Drop`
132
-
calls will be executed, and the error output may be less informative than if the
133
-
runtime had been terminated by a "native" Rust `panic`.
128
+
When a "foreign" unwind (e.g. an exception thrown from C++ code, or a `panic!` in Rust code using a different panic handler) propagates beyond the `main` function, the process will be safely terminated. This may take the form of an abort, in which case it is not guaranteed that any `Drop` calls will be executed, and the error output may be less informative than if the runtime had been terminated by a "native" Rust `panic`.
134
129
135
130
For more information, see the [panic documentation][panic-docs].
136
131
137
132
r[crate.no_main]
138
133
### The `no_main` attribute
139
134
140
-
The *`no_main`[attribute]* may be applied at the crate level to disable
141
-
emitting the `main` symbol for an executable binary. This is useful when some
142
-
other object being linked to defines `main`.
135
+
The *`no_main`[attribute]* may be applied at the crate level to disable emitting the `main` symbol for an executable binary. This is useful when some other object being linked to defines `main`.
Copy file name to clipboardExpand all lines: src/destructors.md
+4-11
Original file line number
Diff line number
Diff line change
@@ -274,8 +274,7 @@ Temporaries are also created to hold the result of operands to an expression
274
274
while the other operands are evaluated. The temporaries are associated to the
275
275
scope of the expression with that operand. Since the temporaries are moved from
276
276
once the expression is evaluated, dropping them has no effect unless one of the
277
-
operands to an expression breaks out of the expression, returns, or
278
-
[panics][panic].
277
+
operands to an expression breaks out of the expression, returns, or [panics][panic].
279
278
280
279
```rust
281
280
# structPrintOnDrop(&'staticstr);
@@ -439,17 +438,11 @@ variable or field from being dropped automatically.
439
438
r[destructors.process-termination]
440
439
### Process termination without unwinding
441
440
442
-
There are some ways to terminate the process without [unwinding], in which case
443
-
destructors will not be run.
441
+
There are some ways to terminate the process without [unwinding], in which case destructors will not be run.
444
442
445
-
The standard library provides [`std::process::exit`] and
446
-
[`std::process::abort`] to do this explicitly. Additionally, if the
447
-
[panic handler][panic.panic_handler.std] is set to `abort`, panicking will always terminate the process
448
-
without destructors being run.
443
+
The standard library provides [`std::process::exit`] and [`std::process::abort`] to do this explicitly. Additionally, if the [panic handler][panic.panic_handler.std] is set to `abort`, panicking will always terminate the process without destructors being run.
449
444
450
-
There is one additional case to be aware of: when a panic reaches a
451
-
[non-unwinding ABI boundary], either no destructors will run, or all
452
-
destructors up until the ABI boundary will run.
445
+
There is one additional case to be aware of: when a panic reaches a [non-unwinding ABI boundary], either no destructors will run, or all destructors up until the ABI boundary will run.
Copy file name to clipboardExpand all lines: src/items/external-blocks.md
+2-5
Original file line number
Diff line number
Diff line change
@@ -122,9 +122,7 @@ r[items.extern.abi.system]
122
122
API itself
123
123
124
124
r[items.extern.abi.unwind]
125
-
*`extern "C-unwind"` and `extern "system-unwind"` -- identical to `"C"` and
126
-
`"system"`, respectively, but with [different behavior][unwind-behavior] when
127
-
the callee unwinds (by panicking or throwing a C++ style exception).
125
+
*`extern "C-unwind"` and `extern "system-unwind"` -- identical to `"C"` and `"system"`, respectively, but with [different behavior][unwind-behavior] when the callee unwinds (by panicking or throwing a C++ style exception).
128
126
129
127
r[items.extern.abi.platform]
130
128
There are also some platform-specific ABI strings:
@@ -156,8 +154,7 @@ r[items.extern.abi.efiapi]
156
154
*`unsafe extern "efiapi"` -- The ABI used for [UEFI] functions.
157
155
158
156
r[items.extern.abi.platform-unwind-variants]
159
-
Like `"C"` and `"system"`, most platform-specific ABI strings also have a
160
-
[corresponding `-unwind` variant][unwind-behavior]; specifically, these are:
157
+
Like `"C"` and `"system"`, most platform-specific ABI strings also have a [corresponding `-unwind` variant][unwind-behavior]; specifically, these are:
Copy file name to clipboardExpand all lines: src/items/functions.md
+11-33
Original file line number
Diff line number
Diff line change
@@ -257,34 +257,16 @@ r[items.fn.extern.unwind]
257
257
### Unwinding
258
258
259
259
r[items.fn.extern.unwind.intro]
260
-
Most ABI strings come in two variants, one with an `-unwind` suffix and one without.
261
-
The `Rust` ABI always permits unwinding, so there is no `Rust-unwind` ABI. The
262
-
choice of ABI, together with the runtime [panic handler], determines
263
-
the behavior when unwinding out of a function.
260
+
Most ABI strings come in two variants, one with an `-unwind` suffix and one without. The `Rust` ABI always permits unwinding, so there is no `Rust-unwind` ABI. The choice of ABI, together with the runtime [panic handler], determines the behavior when unwinding out of a function.
264
261
265
262
r[items.fn.extern.unwind.behavior]
266
-
The table below indicates the behavior of an unwinding operation reaching each
267
-
type of ABI boundary (function declaration or definition using the
268
-
corresponding ABI string). Note that the Rust runtime is not affected by, and
269
-
cannot have an effect on, any unwinding that occurs entirely within another
270
-
language's runtime, that is, unwinds that are thrown and caught without
271
-
reaching a Rust ABI boundary.
272
-
273
-
The `panic`-unwind column refers to [panicking] via the `panic!` macro and
274
-
similar standard library mechanisms, as well as to any other Rust operations
275
-
that cause a panic, such as out-of-bounds array indexing or integer overflow.
276
-
277
-
The "unwinding" ABI category refers to `"Rust"` (the implicit ABI of Rust
278
-
functions not marked `extern`), `"C-unwind"`, and any other ABI with `-unwind`
279
-
in its name. The "non-unwinding" ABI category refers to all other ABI strings,
280
-
including `"C"` and `"stdcall"`.
281
-
282
-
Native unwinding is defined per-target. On targets that support throwing and
283
-
catching C++ exceptions, it refers to the mechanism used to implement this
284
-
feature. Some platforms implement a form of unwinding referred to as ["forced
285
-
unwinding"][forced-unwinding]; `longjmp` on Windows and `pthread_exit` in
286
-
`glibc` are implemented this way. Forced unwinding is explicitly excluded
287
-
from the "Native unwind" column in the table.
263
+
The table below indicates the behavior of an unwinding operation reaching each type of ABI boundary (function declaration or definition using the corresponding ABI string). Note that the Rust runtime is not affected by, and cannot have an effect on, any unwinding that occurs entirely within another language's runtime, that is, unwinds that are thrown and caught without reaching a Rust ABI boundary.
264
+
265
+
The `panic`-unwind column refers to [panicking] via the `panic!` macro and similar standard library mechanisms, as well as to any other Rust operations that cause a panic, such as out-of-bounds array indexing or integer overflow.
266
+
267
+
The "unwinding" ABI category refers to `"Rust"` (the implicit ABI of Rust functions not marked `extern`), `"C-unwind"`, and any other ABI with `-unwind` in its name. The "non-unwinding" ABI category refers to all other ABI strings, including `"C"` and `"stdcall"`.
268
+
269
+
Native unwinding is defined per-target. On targets that support throwing and catching C++ exceptions, it refers to the mechanism used to implement this feature. Some platforms implement a form of unwinding referred to as ["forced unwinding"][forced-unwinding]; `longjmp` on Windows and `pthread_exit` in `glibc` are implemented this way. Forced unwinding is explicitly excluded from the "Native unwind" column in the table.
@@ -294,11 +276,9 @@ from the "Native unwind" column in the table.
294
276
|`panic=abort`| non-unwinding |`panic` aborts without unwinding |[undefined behavior]|
295
277
296
278
r[items.fn.extern.abort]
297
-
With `panic=unwind`, when a `panic` is turned into an abort by a non-unwinding ABI boundary, either no destructors (`Drop` calls) will run, or all destructors
298
-
up until the ABI boundary will run. It is unspecified which of those two behaviors will happen.
279
+
With `panic=unwind`, when a `panic` is turned into an abort by a non-unwinding ABI boundary, either no destructors (`Drop` calls) will run, or all destructors up until the ABI boundary will run. It is unspecified which of those two behaviors will happen.
299
280
300
-
For other considerations and limitations regarding unwinding across FFI
301
-
boundaries, see the [relevant section in the Panic documentation][panic-ffi].
281
+
For other considerations and limitations regarding unwinding across FFI boundaries, see the [relevant section in the Panic documentation][panic-ffi].
Functions qualified with the `const` keyword are [const functions], as are
314
-
[tuple struct] and [tuple variant] constructors. _Const functions_ can be
315
-
called from within [const contexts].
293
+
Functions qualified with the `const` keyword are [const functions], as are [tuple struct] and [tuple variant] constructors. _Const functions_ can be called from within [const contexts].
316
294
317
295
r[items.fn.const.extern]
318
296
Const functions may use the [`extern`] function qualifier.
Copy file name to clipboardExpand all lines: src/linkage.md
+7-19
Original file line number
Diff line number
Diff line change
@@ -272,8 +272,7 @@ binary link:
272
272
Passing `rlib`s directly into your foreign linker is currently unsupported.
273
273
274
274
> [!NOTE]
275
-
> Rust code compiled or linked with a different instance of the Rust runtime counts as a
276
-
> "foreign code" for the purpose of this section.
275
+
> Rust code compiled or linked with a different instance of the Rust runtime counts as "foreign code" for the purpose of this section.
277
276
278
277
r[link.unwinding]
279
278
### Prohibited linkage and unwinding
@@ -284,31 +283,20 @@ Panic unwinding can only be used if the binary is built consistently according t
284
283
r[link.unwinding.potential]
285
284
A Rust artifact is called *potentially unwinding* if any of the following conditions is met:
286
285
- The artifact uses the [`unwind` panic handler][panic.panic_handler].
287
-
- The artifact contains a crate built with the `unwind`[panic strategy] that makes a call
288
-
to a function using a `-unwind` ABI.
289
-
- The artifact makes a `"Rust"` ABI call to code running in another Rust
290
-
artifact that has a separate copy of the Rust runtime, and that other artifact is
291
-
potentially unwinding.
286
+
- The artifact contains a crate built with the `unwind`[panic strategy] that makes a call to a function using a `-unwind` ABI.
287
+
- The artifact makes a `"Rust"` ABI call to code running in another Rust artifact that has a separate copy of the Rust runtime, and that other artifact is potentially unwinding.
292
288
293
289
> [!NOTE]
294
-
> This definition captures whether a `"Rust"` ABI call inside a Rust artifact can ever
295
-
> unwind.
290
+
> This definition captures whether a `"Rust"` ABI call inside a Rust artifact can ever unwind.
296
291
297
292
r[link.unwinding.prohibited]
298
-
If a Rust artifact is potentially unwinding, then all its crates must be built with the `unwind`[panic strategy].
299
-
Otherwise, unwinding can cause undefined behavior.
293
+
If a Rust artifact is potentially unwinding, then all its crates must be built with the `unwind`[panic strategy]. Otherwise, unwinding can cause undefined behavior.
300
294
301
295
> [!NOTE]
302
-
> If you are using `rustc` to link, these rules are enforced automatically.
303
-
> If you are *not* using `rustc` to link, you must take care to ensure that unwinding is handled consistently across the entire binary. Linking without `rustc` includes using `dlopen` or similar facilities where linking is done by the system runtime without `rustc` being involved.
304
-
>
305
-
> This can only happen when mixing code with different [`-C panic`] flags, so most users do not have to be concerned about this.
296
+
> If you are using `rustc` to link, these rules are enforced automatically. If you are *not* using `rustc` to link, you must take care to ensure that unwinding is handled consistently across the entire binary. Linking without `rustc` includes using `dlopen` or similar facilities where linking is done by the system runtime without `rustc` being involved. This can only happen when mixing code with different [`-C panic`] flags, so most users do not have to be concerned about this.
306
297
307
298
> [!NOTE]
308
-
> To guarantee that a library will be sound (and linkable with `rustc`)
309
-
> regardless of the panic runtime used at link-time, the [`ffi_unwind_calls` lint]
310
-
> may be used. The lint flags any calls to `-unwind` foreign functions or
311
-
> function pointers.
299
+
> To guarantee that a library will be sound (and linkable with `rustc`) regardless of the panic runtime used at link-time, the [`ffi_unwind_calls` lint] may be used. The lint flags any calls to `-unwind` foreign functions or function pointers.
0 commit comments