From d07e4060c822c079b5cac0ada0227efd89d6b593 Mon Sep 17 00:00:00 2001
From: carbotaniuman <41451839+carbotaniuman@users.noreply.github.com>
Date: Sat, 20 Jul 2024 20:19:25 -0500
Subject: [PATCH 1/6] Add some basic docs for unsafe attrs
---
src/abi.md | 10 ++++++++++
src/attributes.md | 14 ++++++++++++++
2 files changed, 24 insertions(+)
diff --git a/src/abi.md b/src/abi.md
index 374dd6d45..931727256 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -66,12 +66,19 @@ item's name.
Additionally, the item will be publicly exported from the produced library or
object file, similar to the [`used` attribute](#the-used-attribute).
+This attribute is unsafe as an unmangled symbol may collide with another
+symbol with the same name (or a well-known symbol), leading to undefined behavior.
+
## The `link_section` attribute
The *`link_section` attribute* specifies the section of the object file that a
[function] or [static]'s content will be placed into. It uses the
[_MetaNameValueStr_] syntax to specify the section name.
+This attribute is unsafe as using `link_section` allows users to place data
+and code into sections of memory not expecting them, such as mutable data
+into read-only areas.
+
```rust,no_run
#[no_mangle]
@@ -85,6 +92,9 @@ The *`export_name` attribute* specifies the name of the symbol that will be
exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax
to specify the symbol name.
+This attribute is unsafe as a symbol with a custom name may collide with another
+symbol with the same name (or a well-known symbol), leading to undefined behavior.
+
```rust
#[export_name = "exported_symbol_name"]
pub fn name_in_rust() { }
diff --git a/src/attributes.md b/src/attributes.md
index a56e276f6..a2ed37f33 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -4,9 +4,13 @@
> **Syntax**\
> _InnerAttribute_ :\
> `#` `!` `[` _Attr_ `]`
+> `#` `!` `[` `unsafe` `(` _Attr_ `)` `]`
>
> _OuterAttribute_ :\
> `#` `[` _Attr_ `]`
+> `#` `[` `unsafe` `(` _Attr_ `)` `]`
+> `#` `!` `[` _Attr_ `]`
+> `#` `!` `[` `unsafe` `(` _Attr_ `)` `]`
>
> _Attr_ :\
> [_SimplePath_] _AttrInput_?
@@ -29,6 +33,16 @@ Attributes other than macro attributes also allow the input to be an equals
sign (`=`) followed by an expression. See the [meta item
syntax](#meta-item-attribute-syntax) below for more details.
+An attribute may be considered unsafe. Unsafe attributes must *satisfy* extra
+safety conditions that cannot be checked by the compiler, and are specified
+as the attribute wrapped in `unsafe(...)`, for instance, `#[unsafe(no_mangle)]`.
+
+The following attributes are unsafe:
+
+* [`export_name`]
+* [`link_section`]
+* [`no_mangle`]
+
Attributes can be classified into the following kinds:
* [Built-in attributes]
From 7b4d9b3080f97ebe9e093b63cf88644339c6657a Mon Sep 17 00:00:00 2001
From: Travis Cross
Date: Mon, 22 Jul 2024 07:31:13 +0000
Subject: [PATCH 2/6] Wordsmith text for unsafe attributes
In this commit, we improve some verbiage.
---
src/abi.md | 12 ++++++------
src/attributes.md | 7 ++++---
2 files changed, 10 insertions(+), 9 deletions(-)
diff --git a/src/abi.md b/src/abi.md
index 931727256..47116f5ee 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -66,8 +66,8 @@ item's name.
Additionally, the item will be publicly exported from the produced library or
object file, similar to the [`used` attribute](#the-used-attribute).
-This attribute is unsafe as an unmangled symbol may collide with another
-symbol with the same name (or a well-known symbol), leading to undefined behavior.
+This attribute is unsafe as an unmangled symbol may collide with another symbol
+with the same name (or with a well-known symbol), leading to undefined behavior.
## The `link_section` attribute
@@ -75,9 +75,8 @@ The *`link_section` attribute* specifies the section of the object file that a
[function] or [static]'s content will be placed into. It uses the
[_MetaNameValueStr_] syntax to specify the section name.
-This attribute is unsafe as using `link_section` allows users to place data
-and code into sections of memory not expecting them, such as mutable data
-into read-only areas.
+This attribute is unsafe as it allows users to place data and code into sections
+of memory not expecting them, such as mutable data into read-only areas.
```rust,no_run
@@ -93,7 +92,8 @@ exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax
to specify the symbol name.
This attribute is unsafe as a symbol with a custom name may collide with another
-symbol with the same name (or a well-known symbol), leading to undefined behavior.
+symbol with the same name (or with a well-known symbol), leading to undefined
+behavior.
```rust
#[export_name = "exported_symbol_name"]
diff --git a/src/attributes.md b/src/attributes.md
index a2ed37f33..9bc82c301 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -33,9 +33,10 @@ Attributes other than macro attributes also allow the input to be an equals
sign (`=`) followed by an expression. See the [meta item
syntax](#meta-item-attribute-syntax) below for more details.
-An attribute may be considered unsafe. Unsafe attributes must *satisfy* extra
-safety conditions that cannot be checked by the compiler, and are specified
-as the attribute wrapped in `unsafe(...)`, for instance, `#[unsafe(no_mangle)]`.
+An attribute may be unsafe to apply. To avoid undefined behavior when using
+these attributes, certain obligations that cannot be checked by the compiler
+must be met. To assert these have been, the attribute is wrapped in
+`unsafe(..)`, e.g. `#[unsafe(no_mangle)]`.
The following attributes are unsafe:
From e588d824950dd944a4e07ef3428a7e6cc89ec0f6 Mon Sep 17 00:00:00 2001
From: Travis Cross
Date: Mon, 22 Jul 2024 07:49:01 +0000
Subject: [PATCH 3/6] Fix grammar for unsafe attributes
There were some errors in the formatting and the content of the
grammar for unsafe attributes. Let's fix those.
---
src/attributes.md | 10 ++++------
1 file changed, 4 insertions(+), 6 deletions(-)
diff --git a/src/attributes.md b/src/attributes.md
index 9bc82c301..c05bfa009 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -3,14 +3,12 @@
> **Syntax**\
> _InnerAttribute_ :\
-> `#` `!` `[` _Attr_ `]`
-> `#` `!` `[` `unsafe` `(` _Attr_ `)` `]`
+> `#` `!` `[` _Attr_ `]`\
+> | `#` `!` `[` `unsafe` `(` _Attr_ `)` `]`
>
> _OuterAttribute_ :\
-> `#` `[` _Attr_ `]`
-> `#` `[` `unsafe` `(` _Attr_ `)` `]`
-> `#` `!` `[` _Attr_ `]`
-> `#` `!` `[` `unsafe` `(` _Attr_ `)` `]`
+> `#` `[` _Attr_ `]`\
+> | `#` `[` `unsafe` `(` _Attr_ `)` `]`
>
> _Attr_ :\
> [_SimplePath_] _AttrInput_?
From 5bbf37952fe1673dd9134880d21ff48ad04c54e1 Mon Sep 17 00:00:00 2001
From: Travis Cross
Date: Mon, 22 Jul 2024 08:07:08 +0000
Subject: [PATCH 4/6] Add to unsafety section for unsafe attributes
Let's describe unsafe attributes in the chapter on unsafety.
---
src/unsafe-keyword.md | 10 ++++++++--
src/unsafety.md | 2 ++
2 files changed, 10 insertions(+), 2 deletions(-)
diff --git a/src/unsafe-keyword.md b/src/unsafe-keyword.md
index df68a74cc..20aa1aa56 100644
--- a/src/unsafe-keyword.md
+++ b/src/unsafe-keyword.md
@@ -1,10 +1,10 @@
# The `unsafe` keyword
The `unsafe` keyword can occur in several different contexts:
-unsafe functions (`unsafe fn`), unsafe blocks (`unsafe {}`), unsafe traits (`unsafe trait`), unsafe trait implementations (`unsafe impl`), and unsafe external blocks (`unsafe extern`).
+unsafe functions (`unsafe fn`), unsafe blocks (`unsafe {}`), unsafe traits (`unsafe trait`), unsafe trait implementations (`unsafe impl`), unsafe external blocks (`unsafe extern`), and unsafe attributes (`#[unsafe(attr)]`).
It plays several different roles, depending on where it is used and whether the `unsafe_op_in_unsafe_fn` lint is enabled:
- it is used to mark code that *defines* extra safety conditions (`unsafe fn`, `unsafe trait`)
-- it is used to mark code that needs to *satisfy* extra safety conditions (`unsafe {}`, `unsafe impl`, `unsafe fn` without [`unsafe_op_in_unsafe_fn`], `unsafe extern`)
+- it is used to mark code that needs to *satisfy* extra safety conditions (`unsafe {}`, `unsafe impl`, `unsafe fn` without [`unsafe_op_in_unsafe_fn`], `unsafe extern`, `#[unsafe(attr)]`)
The following discusses each of these cases.
See the [keyword documentation][keyword] for some illustrative examples.
@@ -62,3 +62,9 @@ Unsafe trait implementations are the logical dual to unsafe traits: where unsafe
The programmer who declares an [external block] must assure that the signatures of the items contained within are correct. Failing to do so may lead to undefined behavior. That this obligation has been met is indicated by writing `unsafe extern`.
[external block]: items/external-blocks.md
+
+## Unsafe attributes (`#[unsafe(attr)]`)
+
+An [unsafe attribute] is one that has extra safety conditions that must be upheld when using the attribute. The compiler cannot check whether these conditions have been upheld. To assert that they have been, these attributes must be wrapped in `unsafe(..)`, e.g. `#[unsafe(no_mangle)]`.
+
+[unsafe attribute]: attributes.md
diff --git a/src/unsafety.md b/src/unsafety.md
index 237a4bfec..9383eba9d 100644
--- a/src/unsafety.md
+++ b/src/unsafety.md
@@ -12,6 +12,7 @@ Rust:
- Calling an unsafe function (including an intrinsic or foreign function).
- Implementing an [unsafe trait].
- Declaring an [`extern`] block.
+- Applying an [unsafe attribute] to an item.
[`extern`]: items/external-blocks.md
[`union`]: items/unions.md
@@ -19,3 +20,4 @@ Rust:
[external]: items/external-blocks.md
[raw pointer]: types/pointer.md
[unsafe trait]: items/traits.md#unsafe-traits
+[unsafe attribute]: attributes.md
From f6cd69a89caadd47cfcb32bd6a02830f6d0180a9 Mon Sep 17 00:00:00 2001
From: Eric Huss
Date: Wed, 24 Jul 2024 17:16:15 -0700
Subject: [PATCH 5/6] Fix the Attr grammar for unsafe attributes.
The _Attr_ production is used for `cfg_attr` attribute and the `meta`
macro fragment specifier, and those need to accept the new `unsafe`
syntax.
---
src/attributes.md | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/src/attributes.md b/src/attributes.md
index c05bfa009..f3ca9173e 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -3,15 +3,14 @@
> **Syntax**\
> _InnerAttribute_ :\
-> `#` `!` `[` _Attr_ `]`\
-> | `#` `!` `[` `unsafe` `(` _Attr_ `)` `]`
+> `#` `!` `[` _Attr_ `]`
>
> _OuterAttribute_ :\
-> `#` `[` _Attr_ `]`\
-> | `#` `[` `unsafe` `(` _Attr_ `)` `]`
+> `#` `[` _Attr_ `]`
>
> _Attr_ :\
-> [_SimplePath_] _AttrInput_?
+> [_SimplePath_] _AttrInput_?\
+> | `unsafe` `(` [_SimplePath_] _AttrInput_? `)`
>
> _AttrInput_ :\
> [_DelimTokenTree_]\
From 73c11acaf1d161fdf953eeba1be7cd2d0c0a79a8 Mon Sep 17 00:00:00 2001
From: Eric Huss
Date: Wed, 24 Jul 2024 17:16:23 -0700
Subject: [PATCH 6/6] Use `unsafe` in the unsafe attribute examples.
This will be required in 2024.
---
src/abi.md | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/src/abi.md b/src/abi.md
index 47116f5ee..09ff20b16 100644
--- a/src/abi.md
+++ b/src/abi.md
@@ -69,6 +69,11 @@ object file, similar to the [`used` attribute](#the-used-attribute).
This attribute is unsafe as an unmangled symbol may collide with another symbol
with the same name (or with a well-known symbol), leading to undefined behavior.
+```rust
+#[unsafe(no_mangle)]
+extern "C" fn foo() {}
+```
+
## The `link_section` attribute
The *`link_section` attribute* specifies the section of the object file that a
@@ -80,8 +85,8 @@ of memory not expecting them, such as mutable data into read-only areas.
```rust,no_run
-#[no_mangle]
-#[link_section = ".example_section"]
+#[unsafe(no_mangle)]
+#[unsafe(link_section = ".example_section")]
pub static VAR1: u32 = 1;
```
@@ -96,7 +101,7 @@ symbol with the same name (or with a well-known symbol), leading to undefined
behavior.
```rust
-#[export_name = "exported_symbol_name"]
+#[unsafe(export_name = "exported_symbol_name")]
pub fn name_in_rust() { }
```