Rollup merge of #54313 - cgwalters:osstr-ref-cstr, r=joshtriplett

OsStr: Document that it's not NUL terminated

I somehow got confused into thinking this was the case, but
it's definitely not.  Let's help the common case of people who
have an `OsStr` and need to call e.g. Unix APIs.

1 files changed, 4 insertions, 1 deletions

diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index 237af2f04e5..e9390630445 100644
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -34,7 +34,9 @@ use sys_common::{AsInner, IntoInner, FromInner};
 ///
 /// `OsString` and [`OsStr`] bridge this gap by simultaneously representing Rust
 /// and platform-native string values, and in particular allowing a Rust string
-/// to be converted into an "OS" string with no cost if possible.
+/// to be converted into an "OS" string with no cost if possible.  A consequence
+/// of this is that `OsString` instances are *not* `NUL` terminated; in order
+/// to pass to e.g. Unix system call, you should create a [`CStr`].
 ///
 /// `OsString` is to [`&OsStr`] as [`String`] is to [`&str`]: the former
 /// in each pair are owned strings; the latter are borrowed
@@ -65,6 +67,7 @@ use sys_common::{AsInner, IntoInner, FromInner};
 ///
 /// [`OsStr`]: struct.OsStr.html
 /// [`&OsStr`]: struct.OsStr.html
+/// [`CStr`]: struct.CStr.html
 /// [`From`]: ../convert/trait.From.html
 /// [`String`]: ../string/struct.String.html
 /// [`&str`]: ../primitive.str.html