Rollup merge of #114412 - RalfJung:libc-symbols, r=pnkfelix

document our assumptions about symbols provided by the libc

LLVM makes assumptions about `memcmp`, `memmove`, and `memset` that go beyond what the C standard guarantees -- see https://reviews.llvm.org/D86993. Since we use LLVM, we are inheriting these assumptions.

With https://github.com/rust-lang/rust/pull/114382 we are also making a similar assumption about `memcmp`, so I added that to the list.

Fixes https://github.com/rust-lang/unsafe-code-guidelines/issues/426.

1 files changed, 13 insertions, 5 deletions

diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs
index b97cb652076..c3edd3a9d7d 100644
--- a/library/core/src/lib.rs
+++ b/library/core/src/lib.rs
@@ -20,11 +20,19 @@
 // FIXME: Fill me in with more detail when the interface settles
 //! This library is built on the assumption of a few existing symbols:
 //!
-//! * `memcpy`, `memcmp`, `memset`, `strlen` - These are core memory routines which are
-//!   often generated by LLVM. Additionally, this library can make explicit
-//!   calls to these functions. Their signatures are the same as found in C.
-//!   These functions are often provided by the system libc, but can also be
-//!   provided by the [compiler-builtins crate](https://crates.io/crates/compiler_builtins).
+//! * `memcpy`, `memmove`, `memset`, `memcmp`, `bcmp`, `strlen` - These are core memory routines
+//!   which are generated by Rust codegen backends. Additionally, this library can make explicit
+//!   calls to `strlen`. Their signatures are the same as found in C, but there are extra
+//!   assumptions about their semantics: For `memcpy`, `memmove`, `memset`, `memcmp`, and `bcmp`, if
+//!   the `n` parameter is 0, the function is assumed to not be UB. Furthermore, for `memcpy`, if
+//!   source and target pointer are equal, the function is assumed to not be UB.
+//!   (Note that these are [standard assumptions](https://reviews.llvm.org/D86993) among compilers.)
+//!   These functions are often provided by the system libc, but can also be provided by the
+//!   [compiler-builtins crate](https://crates.io/crates/compiler_builtins).
+//!   Note that the library does not guarantee that it will always make these assumptions, so Rust
+//!   user code directly calling the C functions should follow the C specification! The advice for
+//!   Rust user code is to call the functions provided by this library instead (such as
+//!   `ptr::copy`).
 //!
 //! * `rust_begin_panic` - This function takes four arguments, a
 //!   `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments