Rollup merge of #140216 - t5kd:master, r=tgross35

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

The [documentation on `extern`](https://doc.rust-lang.org/std/keyword.extern.html) contains the following code sample:
```rust
#[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

1 files changed, 6 insertions, 2 deletions

diff --git a/library/std/src/keyword_docs.rs b/library/std/src/keyword_docs.rs
index 91701576130..c9595b051e2 100644
--- a/library/std/src/keyword_docs.rs
+++ b/library/std/src/keyword_docs.rs
@@ -388,11 +388,15 @@ mod enum_keyword {}
 /// lazy_static;`. The other use is in foreign function interfaces (FFI).
 ///
 /// `extern` is used in two different contexts within FFI. The first is in the form of external
-/// blocks, for declaring function interfaces that Rust code can call foreign code by.
+/// blocks, for declaring function interfaces that Rust code can call foreign code by. This use
+/// of `extern` is unsafe, since we are asserting to the compiler that all function declarations
+/// are correct. If they are not, using these items may lead to undefined behavior.
 ///
 /// ```rust ignore
+/// // SAFETY: The function declarations given below are in
+/// // line with the header files of `my_c_library`.
 /// #[link(name = "my_c_library")]
-/// extern "C" {
+/// unsafe extern "C" {
 ///     fn my_c_function(x: i32) -> bool;
 /// }
 /// ```