Rollup merge of rust-lang#60443 - RalfJung:as_ptr, r=SimonSapin

as_ptr returns a read-only pointer

Add comments to `as_ptr` methods to warn that these are read-only pointers, and writing to them is UB.

[It was pointed out](https://internals.rust-lang.org/t/as-ptr-vs-as-mut-ptr/9940) that `CStr` does not even have an `as_mut_ptr`. I originally was going to add one, but there is no method at all that would mutate a `CStr`. Was that a deliberate choice or should I add an `as_mut_ptr` (similar to [what I did for `str`](rust-lang#58200))?

src/libcore/slice/mod.rs

@@ -359,6 +359,10 @@ impl<T> [T] {
  /// The caller must ensure that the slice outlives the pointer this
  /// function returns, or else it will end up pointing to garbage.
  ///
+ /// The caller must also ensure that the memory the pointer (non-transitively) points to
+ /// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer
+ /// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`].
+ ///
  /// Modifying the container referenced by this slice may cause its buffer
  /// to be reallocated, which would also make any pointers to it invalid.
  ///
@@ -374,6 +378,8 @@ impl<T> [T] {
  /// }
  /// }
  /// ```
+ ///
+ /// [`as_mut_ptr`]: #method.as_mut_ptr
  #[stable(feature = "rust1", since = "1.0.0")]
  #[inline]
  pub const fn as_ptr(&self) -> *const T {

src/libcore/str/mod.rs

@@ -2198,7 +2198,11 @@ impl str {
  /// [`u8`]. This pointer will be pointing to the first byte of the string
  /// slice.
  ///
+ /// The caller must ensure that the returned pointer is never written to.
+ /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
+ ///
  /// [`u8`]: primitive.u8.html
+ /// [`as_mut_ptr`]: #method.as_mut_ptr
  ///
  /// # Examples
  ///

src/libstd/ffi/c_str.rs

@@ -43,7 +43,9 @@ use crate::sys;
 /// `CString` implements a [`as_ptr`] method through the [`Deref`]
 /// trait. This method will give you a `*const c_char` which you can
 /// feed directly to extern functions that expect a nul-terminated
-/// string, like C's `strdup()`.
+/// string, like C's `strdup()`. Notice that [`as_ptr`] returns a
+/// read-only pointer; if the C code writes to it, that causes
+/// undefined behavior.
 ///
 /// # Extracting a slice of the whole C string
 ///
@@ -61,7 +63,7 @@ use crate::sys;
 ///
 /// Once you have the kind of slice you need (with or without a nul
 /// terminator), you can call the slice's own
-/// [`as_ptr`][slice.as_ptr] method to get a raw pointer to pass to
+/// [`as_ptr`][slice.as_ptr] method to get a read-only raw pointer to pass to
 /// extern functions. See the documentation for that function for a
 /// discussion on ensuring the lifetime of the raw pointer.
 ///
@@ -1043,6 +1045,9 @@ impl CStr {
  ///
  /// **WARNING**
  ///
+ /// The returned pointer is read-only; writing to it (including passing it
+ /// to C code that writes to it) causes undefined behavior.
+ ///
  /// It is your responsibility to make sure that the underlying memory is not
  /// freed too early. For example, the following code will cause undefined
  /// behavior when `ptr` is used inside the `unsafe` block: