Summary

Consider some attributes ‘unsafe’, so that they must only be used like this:

#[unsafe(no_mangle)]

Motivation

Some of our attributes, such as no_mangle, can be used to cause Undefined Behavior without any unsafe block. If this was regular code we would require them to be placed in an unsafe {} block, but since they are attributes that makes less sense. Hence we need a concept of ‘unsafe attributes’ and accompanying syntax to declare that one is aware of the UB risks here (and it might be good to add a SAFETY comment explaining why this use of the attribute is fine).

Guide-level explanation

Example explanation for no_mangle; the other attributes need something similar.

When declaring a function like this

#[no_mangle]
pub fn write(...) { ... }

this will cause Rust to generate a globally visible function with the linker/export name write. As consequence of that, other code that wants to call the POSIX write function might end up calling this other write instead. This can easily lead to Undefined Behavior:

  • The other write might have the wrong signature, so arguments are passed incorrectly.
  • The other write might not have the expected behavior of write, causing code relying on this behavior to misbehave.

To avoid this, when declaring a function no_mangle, it is important that the name of the function does not clash with other globally named functions. Similar to how unsafe { ... } blocks are used to acknowledge that this code is dangerous and needs manual checking, unsafe(no_mangle) acknowledges that no_mangle is dangerous and needs to be manually checked for correctness:

// SAFETY: there is no other global function of this name
#[unsafe(no_mangle)]
pub fn my_own_write(...) { ... }

Note that when writing a library crate, it is in general not possible to make claims like “there is no other global function of this name”. This is a fundamental limitation of the global linking namespace, and not something Rust currently is able to overcome. Libraries that make such assumptions should ideally document somewhere publicly that they consider some namespace, i.e. every function starting with _mycrate__, to be reserved for their exclusive use.

Reference-level explanation

Some attributes (e.g. no_mangle, export_name, link_section – see here for a more complete list) are considered “unsafe” attributes. An unsafe attribute must only be used inside unsafe(...) in the attribute declaration, like

#[unsafe(no_mangle)]

For backwards compatibility reasons, using these attributes outside of unsafe(...) is just a lint, not a hard error. The lint is called unsafe_attr_outside_unsafe. Initially, this lint will be allow-by-default. Unsafe attributes that are added in the future can hard-require unsafe from the start since the backwards compatibility concern does not apply to them. The 2024 edition is also expected to increase the severity of this lint, possibly even making it a hard error.

Syntactically, for each unsafe attribute attr, we now also accept unsafe(attr) anywhere that attr can be used (in particular, inside cfg_attr). unsafe cannot be nested, cannot contain cfg_attr, and cannot contain any other (non-unsafe) attributes. Only a single attribute can be used inside unsafe, i.e., unsafe(foo, bar) is invalid.

The deny(unsafe_code) lint denies the use of unsafe attributes both inside and outside of unsafe(...) blocks. (That lint currently has special handling to deny these attributes. Once there is a general notion of ‘unsafe attributes’ as proposed by this RFC, that special handling should no longer be needed.)

The unsafe(...) attribute block is required even for functions declared inside an unsafe block. That is, the following is an error:

fn outer() {
  unsafe {
    #[no_mangle]
    fn write() {}
  }
}

This matches the fact that expression-level unsafety is not inherited for items declared inside other items.

Drawbacks

I think if we had thought of this around Rust 1.0, then this would be rather uncontroversial. As things stand now, this proposal will cause a lot of churn since all existing uses of these unsafe attributes need to be adjusted. The warning for using unsafe attributes outside unsafe(...) should probably have an auto-fix available to help ease the transition here.

Rationale and alternatives

  • Nothing. We could do nothing at all, and live with the status quo. However then we will not be able to fix issues like no_mangle being unsound, which is one of the oldest open soundness issues.
  • Rename. We could just rename the attributes to unsafe_no_mangle etc. However that is inconsistent with how we approach unsafe on expressions, and feels much less systematic and much more ad-hoc.
  • deny(unsafe_code). We already started the process of rejecting these attributes when deny(unsafe_code) is used. We could say that is enough. However the RFC authors thinks that is insufficient, since only few crates use that lint, and since it is the wrong default for Rust (users have to opt-in to a soundness-critical diagnostic – that’s totally against the “safety by default” goal of Rust). This RFC says that yes, deny(unsafe_code) should deny those attributes, but we should go further and require an explicit unsafe(...) attribute block for them to be used at all.
  • Item-level unsafe blocks. We could find some way to have ‘unsafe blocks’ around entire functions or modules. However, those would go against the usual goal of keeping unsafe blocks small. Big unsafe blocks risk accidentally calling an unsafe operation in there without even realizing it.
  • Other syntax. Obviously we could pick a different syntax for the same concept, but this seems like the most natural marriage of the idea of unsafe blocks from regular code, and the existing attributes syntax.

Prior art

We have unsafe blocks; this is basically the same thing for the “attributes DSL”.

In the attribute DSL, we already have a “nesting” construct: cfg_attr. That allows terms like #[cfg_attr(debug_assertions, deny(unsafe_code), allow(unused))], so there is precedent for having a list of attributes inside a single attribute.

I don’t know of other languages that would distinguish safe and unsafe attributes.

Unresolved questions

  • Different lint staging. The lint on using existing unsafe attributes like no_mangle outside unsafe(...) could be staged in various ways: it could be warn-by-default to start or we wait a while before to do that, it could be edition-dependent, it might eventually be deny-by-default or even a hard error on some editions – there are lots of details here, which can be determined later during the process.

Future possibilities

  • Unsafe attribute proc macros. We could imagine something like 
    #[proc_macro_attribute(require_unsafe)]
fn spoopy(args: TokenStream, input: TokenStream) -> TokenStream {…}
    to declare that an attribute proc macro is unsafe to use, and must only occur as an unsafe macro. Such an unsafe-to-use attribute proc macro must declare in a comment what its safety requirements are. (This is the unsafe from unsafe fn, whereas the rest of the RFC is using the unsafe from unsafe { ... }.)
  • Unsafe derive. We could use #[unsafe(derive(Trait))] to derive an unsafe impl where the deriving macro itself cannot check all required safety conditions (i.e., this is ‘unsafe to derive’).
  • Unsafe tool attributes. Same as above, but for tool attributes.
  • Unsafe attributes on statements. For now, the only unsafe attributes we have don’t make sense on the statement level. Once we do have unsafe statement attributes, we need to figure out whether inside unsafe {} blocks one still needs to also write unsafe(...).
  • Lists and nesting. We could specify that unsafe(...) may contain a list of arbitrary attributes (including safe ones), may be nested, and may contain cfg_attr that gets expanded appropriately. However that could make it tricky to consistently support non-builtin unsafe attributes in the future, so the RFC proposes to not do that yet. The current approach is forward-compatible with allowing lists and nesting in the future.
  • Unsafe crates. Some attributes’ requirements cannot be fully discharged locally. For instance, if a lib crate uses no_mangle, this really puts a burden on the author of the final binary to ensure that the symbol dos not conflict. In the future it would be better if rust tooling could automatically surface a such requirements to downstream code, for example by an automatic “unsafe attributes used” listing in a crate’s generated rustdoc.