From 7b5e847ae5b8d2da27455ffd3fe55cc2e2dccf6d Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Thu, 30 Jan 2025 22:15:26 +0100 Subject: [PATCH 1/2] exit: document interaction with C --- library/std/src/env.rs | 2 +- library/std/src/process.rs | 34 +++++++++++++++++++++++++++++++--- 2 files changed, 32 insertions(+), 4 deletions(-) diff --git a/library/std/src/env.rs b/library/std/src/env.rs index 4a071b4e1fa..c0415eafb05 100644 --- a/library/std/src/env.rs +++ b/library/std/src/env.rs @@ -330,7 +330,7 @@ impl Error for VarError { /// /// Discussion of this unsafety on Unix may be found in: /// -/// - [Austin Group Bugzilla](https://austingroupbugs.net/view.php?id=188) +/// - [Austin Group Bugzilla (for POSIX)](https://austingroupbugs.net/view.php?id=188) /// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2) /// /// To pass an environment variable to a child process, you can instead use [`Command::env`]. diff --git a/library/std/src/process.rs b/library/std/src/process.rs index bdd4844b651..2ae93d84ba4 100644 --- a/library/std/src/process.rs +++ b/library/std/src/process.rs @@ -2003,9 +2003,9 @@ impl ExitCode { /// /// Note that this has the same caveats as [`process::exit()`][exit], namely that this function /// terminates the process immediately, so no destructors on the current stack or any other - /// thread's stack will be run. If a clean shutdown is needed, it is recommended to simply - /// return this ExitCode from the `main` function, as demonstrated in the [type - /// documentation](#examples). + /// thread's stack will be run. Also see those docs for some important notes on interop with C + /// code. If a clean shutdown is needed, it is recommended to simply return this ExitCode from + /// the `main` function, as demonstrated in the [type documentation](#examples). /// /// # Differences from `process::exit()` /// @@ -2297,6 +2297,34 @@ impl Child { /// considered undesirable. Note that returning from `main` also calls `exit`, so making `exit` an /// unsafe operation is not an option.) /// +/// ## Safe interop with C code +/// +/// This function is safe to call as long as `exit` is only ever invoked from Rust. However, on some +/// platforms this function is implemented by calling the C function [`exit`][C-exit]. As of C23, +/// the C standard does not permit multiple threads to call `exit` concurrently. Rust mitigates this +/// with a lock, but if C code calls `exit`, that can still cause undefined behavior. Note that +/// returning from `main` is equivalent to calling `exit`. +/// +/// Therefore, it is undefined behavior to have two concurrent threads perform the following +/// without synchronization: +/// - One thread calls Rust's `exit` function or returns from Rust's `main` function +/// - Another thread calls the C function `exit` or `quick_exit`, or returns from C's `main` function +/// +/// Note that if a binary contains multiple copies of the Rust runtime (e.g., when combining +/// multiple `cdylib` or `staticlib`), they each have their own separate lock, so from the +/// perspective of code running in one of the Rust runtimes, the "outside" Rust code is basically C +/// code, and concurrent `exit` again causes undefined behavior. +/// +/// Individual C implementations might provide more guarantees than the standard and permit concurrent +/// calls to `exit`; consult the documentation of your C implementation for details. +/// +/// For some of the on-going discussion to make `exit` thread-safe in C, see: +/// - [Rust issue #126600](https://github.com/rust-lang/rust/issues/126600) +/// - [Austin Group Bugzilla (for POSIX)](https://austingroupbugs.net/view.php?id=1845) +/// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=31997) +/// +/// [C-exit]: https://en.cppreference.com/w/c/program/exit +/// /// ## Platform-specific behavior /// /// **Unix**: On Unix-like platforms, it is unlikely that all 32 bits of `exit` From c133e22f7c3ba129185a500896fabb7befef7926 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Mon, 17 Mar 2025 17:56:22 +0100 Subject: [PATCH 2/2] move new section into platform-specific behavior, as it is unix-specific --- library/std/src/process.rs | 41 +++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/library/std/src/process.rs b/library/std/src/process.rs index 2ae93d84ba4..f1ee65e4648 100644 --- a/library/std/src/process.rs +++ b/library/std/src/process.rs @@ -2297,13 +2297,27 @@ impl Child { /// considered undesirable. Note that returning from `main` also calls `exit`, so making `exit` an /// unsafe operation is not an option.) /// -/// ## Safe interop with C code +/// ## Platform-specific behavior /// -/// This function is safe to call as long as `exit` is only ever invoked from Rust. However, on some -/// platforms this function is implemented by calling the C function [`exit`][C-exit]. As of C23, -/// the C standard does not permit multiple threads to call `exit` concurrently. Rust mitigates this -/// with a lock, but if C code calls `exit`, that can still cause undefined behavior. Note that -/// returning from `main` is equivalent to calling `exit`. +/// **Unix**: On Unix-like platforms, it is unlikely that all 32 bits of `exit` +/// will be visible to a parent process inspecting the exit code. On most +/// Unix-like platforms, only the eight least-significant bits are considered. +/// +/// For example, the exit code for this example will be `0` on Linux, but `256` +/// on Windows: +/// +/// ```no_run +/// use std::process; +/// +/// process::exit(0x0100); +/// ``` +/// +/// ### Safe interop with C code +/// +/// On Unix, this function is currently implemented using the `exit` C function [`exit`][C-exit]. As +/// of C23, the C standard does not permit multiple threads to call `exit` concurrently. Rust +/// mitigates this with a lock, but if C code calls `exit`, that can still cause undefined behavior. +/// Note that returning from `main` is equivalent to calling `exit`. /// /// Therefore, it is undefined behavior to have two concurrent threads perform the following /// without synchronization: @@ -2324,21 +2338,6 @@ impl Child { /// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=31997) /// /// [C-exit]: https://en.cppreference.com/w/c/program/exit -/// -/// ## Platform-specific behavior -/// -/// **Unix**: On Unix-like platforms, it is unlikely that all 32 bits of `exit` -/// will be visible to a parent process inspecting the exit code. On most -/// Unix-like platforms, only the eight least-significant bits are considered. -/// -/// For example, the exit code for this example will be `0` on Linux, but `256` -/// on Windows: -/// -/// ```no_run -/// use std::process; -/// -/// process::exit(0x0100); -/// ``` #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(not(test), rustc_diagnostic_item = "process_exit")] pub fn exit(code: i32) -> ! {