Document that "extern blocks must be unsafe" in Rust 2024

[t5kd]

The documentation on extern contains the following code sample:

#[link(name = "my_c_library")]
extern "C" {
    fn my_c_function(x: i32) -> bool;
}

Due to #123743, attempting to compile such code with the 2024 edition of Rust fails:

error: extern blocks must be unsafe

This PR extends the extern documentation with a brief explanation of the new requirement. It also adds the missing unsafe keyword to the code sample, which should be compatible with rustc since v1.82.

Related docs:

• https://doc.rust-lang.org/reference/items/external-blocks.html
• https://doc.rust-lang.org/edition-guide/rust-2024/unsafe-extern.html

[rustbot]

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[tgross35]

Since this is unsafe, it would be good to document what makes usage sound. Could you do that, and add an example // SAFETY: comment?

There is more at https://github.com/rust-lang/rfcs/blob/master/text/3484-unsafe-extern-blocks.md but mainly you have to assert that the function exists with that signature, since the compiler has no way to verify it.

[tgross35]

It's probably actually okay to drop the mention of edition differences. unsafe extern can be used in all editions so it's not something the user needs to worry about, always using unsafe extern should be preferred.

[t5kd]

Since this is unsafe, it would be good to document what makes usage sound. Could you do that, and add an example // SAFETY: comment?

Sure, thank you for your feedback. I came up with two possible options.

Option 1 (more compact):

This use of extern is unsafe, since we are asserting to the compiler that all declared signatures are correct. If they are not, using these items may lead to undefined behavior.

// SAFETY: It is our responsibility to ensure that the following
// external block contains correct function signatures.
#[link(name = "my_c_library")]
unsafe extern "C" {
    fn my_c_function(x: i32) -> bool;
}

Option 2 (more verbose):

This use of extern is unsafe, since we are asserting to the compiler that all declared signatures are correct. If they are not, using these items may lead to undefined behavior. In addition, if it is possible to prove that calling certain external functions will not lead to undefined behavior, their declarations can be marked as safe. Such functions are directly usable from safe Rust code.

// SAFETY: It is our responsibility to ensure that the following
// external block contains correct function signatures.
#[link(name = "my_c_library")]
unsafe extern "C" {
    fn first_c_function(x: i32) -> bool;
    // SAFETY: We need to ensure that calling the following
    // function will not cause undefined behavior.
    safe fn second_c_function() -> bool;
}

Do you mean something like that?

[tgross35]

I think the first option is fine, the reference has more details about the caveats here. The safety comment should be adjusted though, it's describing what needs to be done rather than that we have done it.

Something like "SAFETY: below function definitions match the headers for my_c_library" would be more accurate.

[t5kd]

Got it, I just committed a possible wording. For consistency with the corresponding Reference item, I went for the term "function declarations" rather than "function signatures" or "function definitions". Please let me know if there is something to improve. Otherwise, the PR is complete from my side.

[tgross35]

LGTM! Please squash

[tgross35]

Thanks for adding this clarification.

@bors r+ rollup

[bors]

📌 Commit 1862feb has been approved by tgross35

It is now in the queue for this repository.