diff --git a/src/librustrt/c_str.rs b/src/librustrt/c_str.rs index 5e0004f2a2a..04a4e96ecc4 100644 --- a/src/librustrt/c_str.rs +++ b/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 hash::Hash 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.