mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-22 14:55:26 +00:00
Improve the safety docs for CStr
Namely, the two functions `from_ptr` and `from_bytes_with_nul_unchecked`. Before, this functions didn't state the requirements clearly enough, and I was not immediately able to find them like for other functions. This doesn't change the content of the docs, but simply rewords them for clarity.
This commit is contained in:
parent
1851f0802e
commit
0dda42bc14
@ -196,20 +196,32 @@ impl CStr {
|
||||
/// allows inspection and interoperation of non-owned C strings. The total
|
||||
/// size of the raw C string must be smaller than `isize::MAX` **bytes**
|
||||
/// in memory due to calling the `slice::from_raw_parts` function.
|
||||
/// This method is unsafe for a number of reasons:
|
||||
///
|
||||
/// * There is no guarantee to the validity of `ptr`.
|
||||
/// * The returned lifetime is not guaranteed to be the actual lifetime of
|
||||
/// `ptr`.
|
||||
/// * There is no guarantee that the memory pointed to by `ptr` contains a
|
||||
/// valid nul terminator byte at the end of the string.
|
||||
/// * It is not guaranteed that the memory pointed by `ptr` won't change
|
||||
/// before the `CStr` has been destroyed.
|
||||
/// # Safety
|
||||
///
|
||||
/// * The memory pointed to by `ptr` must contain a valid nul terminator at the
|
||||
/// end of the string.
|
||||
///
|
||||
/// * `ptr` must be [valid] for reads of bytes up to and including the null terminator.
|
||||
/// This means in particular:
|
||||
///
|
||||
/// * The entire memory range of this `CStr` must be contained within a single allocated object!
|
||||
/// * `ptr` must be non-null even for a zero-length cstr.
|
||||
///
|
||||
/// * The memory referenced by the returned `CStr` must not be mutated for
|
||||
/// the duration of lifetime `'a`.
|
||||
///
|
||||
/// > **Note**: This operation is intended to be a 0-cost cast but it is
|
||||
/// > currently implemented with an up-front calculation of the length of
|
||||
/// > the string. This is not guaranteed to always be the case.
|
||||
///
|
||||
/// # Caveat
|
||||
///
|
||||
/// The lifetime for the returned slice is inferred from its usage. To prevent accidental misuse,
|
||||
/// it's suggested to tie the lifetime to whichever source lifetime is safe in the context,
|
||||
/// such as by providing a helper function taking the lifetime of a host value for the slice,
|
||||
/// or by explicit annotation.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```ignore (extern-declaration)
|
||||
@ -227,6 +239,8 @@ impl CStr {
|
||||
/// }
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// [valid]: core::ptr#safety
|
||||
#[inline]
|
||||
#[must_use]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
@ -349,8 +363,11 @@ impl CStr {
|
||||
/// Unsafely creates a C string wrapper from a byte slice.
|
||||
///
|
||||
/// This function will cast the provided `bytes` to a `CStr` wrapper without
|
||||
/// performing any sanity checks. The provided slice **must** be nul-terminated
|
||||
/// and not contain any interior nul bytes.
|
||||
/// performing any sanity checks.
|
||||
///
|
||||
/// # Safety
|
||||
/// The provided slice **must** be nul-terminated and not contain any interior
|
||||
/// nul bytes.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
Loading…
Reference in New Issue
Block a user