From 71b526bf944c04ed0ac7d96b898332b4697a53a6 Mon Sep 17 00:00:00 2001
From: Dirk Gadsden <dirk@esherido.com>
Date: Sun, 24 Jan 2016 17:41:44 -0500
Subject: [PATCH 1/2] Add section about memory safety to `ffi::CString`
documentation
Also a minor language tweak to the documentation of the
`ffi::CString::from_raw` function.
---
src/libstd/ffi/c_str.rs | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs
index 9d505607a60..4c3b77402e4 100644
--- a/src/libstd/ffi/c_str.rs
+++ b/src/libstd/ffi/c_str.rs
@@ -60,6 +60,18 @@ use vec::Vec;
/// }
/// # }
/// ```
+///
+/// # Safety
+///
+/// `CString` is intended for working with traditional C-style strings
+/// (a sequence of non-null bytes terminated by a single null byte); the
+/// primary use case for these kinds of strings is interoperating with C-like
+/// code. Often you will need to transfer ownership to/from that external
+/// code. It is strongly recommended that you thoroughly read through the
+/// documentation of `CString` before use, as improper ownership management
+/// of `CString` instances can lead to invalid memory accesses, memory leaks,
+/// and other memory errors.
+
#[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct CString {
@@ -209,9 +221,9 @@ impl CString {
/// Retakes ownership of a CString that was transferred to C.
///
- /// The only appropriate argument is a pointer obtained by calling
- /// `into_raw`. The length of the string will be recalculated
- /// using the pointer.
+ /// This should only ever be called with a pointer that was earlier
+ /// obtained by calling `into_raw` on a CString. Additionally, the length
+ /// of the string will be recalculated from the pointer.
#[stable(feature = "cstr_memory", since = "1.4.0")]
pub unsafe fn from_raw(ptr: *mut c_char) -> CString {
let len = libc::strlen(ptr) + 1; // Including the NUL byte
From 9cfa1916fa06fa5fa809d6d7807a6f978e35c67d Mon Sep 17 00:00:00 2001
From: Dirk Gadsden <dirk@esherido.com>
Date: Wed, 27 Jan 2016 15:07:10 -0800
Subject: [PATCH 2/2] Fix formatting in documentation of `ffi::CString`
---
src/libstd/ffi/c_str.rs | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs
index 4c3b77402e4..ee744b868dd 100644
--- a/src/libstd/ffi/c_str.rs
+++ b/src/libstd/ffi/c_str.rs
@@ -219,10 +219,10 @@ impl CString {
CString { inner: v.into_boxed_slice() }
}
- /// Retakes ownership of a CString that was transferred to C.
+ /// Retakes ownership of a `CString` that was transferred to C.
///
/// This should only ever be called with a pointer that was earlier
- /// obtained by calling `into_raw` on a CString. Additionally, the length
+ /// obtained by calling `into_raw` on a `CString`. Additionally, the length
/// of the string will be recalculated from the pointer.
#[stable(feature = "cstr_memory", since = "1.4.0")]
pub unsafe fn from_raw(ptr: *mut c_char) -> CString {