rollup merge of #17355 : gamazeps/issue17210

Author: alexcrichton

src/librustrt/c_str.rs

@@ -36,6 +36,12 @@ not tied to the lifetime of the original string/data buffer). If C strings are
 heavily used in applications, then caching may be advisable to prevent
 unnecessary amounts of allocations.
 
+Be carefull to remember that the memory is managed by C allocator API and not
+by Rust allocator API.
+That means that the CString pointers should be freed with C allocator API
+if you intend to do that on your own, as the behaviour if you free them with
+Rust's allocator API is not well defined
+
 An example of creating and using a C string would be:
 
 ```rust
@@ -91,8 +97,8 @@ pub struct CString {
 
 impl Clone for CString {
     /// Clone this CString into a new, uniquely owned CString. For safety
-    /// reasons, this is always a deep clone, rather than the usual shallow
-    /// clone.
+    /// reasons, this is always a deep clone with the memory allocated
+    /// with C's allocator API, rather than the usual shallow clone.
     fn clone(&self) -> CString {
         let len = self.len() + 1;
         let buf = unsafe { malloc_raw(len) } as *mut libc::c_char;
@@ -131,7 +137,9 @@ impl<S: hash::Writer> hash::Hash<S> for CString {
 }
 
 impl CString {
-    /// Create a C String from a pointer.
+    /// Create a C String from a pointer, with memory managed by C's allocator
+    /// API, so avoid calling it with a pointer to memory managed by Rust's
+    /// allocator API, as the behaviour would not be well defined.
     ///
     ///# Failure
     ///
@@ -265,7 +273,8 @@ impl CString {
     /// forgotten, meaning that the backing allocation of this
     /// `CString` is not automatically freed if it owns the
     /// allocation. In this case, a user of `.unwrap()` should ensure
-    /// the allocation is freed, to avoid leaking memory.
+    /// the allocation is freed, to avoid leaking memory. You should
+    /// use libc's memory allocator in this case.
     ///
     /// Prefer `.as_ptr()` when just retrieving a pointer to the
     /// string data, as that does not relinquish ownership.