From ac4b87f9b7ec05a1133ce77734387b30e5e5bf92 Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Wed, 4 Feb 2026 14:56:44 +0800 Subject: [PATCH 1/7] Crate a new project goal: standardize-std-unsafe --- src/2026/standardize-std-unsafe.md | 53 ++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 src/2026/standardize-std-unsafe.md diff --git a/src/2026/standardize-std-unsafe.md b/src/2026/standardize-std-unsafe.md new file mode 100644 index 00000000..65c511dc --- /dev/null +++ b/src/2026/standardize-std-unsafe.md @@ -0,0 +1,53 @@ +# Standardizing Unsafe Code Usage in the Rust Standard Library + +| Metadata | | +| :--------------- | -------------------------------------------------------------------------------- | +| Point of contact | @hxuhack | +| Status | Proposed | +| Tracking issue | TBD | +| Zulip channel | N/A | + +## Summary + +To establish explicit conventions for unsafe code usage and documentation by reviewing existing practices in the Rust standard library, and to audit the library against these conventions to identify and correct inconsistencies. + +## Motivation + +### The status quo + +The Rust standard library does not currently provide systematic guidelines for unsafe code usage and documentation. +While existing [Unsafe Code Guidelines](https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#soundness-of-code--of-a-library) establishes an essential baseline, it is not sufficiently detailed to guide the practical adoption of unsafe code, particularly with respect to visibility-related soundness choices and the documentation of safety invariants. + +In practice, the opsem team and standard library team have developed a shared understanding and informal conventions about unsafe code usage through ongoing development. +These conventions are important, but they have not yet been systematically documented. +As the standard library continues to grow in size and complexity, documenting these conventions becomes increasingly important for guiding contributors in writing and reviewing unsafe code correctly. + +### What we propose to do about it + +- Document the conventions about unsafe code usage as a Rust Safety Standard in collaboration with the opsem team and the standard library team, and iteratively refine the standard based on feedback and experience (see a draft [here](https://internals.rust-lang.org/t/pre-rfc-rust-safety-standard/23963)). The standard focuses on the following two aspects: + + * **Code safety criteria**: criteria for marking functions or other program components as safe or unsafe. + + * **Safety documentation**: the information that should be provided at unsafe code definition sites, use sites, and struct definition sites where type invariants are required. + +- Review unsafe code usage in the Rust standard library and identify and correct inconsistencies with the standard. + + +### Work items over the next year + +| Task | Owner(s) | Notes | +| ----------- | -------- | ----- | +| Draft and refine the safety standard | @hxuhack | | +| Audit standard library | @hxuhack, @DiuDiu777 | | + +### The "shiny future" + +- The standard can also be adopted by downstream Rust crates, helping to promote consistent and sound unsafe code practices across the ecosystem. +- It can serve as a basis for future attribute-based safety documentation and checking, as proposed in [RFC 3842](https://github.com/rust-lang/rfcs/pull/3842). + +## Team asks + +| Team | Support level | Notes | +| ---------- | ------------- | --------------------------------------- | +| [libs] | Small | Review the standard document and provide feedback, examine any issues identified, and review related pull requests | +| [opsem] | Small | Review the standard document and provide feedback, examine any issues identified, and review related pull requests | From f0f7e607c5b95fd6b618982b031a7ecd215c9618 Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Wed, 4 Feb 2026 22:44:53 +0800 Subject: [PATCH 2/7] Update tracking issue in standardize-std-unsafe.md Removed tracking issue placeholder from metadata. --- src/2026/standardize-std-unsafe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2026/standardize-std-unsafe.md b/src/2026/standardize-std-unsafe.md index 65c511dc..8618d5a9 100644 --- a/src/2026/standardize-std-unsafe.md +++ b/src/2026/standardize-std-unsafe.md @@ -4,7 +4,7 @@ | :--------------- | -------------------------------------------------------------------------------- | | Point of contact | @hxuhack | | Status | Proposed | -| Tracking issue | TBD | +| Tracking issue | | | Zulip channel | N/A | ## Summary From 1a70635253a3dcd7d92f098f6f857a99bf05dd61 Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Fri, 6 Feb 2026 17:46:57 +0800 Subject: [PATCH 3/7] Involving Rust for Linux in the loop --- src/2026/standardize-std-unsafe.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/2026/standardize-std-unsafe.md b/src/2026/standardize-std-unsafe.md index 8618d5a9..0cb0b674 100644 --- a/src/2026/standardize-std-unsafe.md +++ b/src/2026/standardize-std-unsafe.md @@ -22,6 +22,8 @@ In practice, the opsem team and standard library team have developed a shared un These conventions are important, but they have not yet been systematically documented. As the standard library continues to grow in size and complexity, documenting these conventions becomes increasingly important for guiding contributors in writing and reviewing unsafe code correctly. +In addition, Rust for Linux has a similar requirement and has already drafted a [document](https://lore.kernel.org/rust-for-linux/20240717221133.459589-1-benno.lossin@proton.me/) to guide unsafe code usage in the project. + ### What we propose to do about it - Document the conventions about unsafe code usage as a Rust Safety Standard in collaboration with the opsem team and the standard library team, and iteratively refine the standard based on feedback and experience (see a draft [here](https://internals.rust-lang.org/t/pre-rfc-rust-safety-standard/23963)). The standard focuses on the following two aspects: @@ -30,7 +32,7 @@ As the standard library continues to grow in size and complexity, documenting th * **Safety documentation**: the information that should be provided at unsafe code definition sites, use sites, and struct definition sites where type invariants are required. -- Review unsafe code usage in the Rust standard library and identify and correct inconsistencies with the standard. +- Review unsafe code usage in the Rust standard library as well as Rust for Linux, and identify and correct inconsistencies with the standard. ### Work items over the next year @@ -39,6 +41,7 @@ As the standard library continues to grow in size and complexity, documenting th | ----------- | -------- | ----- | | Draft and refine the safety standard | @hxuhack | | | Audit standard library | @hxuhack, @DiuDiu777 | | +| Audit Rust for Linux | @hxuhack, @yilin0518 | | ### The "shiny future" From afd17babdb626bb54152265103fdea0463ec717d Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Fri, 13 Feb 2026 23:10:36 +0800 Subject: [PATCH 4/7] Refine the goal to make it concise and concrete. --- src/2026/improve-std-unsafe.md | 126 +++++++++++++++++++++++++++++ src/2026/standardize-std-unsafe.md | 56 ------------- 2 files changed, 126 insertions(+), 56 deletions(-) create mode 100644 src/2026/improve-std-unsafe.md delete mode 100644 src/2026/standardize-std-unsafe.md diff --git a/src/2026/improve-std-unsafe.md b/src/2026/improve-std-unsafe.md new file mode 100644 index 00000000..b3ccfbbd --- /dev/null +++ b/src/2026/improve-std-unsafe.md @@ -0,0 +1,126 @@ +# Improving Unsafe Code Documentation in the Rust Standard Library + +| Metadata | | +| :--------------- | -------------------------------------------------------------------------------- | +| Point of contact | @hxuhack | +| Status | Proposed | +| Tracking issue | | +| Zulip channel | N/A | + +## Summary + +Review unsafe code documentation in the Rust standard library, identify inconsistencies, and fix them. Based on the lessons learned during this review process, we also aim to establish explicit conventions for code safety reasoning and unsafe code documentation. + +## Motivation + +### The status quo + +The Rust standard library provides many unsafe APIs accompanied by safety documentation. +While most unsafe APIs include safety sections, the quality of these documents does not always match the rigor of the code itself. +Inconsistencies exist, such as missing safety sections (e.g., [#138309](https://github.com/rust-lang/rust/pull/138309), [#146925](https://github.com/rust-lang/rust/pull/146925)) and incomplete safety properties (e.g., [#134953](https://github.com/rust-lang/rust/pull/134953), [#134496](https://github.com/rust-lang/rust/pull/134496), [#135009](https://github.com/rust-lang/rust/pull/135009)). A systematic review is therefore necessary to uphold the quality of this flagship component of Rust. + +Additionally, the Rust standard library lacks systematic guidelines for safety reasoning and unsafe code documentation. +As the library continues to grow in size and complexity, maintaining unsafe code documentation quality becomes increasingly challenging without such guidelines. +Rust for Linux has already drafted a [document](https://lore.kernel.org/rust-for-linux/20240717221133.459589-1-benno.lossin@proton.me/) to guide unsafe code usage in that project. However, the standard is still incomplete and not directly applicable to the Rust standard library. +In practice, the standard library team and the opsem team have developed a shared understanding and informal conventions around unsafe code usage through ongoing development. However, these conventions have not yet been systematically documented. +While reviewing the Rust standard library, we aim to document these conventions, which are increasingly important for guiding contributors in writing and reviewing unsafe code correctly. + +Finnaly, such a guideline is also needed by the community. For example, there have recently been several discussion threads about code safety reasoning and documentation, such as [Conditions for unsafe code to rely on correctness](https://internals.rust-lang.org/t/conditions-for-unsafe-code-to-rely-on-correctness/23995) and [Private unsafe fields are a poorly motivated feature](https://internals.rust-lang.org/t/private-unsafe-fields-are-a-poorly-motivated-feature/23976). This suggests that there is ongoing uncertainty and divergence in how people reason about code safety. While existing [Unsafe Code Guidelines](https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#soundness-of-code--of-a-library) establishes an essential baseline, it is not sufficiently detailed to guide the practical adoption of unsafe code, particularly with respect to visibility-related soundness choices and the documentation of safety invariants. We believe that even an experimental standard could help reduce such divergence by providing a clearer and more structured framework for discussion. + +### What we propose to do about it + +- **Review unsafe code documentation in the Rust standard library, identify and resolve inconsistencies (missing safety sections and missing safety properties), following the approach taken in [#138309](https://github.com/rust-lang/rust/pull/138309), [#146925](https://github.com/rust-lang/rust/pull/146925), [#134953](https://github.com/rust-lang/rust/pull/134953), [#134496](https://github.com/rust-lang/rust/pull/134496), and [#135009](https://github.com/rust-lang/rust/pull/135009).** This effort will require continued collaboration between the opsem team and the standard library team, as in previous reviews. + + The inconsistency checking will be primarily based on the following mechanisms and will not introduce hard semantic-related issues. + - **i. Missing safety sections:** + For example, an unsafe API without the safety section in its doc. + + - **ii. Cross-checking API naming and parameters:** + API names and parameters often encode specific safety properties. For instance, the following four APIs (`from_raw(raw: *mut T)`, `from_raw_in(raw: *mut T, alloc: A)`, `from_non_null(ptr: NonNull)`, `from_non_null_in(raw: NonNull, alloc: A)`) of `Box` illustrate a naming convention. The substring `_in` indicates that the pointer must refer to a block of memory allocated by the provided allocator `alloc`. By contrast, APIs without the `_in` suffix imply that the pointer must refer to a block of memory allocated by the global allocator. Such naming patterns also exist in other structs like `Weak` and `Arc`. It is not difficult to detect and confirm inconsistencies among them. See [#135009](https://github.com/rust-lang/rust/pull/135009) and [#135805](https://github.com/rust-lang/rust/pull/135805) for more details. + + - **iii. Inference based on unsafe callees:** + If an unsafe callee has safety requirements that are not enforced or discharged by the caller, this may indicate that a safety requirement is missing from the caller’s documentation. + In the following example, `foo` is an unsafe API with two safety requirements. At the callsite in `bar`, only one requirement `valid for reads` is discharged. The other requirement `aligned for u32` must therefore be documented as a safety requirement of the caller. + ```rust + /// # Safety: + /// - `p` must be valid for reads. + /// - `p` must be properly aligned for `u32`. + pub unsafe fn foo(p: *const u32) -> u32 { + let r = p; + unsafe { *r } + } + + /// # Safety: + /// - `T` must have size at least 4. + /// - `T` must not have padding in its first 4 bytes. + /// - (missing: `x` must be properly aligned for `u32`.) + pub unsafe fn bar(x: T) { + let p: *const u32 = &x as *const T as *const u32; + + // Safety: + // - `p` is valid for reads because it points to `x`. + unsafe { foo(p as *mut u32); } + } + ``` + In a word, all prospective inconsistencies detected via such mechanisms should be straightforward to check and confirm. + +- **Formulate an experimental standard based on the lessons learned from the standard library to guide the future development of library features involving unsafe code (see a draft [here](https://internals.rust-lang.org/t/pre-rfc-rust-safety-standard/23963)).** The proposed standard focuses on two aspects: + * **Code safety reasoning**: principles and criteria for determining when functions or other program components should be marked as safe or unsafe. + * **Unsafe code documentation**: the information that should be provided at unsafe code definition sites, use sites, and struct definition sites where type invariants are required. + + For example, the community has had a fierce [dicussion](https://internals.rust-lang.org/t/private-unsafe-fields-are-a-poorly-motivated-feature/23976) on whether the function, `new_unchecked`, in the following example, should be declared safe. + While surveying the Rust standard library, we observe that declaring a function as unsafe means that it may violate certain safety invariants if misused. Therefore, these invariants must be identified and established first. From this, we can summarize the guiding principle: "safety invariants go before unsafe." + + In the following example, whether `new_unchecked` should be safe or unsafe depends on whether the type explicitly declares a safety invariant that `x` must be even. + If such an invariant is part of the type’s contract, then `new_unchecked` must be declared unsafe, since incorrect usage can violate the invariant. + If such invariant does not exist, then `new_unchecked` is safe, as misuse does not violate any safety invariant. + Therefore, both versions below are sound, but they correspond to different design choices regarding the type’s invariants. + + ```rust + /// # Safety + /// ## Struct invariant + /// - `x` must be even. + pub struct EvenNumber { + val: u32, + } + + impl EvenNumber { + /// # Safety + /// - `x` must be even. + pub unsafe fn new_unchecked(x: u32) -> Self { + EvenNumber{x} + } + } + ``` + +### Work items over the next year + +| Task | Owner(s) | Notes | +| ----------- | -------- | ----- | +| Audit the Rust standard library | @hxuhack, @DiuDiu777 | | +| Draft and refine the safety standard | @hxuhack | | + +### The "shiny future" + +- The standard can also be adopted by downstream Rust crates, promoting more consistent and sound unsafe code practices across the ecosystem. A particularly important beneficiary would be Rust for Linux, which places significant emphasis on the correct handling of unsafe code. +- It can serve as a basis for future attribute-based safety documentation and checking, as proposed in [RFC 3842](https://github.com/rust-lang/rfcs/pull/3842). + +## Team asks + +| Team | Support level | Notes | +| ---------- | ------------- | --------------------------------------- | +| [libs] | Small | Review pull requests; | +| [opsem] | Small | Review pull requests; answer questions on Zulip when there are different openions about specific rules | + +## Frequently asked questions + +### What is the difference from goal [486](https://github.com/rust-lang/rust-project-goals/pull/486). + +[#486](https://github.com/rust-lang/rust-project-goals/pull/486) will start with Eclipse iceoryx2. +> We’ll apply the zerocopy model systematically, starting with [Eclipse iceoryx2](https://github.com/eclipse-iceoryx/iceoryx2), a zero-copy IPC framework with ~3,300 unsafe usages. + +It focuses more on summarizing and documenting practical usage patterns of unsafe code and the specific contracts involved, particularly across different application scenarios. +> Priority areas include cross-process synchronization, memory-mapped regions, cross-process atomics, and UnsafeCell in shared memory—patterns common in systems programming but underdocumented. + +This goal is neither concerned with specific contracts nor with particular application scenarios. It starts from the Rust standard library and summarizes general rules to guide further development of library features involving unsafe code. + diff --git a/src/2026/standardize-std-unsafe.md b/src/2026/standardize-std-unsafe.md deleted file mode 100644 index 0cb0b674..00000000 --- a/src/2026/standardize-std-unsafe.md +++ /dev/null @@ -1,56 +0,0 @@ -# Standardizing Unsafe Code Usage in the Rust Standard Library - -| Metadata | | -| :--------------- | -------------------------------------------------------------------------------- | -| Point of contact | @hxuhack | -| Status | Proposed | -| Tracking issue | | -| Zulip channel | N/A | - -## Summary - -To establish explicit conventions for unsafe code usage and documentation by reviewing existing practices in the Rust standard library, and to audit the library against these conventions to identify and correct inconsistencies. - -## Motivation - -### The status quo - -The Rust standard library does not currently provide systematic guidelines for unsafe code usage and documentation. -While existing [Unsafe Code Guidelines](https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#soundness-of-code--of-a-library) establishes an essential baseline, it is not sufficiently detailed to guide the practical adoption of unsafe code, particularly with respect to visibility-related soundness choices and the documentation of safety invariants. - -In practice, the opsem team and standard library team have developed a shared understanding and informal conventions about unsafe code usage through ongoing development. -These conventions are important, but they have not yet been systematically documented. -As the standard library continues to grow in size and complexity, documenting these conventions becomes increasingly important for guiding contributors in writing and reviewing unsafe code correctly. - -In addition, Rust for Linux has a similar requirement and has already drafted a [document](https://lore.kernel.org/rust-for-linux/20240717221133.459589-1-benno.lossin@proton.me/) to guide unsafe code usage in the project. - -### What we propose to do about it - -- Document the conventions about unsafe code usage as a Rust Safety Standard in collaboration with the opsem team and the standard library team, and iteratively refine the standard based on feedback and experience (see a draft [here](https://internals.rust-lang.org/t/pre-rfc-rust-safety-standard/23963)). The standard focuses on the following two aspects: - - * **Code safety criteria**: criteria for marking functions or other program components as safe or unsafe. - - * **Safety documentation**: the information that should be provided at unsafe code definition sites, use sites, and struct definition sites where type invariants are required. - -- Review unsafe code usage in the Rust standard library as well as Rust for Linux, and identify and correct inconsistencies with the standard. - - -### Work items over the next year - -| Task | Owner(s) | Notes | -| ----------- | -------- | ----- | -| Draft and refine the safety standard | @hxuhack | | -| Audit standard library | @hxuhack, @DiuDiu777 | | -| Audit Rust for Linux | @hxuhack, @yilin0518 | | - -### The "shiny future" - -- The standard can also be adopted by downstream Rust crates, helping to promote consistent and sound unsafe code practices across the ecosystem. -- It can serve as a basis for future attribute-based safety documentation and checking, as proposed in [RFC 3842](https://github.com/rust-lang/rfcs/pull/3842). - -## Team asks - -| Team | Support level | Notes | -| ---------- | ------------- | --------------------------------------- | -| [libs] | Small | Review the standard document and provide feedback, examine any issues identified, and review related pull requests | -| [opsem] | Small | Review the standard document and provide feedback, examine any issues identified, and review related pull requests | From 61170c6d97d8ee60b633291343cfb341ded53c59 Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Sat, 14 Feb 2026 00:02:32 +0800 Subject: [PATCH 5/7] Update src/2026/improve-std-unsafe.md Co-authored-by: Pete LeVasseur --- src/2026/improve-std-unsafe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2026/improve-std-unsafe.md b/src/2026/improve-std-unsafe.md index b3ccfbbd..5bda3bb0 100644 --- a/src/2026/improve-std-unsafe.md +++ b/src/2026/improve-std-unsafe.md @@ -119,7 +119,7 @@ Finnaly, such a guideline is also needed by the community. For example, there ha [#486](https://github.com/rust-lang/rust-project-goals/pull/486) will start with Eclipse iceoryx2. > We’ll apply the zerocopy model systematically, starting with [Eclipse iceoryx2](https://github.com/eclipse-iceoryx/iceoryx2), a zero-copy IPC framework with ~3,300 unsafe usages. -It focuses more on summarizing and documenting practical usage patterns of unsafe code and the specific contracts involved, particularly across different application scenarios. +This goal focuses on identifying particular `unsafe` usage patterns for Eclipse iceoryx2 and tracing those back to relevant portions of the Rust Reference and standard library documentation. The main work is then to follow the work model of the [zerocopy](https://crates.io/crates/zerocopy) crate by working with the relevant teams to have normative language created in the Reference and standard library documentation such that safety-critical Rust users can build safety-cases upon them. > Priority areas include cross-process synchronization, memory-mapped regions, cross-process atomics, and UnsafeCell in shared memory—patterns common in systems programming but underdocumented. This goal is neither concerned with specific contracts nor with particular application scenarios. It starts from the Rust standard library and summarizes general rules to guide further development of library features involving unsafe code. From 7e62b9ae44a82a2d5ff12d69be9c4b827691e9e0 Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Sat, 14 Feb 2026 00:06:33 +0800 Subject: [PATCH 6/7] Update src/2026/improve-std-unsafe.md Co-authored-by: Pete LeVasseur --- src/2026/improve-std-unsafe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2026/improve-std-unsafe.md b/src/2026/improve-std-unsafe.md index 5bda3bb0..6d807fc4 100644 --- a/src/2026/improve-std-unsafe.md +++ b/src/2026/improve-std-unsafe.md @@ -122,5 +122,5 @@ Finnaly, such a guideline is also needed by the community. For example, there ha This goal focuses on identifying particular `unsafe` usage patterns for Eclipse iceoryx2 and tracing those back to relevant portions of the Rust Reference and standard library documentation. The main work is then to follow the work model of the [zerocopy](https://crates.io/crates/zerocopy) crate by working with the relevant teams to have normative language created in the Reference and standard library documentation such that safety-critical Rust users can build safety-cases upon them. > Priority areas include cross-process synchronization, memory-mapped regions, cross-process atomics, and UnsafeCell in shared memory—patterns common in systems programming but underdocumented. -This goal is neither concerned with specific contracts nor with particular application scenarios. It starts from the Rust standard library and summarizes general rules to guide further development of library features involving unsafe code. +This goal is focused on ensuring that particular `unsafe` usages from the language and standard library are documented in a normative fashion as to how they behave. It would not produce a general standard or set of guidelines on how to use `unsafe` to mitigate risk of introducing undefined behavior. From 89440842f30c3f6bd54545f25e946539680a96b3 Mon Sep 17 00:00:00 2001 From: "XU, Hui" Date: Wed, 18 Feb 2026 06:34:25 +0800 Subject: [PATCH 7/7] fix typos Co-authored-by: Josh Triplett --- src/2026/improve-std-unsafe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2026/improve-std-unsafe.md b/src/2026/improve-std-unsafe.md index 6d807fc4..d5c1fec6 100644 --- a/src/2026/improve-std-unsafe.md +++ b/src/2026/improve-std-unsafe.md @@ -110,7 +110,7 @@ Finnaly, such a guideline is also needed by the community. For example, there ha | Team | Support level | Notes | | ---------- | ------------- | --------------------------------------- | | [libs] | Small | Review pull requests; | -| [opsem] | Small | Review pull requests; answer questions on Zulip when there are different openions about specific rules | +| [opsem] | Small | Review pull requests; answer questions on Zulip when there are different opinions about specific rules | ## Frequently asked questions