library/alloc/src/ffi/c_str.rs

   1 #[cfg(test)]
   2 mod tests;
   3
   4 use crate::borrow::{Cow, ToOwned};
   5 use crate::boxed::Box;
   6 use crate::rc::Rc;
   7 use crate::slice::hack::into_vec;
   8 use crate::string::String;
   9 use crate::vec::Vec;
  10 use core::borrow::Borrow;
  11 use core::ffi::{c_char, CStr};
  12 use core::fmt;
  13 use core::mem;
  14 use core::num::NonZeroU8;
  15 use core::ops;
  16 use core::ptr;
  17 use core::slice;
  18 use core::slice::memchr;
  19 use core::str::{self, Utf8Error};
  20
  21 #[cfg(target_has_atomic = "ptr")]
  22 use crate::sync::Arc;
  23
  24 /// A type representing an owned, C-compatible, nul-terminated string with no nul bytes in the
  25 /// middle.
  26 ///
  27 /// This type serves the purpose of being able to safely generate a
  28 /// C-compatible string from a Rust byte slice or vector. An instance of this
  29 /// type is a static guarantee that the underlying bytes contain no interior 0
  30 /// bytes ("nul characters") and that the final byte is 0 ("nul terminator").
  31 ///
  32 /// `CString` is to <code>&[CStr]</code> as [`String`] is to <code>&[str]</code>: the former
  33 /// in each pair are owned strings; the latter are borrowed
  34 /// references.
  35 ///
  36 /// # Creating a `CString`
  37 ///
  38 /// A `CString` is created from either a byte slice or a byte vector,
  39 /// or anything that implements <code>[Into]<[Vec]<[u8]>></code> (for
  40 /// example, you can build a `CString` straight out of a [`String`] or
  41 /// a <code>&[str]</code>, since both implement that trait).
  42 ///
  43 /// The [`CString::new`] method will actually check that the provided <code>&[[u8]]</code>
  44 /// does not have 0 bytes in the middle, and return an error if it
  45 /// finds one.
  46 ///
  47 /// # Extracting a raw pointer to the whole C string
  48 ///
  49 /// `CString` implements an [`as_ptr`][`CStr::as_ptr`] method through the [`Deref`]
  50 /// trait. This method will give you a `*const c_char` which you can
  51 /// feed directly to extern functions that expect a nul-terminated
  52 /// string, like C's `strdup()`. Notice that [`as_ptr`][`CStr::as_ptr`] returns a
  53 /// read-only pointer; if the C code writes to it, that causes
  54 /// undefined behavior.
  55 ///
  56 /// # Extracting a slice of the whole C string
  57 ///
  58 /// Alternatively, you can obtain a <code>&[[u8]]</code> slice from a
  59 /// `CString` with the [`CString::as_bytes`] method. Slices produced in this
  60 /// way do *not* contain the trailing nul terminator. This is useful
  61 /// when you will be calling an extern function that takes a `*const
  62 /// u8` argument which is not necessarily nul-terminated, plus another
  63 /// argument with the length of the string — like C's `strndup()`.
  64 /// You can of course get the slice's length with its
  65 /// [`len`][slice::len] method.
  66 ///
  67 /// If you need a <code>&[[u8]]</code> slice *with* the nul terminator, you
  68 /// can use [`CString::as_bytes_with_nul`] instead.
  69 ///
  70 /// Once you have the kind of slice you need (with or without a nul
  71 /// terminator), you can call the slice's own
  72 /// [`as_ptr`][slice::as_ptr] method to get a read-only raw pointer to pass to
  73 /// extern functions. See the documentation for that function for a
  74 /// discussion on ensuring the lifetime of the raw pointer.
  75 ///
  76 /// [str]: prim@str "str"
  77 /// [`Deref`]: ops::Deref
  78 ///
  79 /// # Examples
  80 ///
  81 /// ```ignore (extern-declaration)
  82 /// # fn main() {
  83 /// use std::ffi::CString;
  84 /// use std::os::raw::c_char;
  85 ///
  86 /// extern "C" {
  87 ///     fn my_printer(s: *const c_char);
  88 /// }
  89 ///
  90 /// // We are certain that our string doesn't have 0 bytes in the middle,
  91 /// // so we can .expect()
  92 /// let c_to_print = CString::new("Hello, world!").expect("CString::new failed");
  93 /// unsafe {
  94 ///     my_printer(c_to_print.as_ptr());
  95 /// }
  96 /// # }
  97 /// ```
  98 ///
  99 /// # Safety
 100 ///
 101 /// `CString` is intended for working with traditional C-style strings
 102 /// (a sequence of non-nul bytes terminated by a single nul byte); the
 103 /// primary use case for these kinds of strings is interoperating with C-like
 104 /// code. Often you will need to transfer ownership to/from that external
 105 /// code. It is strongly recommended that you thoroughly read through the
 106 /// documentation of `CString` before use, as improper ownership management
 107 /// of `CString` instances can lead to invalid memory accesses, memory leaks,
 108 /// and other memory errors.
 109 #[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)]
 110 #[cfg_attr(not(test), rustc_diagnostic_item = "cstring_type")]
 111 #[unstable(feature = "alloc_c_string", issue = "94079")]
 112 pub struct CString {
 113     // Invariant 1: the slice ends with a zero byte and has a length of at least one.
 114     // Invariant 2: the slice contains only one zero byte.
 115     // Improper usage of unsafe function can break Invariant 2, but not Invariant 1.
 116     inner: Box<[u8]>,
 117 }
 118
 119 /// An error indicating that an interior nul byte was found.
 120 ///
 121 /// While Rust strings may contain nul bytes in the middle, C strings
 122 /// can't, as that byte would effectively truncate the string.
 123 ///
 124 /// This error is created by the [`new`][`CString::new`] method on
 125 /// [`CString`]. See its documentation for more.
 126 ///
 127 /// # Examples
 128 ///
 129 /// ```
 130 /// use std::ffi::{CString, NulError};
 131 ///
 132 /// let _: NulError = CString::new(b"f\0oo".to_vec()).unwrap_err();
 133 /// ```
 134 #[derive(Clone, PartialEq, Eq, Debug)]
 135 #[unstable(feature = "alloc_c_string", issue = "94079")]
 136 pub struct NulError(usize, Vec<u8>);
 137
 138 #[derive(Clone, PartialEq, Eq, Debug)]
 139 enum FromBytesWithNulErrorKind {
 140     InteriorNul(usize),
 141     NotNulTerminated,
 142 }
 143
 144 /// An error indicating that a nul byte was not in the expected position.
 145 ///
 146 /// The vector used to create a [`CString`] must have one and only one nul byte,
 147 /// positioned at the end.
 148 ///
 149 /// This error is created by the [`CString::from_vec_with_nul`] method.
 150 /// See its documentation for more.
 151 ///
 152 /// # Examples
 153 ///
 154 /// ```
 155 /// use std::ffi::{CString, FromVecWithNulError};
 156 ///
 157 /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"f\0oo".to_vec()).unwrap_err();
 158 /// ```
 159 #[derive(Clone, PartialEq, Eq, Debug)]
 160 #[unstable(feature = "alloc_c_string", issue = "94079")]
 161 pub struct FromVecWithNulError {
 162     error_kind: FromBytesWithNulErrorKind,
 163     bytes: Vec<u8>,
 164 }
 165
 166 #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
 167 impl FromVecWithNulError {
 168     /// Returns a slice of [`u8`]s bytes that were attempted to convert to a [`CString`].
 169     ///
 170     /// # Examples
 171     ///
 172     /// Basic usage:
 173     ///
 174     /// ```
 175     /// use std::ffi::CString;
 176     ///
 177     /// // Some invalid bytes in a vector
 178     /// let bytes = b"f\0oo".to_vec();
 179     ///
 180     /// let value = CString::from_vec_with_nul(bytes.clone());
 181     ///
 182     /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes());
 183     /// ```
 184     #[must_use]
 185     #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
 186     pub fn as_bytes(&self) -> &[u8] {
 187         &self.bytes[..]
 188     }
 189
 190     /// Returns the bytes that were attempted to convert to a [`CString`].
 191     ///
 192     /// This method is carefully constructed to avoid allocation. It will
 193     /// consume the error, moving out the bytes, so that a copy of the bytes
 194     /// does not need to be made.
 195     ///
 196     /// # Examples
 197     ///
 198     /// Basic usage:
 199     ///
 200     /// ```
 201     /// use std::ffi::CString;
 202     ///
 203     /// // Some invalid bytes in a vector
 204     /// let bytes = b"f\0oo".to_vec();
 205     ///
 206     /// let value = CString::from_vec_with_nul(bytes.clone());
 207     ///
 208     /// assert_eq!(bytes, value.unwrap_err().into_bytes());
 209     /// ```
 210     #[must_use = "`self` will be dropped if the result is not used"]
 211     #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
 212     pub fn into_bytes(self) -> Vec<u8> {
 213         self.bytes
 214     }
 215 }
 216
 217 /// An error indicating invalid UTF-8 when converting a [`CString`] into a [`String`].
 218 ///
 219 /// `CString` is just a wrapper over a buffer of bytes with a nul terminator;
 220 /// [`CString::into_string`] performs UTF-8 validation on those bytes and may
 221 /// return this error.
 222 ///
 223 /// This `struct` is created by [`CString::into_string()`]. See
 224 /// its documentation for more.
 225 #[derive(Clone, PartialEq, Eq, Debug)]
 226 #[unstable(feature = "alloc_c_string", issue = "94079")]
 227 pub struct IntoStringError {
 228     inner: CString,
 229     error: Utf8Error,
 230 }
 231
 232 impl CString {
 233     /// Creates a new C-compatible string from a container of bytes.
 234     ///
 235     /// This function will consume the provided data and use the
 236     /// underlying bytes to construct a new string, ensuring that
 237     /// there is a trailing 0 byte. This trailing 0 byte will be
 238     /// appended by this function; the provided data should *not*
 239     /// contain any 0 bytes in it.
 240     ///
 241     /// # Examples
 242     ///
 243     /// ```ignore (extern-declaration)
 244     /// use std::ffi::CString;
 245     /// use std::os::raw::c_char;
 246     ///
 247     /// extern "C" { fn puts(s: *const c_char); }
 248     ///
 249     /// let to_print = CString::new("Hello!").expect("CString::new failed");
 250     /// unsafe {
 251     ///     puts(to_print.as_ptr());
 252     /// }
 253     /// ```
 254     ///
 255     /// # Errors
 256     ///
 257     /// This function will return an error if the supplied bytes contain an
 258     /// internal 0 byte. The [`NulError`] returned will contain the bytes as well as
 259     /// the position of the nul byte.
 260     #[stable(feature = "rust1", since = "1.0.0")]
 261     pub fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> {
 262         trait SpecNewImpl {
 263             fn spec_new_impl(self) -> Result<CString, NulError>;
 264         }
 265
 266         impl<T: Into<Vec<u8>>> SpecNewImpl for T {
 267             default fn spec_new_impl(self) -> Result<CString, NulError> {
 268                 let bytes: Vec<u8> = self.into();
 269                 match memchr::memchr(0, &bytes) {
 270                     Some(i) => Err(NulError(i, bytes)),
 271                     None => Ok(unsafe { CString::_from_vec_unchecked(bytes) }),
 272                 }
 273             }
 274         }
 275
 276         // Specialization for avoiding reallocation
 277         #[inline(always)] // Without that it is not inlined into specializations
 278         fn spec_new_impl_bytes(bytes: &[u8]) -> Result<CString, NulError> {
 279             // We cannot have such large slice that we would overflow here
 280             // but using `checked_add` allows LLVM to assume that capacity never overflows
 281             // and generate twice shorter code.
 282             // `saturating_add` doesn't help for some reason.
 283             let capacity = bytes.len().checked_add(1).unwrap();
 284
 285             // Allocate before validation to avoid duplication of allocation code.
 286             // We still need to allocate and copy memory even if we get an error.
 287             let mut buffer = Vec::with_capacity(capacity);
 288             buffer.extend(bytes);
 289
 290             // Check memory of self instead of new buffer.
 291             // This allows better optimizations if lto enabled.
 292             match memchr::memchr(0, bytes) {
 293                 Some(i) => Err(NulError(i, buffer)),
 294                 None => Ok(unsafe { CString::_from_vec_unchecked(buffer) }),
 295             }
 296         }
 297
 298         impl SpecNewImpl for &'_ [u8] {
 299             fn spec_new_impl(self) -> Result<CString, NulError> {
 300                 spec_new_impl_bytes(self)
 301             }
 302         }
 303
 304         impl SpecNewImpl for &'_ str {
 305             fn spec_new_impl(self) -> Result<CString, NulError> {
 306                 spec_new_impl_bytes(self.as_bytes())
 307             }
 308         }
 309
 310         impl SpecNewImpl for &'_ mut [u8] {
 311             fn spec_new_impl(self) -> Result<CString, NulError> {
 312                 spec_new_impl_bytes(self)
 313             }
 314         }
 315
 316         t.spec_new_impl()
 317     }
 318
 319     /// Creates a C-compatible string by consuming a byte vector,
 320     /// without checking for interior 0 bytes.
 321     ///
 322     /// Trailing 0 byte will be appended by this function.
 323     ///
 324     /// This method is equivalent to [`CString::new`] except that no runtime
 325     /// assertion is made that `v` contains no 0 bytes, and it requires an
 326     /// actual byte vector, not anything that can be converted to one with Into.
 327     ///
 328     /// # Examples
 329     ///
 330     /// ```
 331     /// use std::ffi::CString;
 332     ///
 333     /// let raw = b"foo".to_vec();
 334     /// unsafe {
 335     ///     let c_string = CString::from_vec_unchecked(raw);
 336     /// }
 337     /// ```
 338     #[must_use]
 339     #[stable(feature = "rust1", since = "1.0.0")]
 340     pub unsafe fn from_vec_unchecked(v: Vec<u8>) -> Self {
 341         debug_assert!(memchr::memchr(0, &v).is_none());
 342         unsafe { Self::_from_vec_unchecked(v) }
 343     }
 344
 345     unsafe fn _from_vec_unchecked(mut v: Vec<u8>) -> Self {
 346         v.reserve_exact(1);
 347         v.push(0);
 348         Self { inner: v.into_boxed_slice() }
 349     }
 350
 351     /// Retakes ownership of a `CString` that was transferred to C via
 352     /// [`CString::into_raw`].
 353     ///
 354     /// Additionally, the length of the string will be recalculated from the pointer.
 355     ///
 356     /// # Safety
 357     ///
 358     /// This should only ever be called with a pointer that was earlier
 359     /// obtained by calling [`CString::into_raw`]. Other usage (e.g., trying to take
 360     /// ownership of a string that was allocated by foreign code) is likely to lead
 361     /// to undefined behavior or allocator corruption.
 362     ///
 363     /// It should be noted that the length isn't just "recomputed," but that
 364     /// the recomputed length must match the original length from the
 365     /// [`CString::into_raw`] call. This means the [`CString::into_raw`]/`from_raw`
 366     /// methods should not be used when passing the string to C functions that can
 367     /// modify the string's length.
 368     ///
 369     /// > **Note:** If you need to borrow a string that was allocated by
 370     /// > foreign code, use [`CStr`]. If you need to take ownership of
 371     /// > a string that was allocated by foreign code, you will need to
 372     /// > make your own provisions for freeing it appropriately, likely
 373     /// > with the foreign code's API to do that.
 374     ///
 375     /// # Examples
 376     ///
 377     /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake
 378     /// ownership with `from_raw`:
 379     ///
 380     /// ```ignore (extern-declaration)
 381     /// use std::ffi::CString;
 382     /// use std::os::raw::c_char;
 383     ///
 384     /// extern "C" {
 385     ///     fn some_extern_function(s: *mut c_char);
 386     /// }
 387     ///
 388     /// let c_string = CString::new("Hello!").expect("CString::new failed");
 389     /// let raw = c_string.into_raw();
 390     /// unsafe {
 391     ///     some_extern_function(raw);
 392     ///     let c_string = CString::from_raw(raw);
 393     /// }
 394     /// ```
 395     #[must_use = "call `drop(from_raw(ptr))` if you intend to drop the `CString`"]
 396     #[stable(feature = "cstr_memory", since = "1.4.0")]
 397     pub unsafe fn from_raw(ptr: *mut c_char) -> CString {
 398         // SAFETY: This is called with a pointer that was obtained from a call
 399         // to `CString::into_raw` and the length has not been modified. As such,
 400         // we know there is a NUL byte (and only one) at the end and that the
 401         // information about the size of the allocation is correct on Rust's
 402         // side.
 403         unsafe {
 404             extern "C" {
 405                 /// Provided by libc or compiler_builtins.
 406                 fn strlen(s: *const c_char) -> usize;
 407             }
 408             let len = strlen(ptr) + 1; // Including the NUL byte
 409             let slice = slice::from_raw_parts_mut(ptr, len as usize);
 410             CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) }
 411         }
 412     }
 413
 414     /// Consumes the `CString` and transfers ownership of the string to a C caller.
 415     ///
 416     /// The pointer which this function returns must be returned to Rust and reconstituted using
 417     /// [`CString::from_raw`] to be properly deallocated. Specifically, one
 418     /// should *not* use the standard C `free()` function to deallocate
 419     /// this string.
 420     ///
 421     /// Failure to call [`CString::from_raw`] will lead to a memory leak.
 422     ///
 423     /// The C side must **not** modify the length of the string (by writing a
 424     /// `null` somewhere inside the string or removing the final one) before
 425     /// it makes it back into Rust using [`CString::from_raw`]. See the safety section
 426     /// in [`CString::from_raw`].
 427     ///
 428     /// # Examples
 429     ///
 430     /// ```
 431     /// use std::ffi::CString;
 432     ///
 433     /// let c_string = CString::new("foo").expect("CString::new failed");
 434     ///
 435     /// let ptr = c_string.into_raw();
 436     ///
 437     /// unsafe {
 438     ///     assert_eq!(b'f', *ptr as u8);
 439     ///     assert_eq!(b'o', *ptr.offset(1) as u8);
 440     ///     assert_eq!(b'o', *ptr.offset(2) as u8);
 441     ///     assert_eq!(b'\0', *ptr.offset(3) as u8);
 442     ///
 443     ///     // retake pointer to free memory
 444     ///     let _ = CString::from_raw(ptr);
 445     /// }
 446     /// ```
 447     #[inline]
 448     #[must_use = "`self` will be dropped if the result is not used"]
 449     #[stable(feature = "cstr_memory", since = "1.4.0")]
 450     pub fn into_raw(self) -> *mut c_char {
 451         Box::into_raw(self.into_inner()) as *mut c_char
 452     }
 453
 454     /// Converts the `CString` into a [`String`] if it contains valid UTF-8 data.
 455     ///
 456     /// On failure, ownership of the original `CString` is returned.
 457     ///
 458     /// # Examples
 459     ///
 460     /// ```
 461     /// use std::ffi::CString;
 462     ///
 463     /// let valid_utf8 = vec![b'f', b'o', b'o'];
 464     /// let cstring = CString::new(valid_utf8).expect("CString::new failed");
 465     /// assert_eq!(cstring.into_string().expect("into_string() call failed"), "foo");
 466     ///
 467     /// let invalid_utf8 = vec![b'f', 0xff, b'o', b'o'];
 468     /// let cstring = CString::new(invalid_utf8).expect("CString::new failed");
 469     /// let err = cstring.into_string().err().expect("into_string().err() failed");
 470     /// assert_eq!(err.utf8_error().valid_up_to(), 1);
 471     /// ```
 472     #[stable(feature = "cstring_into", since = "1.7.0")]
 473     pub fn into_string(self) -> Result<String, IntoStringError> {
 474         String::from_utf8(self.into_bytes()).map_err(|e| IntoStringError {
 475             error: e.utf8_error(),
 476             inner: unsafe { Self::_from_vec_unchecked(e.into_bytes()) },
 477         })
 478     }
 479
 480     /// Consumes the `CString` and returns the underlying byte buffer.
 481     ///
 482     /// The returned buffer does **not** contain the trailing nul
 483     /// terminator, and it is guaranteed to not have any interior nul
 484     /// bytes.
 485     ///
 486     /// # Examples
 487     ///
 488     /// ```
 489     /// use std::ffi::CString;
 490     ///
 491     /// let c_string = CString::new("foo").expect("CString::new failed");
 492     /// let bytes = c_string.into_bytes();
 493     /// assert_eq!(bytes, vec![b'f', b'o', b'o']);
 494     /// ```
 495     #[must_use = "`self` will be dropped if the result is not used"]
 496     #[stable(feature = "cstring_into", since = "1.7.0")]
 497     pub fn into_bytes(self) -> Vec<u8> {
 498         let mut vec = into_vec(self.into_inner());
 499         let _nul = vec.pop();
 500         debug_assert_eq!(_nul, Some(0u8));
 501         vec
 502     }
 503
 504     /// Equivalent to [`CString::into_bytes()`] except that the
 505     /// returned vector includes the trailing nul terminator.
 506     ///
 507     /// # Examples
 508     ///
 509     /// ```
 510     /// use std::ffi::CString;
 511     ///
 512     /// let c_string = CString::new("foo").expect("CString::new failed");
 513     /// let bytes = c_string.into_bytes_with_nul();
 514     /// assert_eq!(bytes, vec![b'f', b'o', b'o', b'\0']);
 515     /// ```
 516     #[must_use = "`self` will be dropped if the result is not used"]
 517     #[stable(feature = "cstring_into", since = "1.7.0")]
 518     pub fn into_bytes_with_nul(self) -> Vec<u8> {
 519         into_vec(self.into_inner())
 520     }
 521
 522     /// Returns the contents of this `CString` as a slice of bytes.
 523     ///
 524     /// The returned slice does **not** contain the trailing nul
 525     /// terminator, and it is guaranteed to not have any interior nul
 526     /// bytes. If you need the nul terminator, use
 527     /// [`CString::as_bytes_with_nul`] instead.
 528     ///
 529     /// # Examples
 530     ///
 531     /// ```
 532     /// use std::ffi::CString;
 533     ///
 534     /// let c_string = CString::new("foo").expect("CString::new failed");
 535     /// let bytes = c_string.as_bytes();
 536     /// assert_eq!(bytes, &[b'f', b'o', b'o']);
 537     /// ```
 538     #[inline]
 539     #[must_use]
 540     #[stable(feature = "rust1", since = "1.0.0")]
 541     pub fn as_bytes(&self) -> &[u8] {
 542         // SAFETY: CString has a length at least 1
 543         unsafe { self.inner.get_unchecked(..self.inner.len() - 1) }
 544     }
 545
 546     /// Equivalent to [`CString::as_bytes()`] except that the
 547     /// returned slice includes the trailing nul terminator.
 548     ///
 549     /// # Examples
 550     ///
 551     /// ```
 552     /// use std::ffi::CString;
 553     ///
 554     /// let c_string = CString::new("foo").expect("CString::new failed");
 555     /// let bytes = c_string.as_bytes_with_nul();
 556     /// assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']);
 557     /// ```
 558     #[inline]
 559     #[must_use]
 560     #[stable(feature = "rust1", since = "1.0.0")]
 561     pub fn as_bytes_with_nul(&self) -> &[u8] {
 562         &self.inner
 563     }
 564
 565     /// Extracts a [`CStr`] slice containing the entire string.
 566     ///
 567     /// # Examples
 568     ///
 569     /// ```
 570     /// use std::ffi::{CString, CStr};
 571     ///
 572     /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed");
 573     /// let cstr = c_string.as_c_str();
 574     /// assert_eq!(cstr,
 575     ///            CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"));
 576     /// ```
 577     #[inline]
 578     #[must_use]
 579     #[stable(feature = "as_c_str", since = "1.20.0")]
 580     pub fn as_c_str(&self) -> &CStr {
 581         &*self
 582     }
 583
 584     /// Converts this `CString` into a boxed [`CStr`].
 585     ///
 586     /// # Examples
 587     ///
 588     /// ```
 589     /// use std::ffi::{CString, CStr};
 590     ///
 591     /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed");
 592     /// let boxed = c_string.into_boxed_c_str();
 593     /// assert_eq!(&*boxed,
 594     ///            CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"));
 595     /// ```
 596     #[must_use = "`self` will be dropped if the result is not used"]
 597     #[stable(feature = "into_boxed_c_str", since = "1.20.0")]
 598     pub fn into_boxed_c_str(self) -> Box<CStr> {
 599         unsafe { Box::from_raw(Box::into_raw(self.into_inner()) as *mut CStr) }
 600     }
 601
 602     /// Bypass "move out of struct which implements [`Drop`] trait" restriction.
 603     #[inline]
 604     fn into_inner(self) -> Box<[u8]> {
 605         // Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)`
 606         // so we use `ManuallyDrop` to ensure `self` is not dropped.
 607         // Then we can return the box directly without invalidating it.
 608         // See https://github.com/rust-lang/rust/issues/62553.
 609         let this = mem::ManuallyDrop::new(self);
 610         unsafe { ptr::read(&this.inner) }
 611     }
 612
 613     /// Converts a <code>[Vec]<[u8]></code> to a [`CString`] without checking the
 614     /// invariants on the given [`Vec`].
 615     ///
 616     /// # Safety
 617     ///
 618     /// The given [`Vec`] **must** have one nul byte as its last element.
 619     /// This means it cannot be empty nor have any other nul byte anywhere else.
 620     ///
 621     /// # Example
 622     ///
 623     /// ```
 624     /// use std::ffi::CString;
 625     /// assert_eq!(
 626     ///     unsafe { CString::from_vec_with_nul_unchecked(b"abc\0".to_vec()) },
 627     ///     unsafe { CString::from_vec_unchecked(b"abc".to_vec()) }
 628     /// );
 629     /// ```
 630     #[must_use]
 631     #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
 632     pub unsafe fn from_vec_with_nul_unchecked(v: Vec<u8>) -> Self {
 633         debug_assert!(memchr::memchr(0, &v).unwrap() + 1 == v.len());
 634         unsafe { Self::_from_vec_with_nul_unchecked(v) }
 635     }
 636
 637     unsafe fn _from_vec_with_nul_unchecked(v: Vec<u8>) -> Self {
 638         Self { inner: v.into_boxed_slice() }
 639     }
 640
 641     /// Attempts to converts a <code>[Vec]<[u8]></code> to a [`CString`].
 642     ///
 643     /// Runtime checks are present to ensure there is only one nul byte in the
 644     /// [`Vec`], its last element.
 645     ///
 646     /// # Errors
 647     ///
 648     /// If a nul byte is present and not the last element or no nul bytes
 649     /// is present, an error will be returned.
 650     ///
 651     /// # Examples
 652     ///
 653     /// A successful conversion will produce the same result as [`CString::new`]
 654     /// when called without the ending nul byte.
 655     ///
 656     /// ```
 657     /// use std::ffi::CString;
 658     /// assert_eq!(
 659     ///     CString::from_vec_with_nul(b"abc\0".to_vec())
 660     ///         .expect("CString::from_vec_with_nul failed"),
 661     ///     CString::new(b"abc".to_vec()).expect("CString::new failed")
 662     /// );
 663     /// ```
 664     ///
 665     /// An incorrectly formatted [`Vec`] will produce an error.
 666     ///
 667     /// ```
 668     /// use std::ffi::{CString, FromVecWithNulError};
 669     /// // Interior nul byte
 670     /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"a\0bc".to_vec()).unwrap_err();
 671     /// // No nul byte
 672     /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err();
 673     /// ```
 674     #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
 675     pub fn from_vec_with_nul(v: Vec<u8>) -> Result<Self, FromVecWithNulError> {
 676         let nul_pos = memchr::memchr(0, &v);
 677         match nul_pos {
 678             Some(nul_pos) if nul_pos + 1 == v.len() => {
 679                 // SAFETY: We know there is only one nul byte, at the end
 680                 // of the vec.
 681                 Ok(unsafe { Self::_from_vec_with_nul_unchecked(v) })
 682             }
 683             Some(nul_pos) => Err(FromVecWithNulError {
 684                 error_kind: FromBytesWithNulErrorKind::InteriorNul(nul_pos),
 685                 bytes: v,
 686             }),
 687             None => Err(FromVecWithNulError {
 688                 error_kind: FromBytesWithNulErrorKind::NotNulTerminated,
 689                 bytes: v,
 690             }),
 691         }
 692     }
 693 }
 694
 695 // Turns this `CString` into an empty string to prevent
 696 // memory-unsafe code from working by accident. Inline
 697 // to prevent LLVM from optimizing it away in debug builds.
 698 #[stable(feature = "cstring_drop", since = "1.13.0")]
 699 impl Drop for CString {
 700     #[inline]
 701     fn drop(&mut self) {
 702         unsafe {
 703             *self.inner.get_unchecked_mut(0) = 0;
 704         }
 705     }
 706 }
 707
 708 #[stable(feature = "rust1", since = "1.0.0")]
 709 impl ops::Deref for CString {
 710     type Target = CStr;
 711
 712     #[inline]
 713     fn deref(&self) -> &CStr {
 714         unsafe { CStr::from_bytes_with_nul_unchecked(self.as_bytes_with_nul()) }
 715     }
 716 }
 717
 718 #[stable(feature = "rust1", since = "1.0.0")]
 719 impl fmt::Debug for CString {
 720     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 721         fmt::Debug::fmt(&**self, f)
 722     }
 723 }
 724
 725 #[stable(feature = "cstring_into", since = "1.7.0")]
 726 impl From<CString> for Vec<u8> {
 727     /// Converts a [`CString`] into a <code>[Vec]<[u8]></code>.
 728     ///
 729     /// The conversion consumes the [`CString`], and removes the terminating NUL byte.
 730     #[inline]
 731     fn from(s: CString) -> Vec<u8> {
 732         s.into_bytes()
 733     }
 734 }
 735
 736 #[stable(feature = "cstr_default", since = "1.10.0")]
 737 impl Default for CString {
 738     /// Creates an empty `CString`.
 739     fn default() -> CString {
 740         let a: &CStr = Default::default();
 741         a.to_owned()
 742     }
 743 }
 744
 745 #[stable(feature = "cstr_borrow", since = "1.3.0")]
 746 impl Borrow<CStr> for CString {
 747     #[inline]
 748     fn borrow(&self) -> &CStr {
 749         self
 750     }
 751 }
 752
 753 #[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")]
 754 impl<'a> From<Cow<'a, CStr>> for CString {
 755     /// Converts a `Cow<'a, CStr>` into a `CString`, by copying the contents if they are
 756     /// borrowed.
 757     #[inline]
 758     fn from(s: Cow<'a, CStr>) -> Self {
 759         s.into_owned()
 760     }
 761 }
 762
 763 #[cfg(not(test))]
 764 #[stable(feature = "box_from_c_str", since = "1.17.0")]
 765 impl From<&CStr> for Box<CStr> {
 766     /// Converts a `&CStr` into a `Box<CStr>`,
 767     /// by copying the contents into a newly allocated [`Box`].
 768     fn from(s: &CStr) -> Box<CStr> {
 769         let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul());
 770         unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
 771     }
 772 }
 773
 774 #[stable(feature = "box_from_cow", since = "1.45.0")]
 775 impl From<Cow<'_, CStr>> for Box<CStr> {
 776     /// Converts a `Cow<'a, CStr>` into a `Box<CStr>`,
 777     /// by copying the contents if they are borrowed.
 778     #[inline]
 779     fn from(cow: Cow<'_, CStr>) -> Box<CStr> {
 780         match cow {
 781             Cow::Borrowed(s) => Box::from(s),
 782             Cow::Owned(s) => Box::from(s),
 783         }
 784     }
 785 }
 786
 787 #[stable(feature = "c_string_from_box", since = "1.18.0")]
 788 impl From<Box<CStr>> for CString {
 789     /// Converts a <code>[Box]<[CStr]></code> into a [`CString`] without copying or allocating.
 790     #[inline]
 791     fn from(s: Box<CStr>) -> CString {
 792         let raw = Box::into_raw(s) as *mut [u8];
 793         CString { inner: unsafe { Box::from_raw(raw) } }
 794     }
 795 }
 796
 797 #[stable(feature = "cstring_from_vec_of_nonzerou8", since = "1.43.0")]
 798 impl From<Vec<NonZeroU8>> for CString {
 799     /// Converts a <code>[Vec]<[NonZeroU8]></code> into a [`CString`] without
 800     /// copying nor checking for inner null bytes.
 801     #[inline]
 802     fn from(v: Vec<NonZeroU8>) -> CString {
 803         unsafe {
 804             // Transmute `Vec<NonZeroU8>` to `Vec<u8>`.
 805             let v: Vec<u8> = {
 806                 // SAFETY:
 807                 //   - transmuting between `NonZeroU8` and `u8` is sound;
 808                 //   - `alloc::Layout<NonZeroU8> == alloc::Layout<u8>`.
 809                 let (ptr, len, cap): (*mut NonZeroU8, _, _) = Vec::into_raw_parts(v);
 810                 Vec::from_raw_parts(ptr.cast::<u8>(), len, cap)
 811             };
 812             // SAFETY: `v` cannot contain null bytes, given the type-level
 813             // invariant of `NonZeroU8`.
 814             Self::_from_vec_unchecked(v)
 815         }
 816     }
 817 }
 818
 819 #[cfg(not(test))]
 820 #[stable(feature = "more_box_slice_clone", since = "1.29.0")]
 821 impl Clone for Box<CStr> {
 822     #[inline]
 823     fn clone(&self) -> Self {
 824         (**self).into()
 825     }
 826 }
 827
 828 #[stable(feature = "box_from_c_string", since = "1.20.0")]
 829 impl From<CString> for Box<CStr> {
 830     /// Converts a [`CString`] into a <code>[Box]<[CStr]></code> without copying or allocating.
 831     #[inline]
 832     fn from(s: CString) -> Box<CStr> {
 833         s.into_boxed_c_str()
 834     }
 835 }
 836
 837 #[stable(feature = "cow_from_cstr", since = "1.28.0")]
 838 impl<'a> From<CString> for Cow<'a, CStr> {
 839     /// Converts a [`CString`] into an owned [`Cow`] without copying or allocating.
 840     #[inline]
 841     fn from(s: CString) -> Cow<'a, CStr> {
 842         Cow::Owned(s)
 843     }
 844 }
 845
 846 #[stable(feature = "cow_from_cstr", since = "1.28.0")]
 847 impl<'a> From<&'a CStr> for Cow<'a, CStr> {
 848     /// Converts a [`CStr`] into a borrowed [`Cow`] without copying or allocating.
 849     #[inline]
 850     fn from(s: &'a CStr) -> Cow<'a, CStr> {
 851         Cow::Borrowed(s)
 852     }
 853 }
 854
 855 #[stable(feature = "cow_from_cstr", since = "1.28.0")]
 856 impl<'a> From<&'a CString> for Cow<'a, CStr> {
 857     /// Converts a `&`[`CString`] into a borrowed [`Cow`] without copying or allocating.
 858     #[inline]
 859     fn from(s: &'a CString) -> Cow<'a, CStr> {
 860         Cow::Borrowed(s.as_c_str())
 861     }
 862 }
 863
 864 #[cfg(target_has_atomic = "ptr")]
 865 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
 866 impl From<CString> for Arc<CStr> {
 867     /// Converts a [`CString`] into an <code>[Arc]<[CStr]></code> by moving the [`CString`]
 868     /// data into a new [`Arc`] buffer.
 869     #[inline]
 870     fn from(s: CString) -> Arc<CStr> {
 871         let arc: Arc<[u8]> = Arc::from(s.into_inner());
 872         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) }
 873     }
 874 }
 875
 876 #[cfg(target_has_atomic = "ptr")]
 877 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
 878 impl From<&CStr> for Arc<CStr> {
 879     /// Converts a `&CStr` into a `Arc<CStr>`,
 880     /// by copying the contents into a newly allocated [`Arc`].
 881     #[inline]
 882     fn from(s: &CStr) -> Arc<CStr> {
 883         let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul());
 884         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) }
 885     }
 886 }
 887
 888 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
 889 impl From<CString> for Rc<CStr> {
 890     /// Converts a [`CString`] into an <code>[Rc]<[CStr]></code> by moving the [`CString`]
 891     /// data into a new [`Arc`] buffer.
 892     #[inline]
 893     fn from(s: CString) -> Rc<CStr> {
 894         let rc: Rc<[u8]> = Rc::from(s.into_inner());
 895         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) }
 896     }
 897 }
 898
 899 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
 900 impl From<&CStr> for Rc<CStr> {
 901     /// Converts a `&CStr` into a `Rc<CStr>`,
 902     /// by copying the contents into a newly allocated [`Rc`].
 903     #[inline]
 904     fn from(s: &CStr) -> Rc<CStr> {
 905         let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul());
 906         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) }
 907     }
 908 }
 909
 910 #[cfg(not(test))]
 911 #[stable(feature = "default_box_extra", since = "1.17.0")]
 912 impl Default for Box<CStr> {
 913     fn default() -> Box<CStr> {
 914         let boxed: Box<[u8]> = Box::from([0]);
 915         unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
 916     }
 917 }
 918
 919 impl NulError {
 920     /// Returns the position of the nul byte in the slice that caused
 921     /// [`CString::new`] to fail.
 922     ///
 923     /// # Examples
 924     ///
 925     /// ```
 926     /// use std::ffi::CString;
 927     ///
 928     /// let nul_error = CString::new("foo\0bar").unwrap_err();
 929     /// assert_eq!(nul_error.nul_position(), 3);
 930     ///
 931     /// let nul_error = CString::new("foo bar\0").unwrap_err();
 932     /// assert_eq!(nul_error.nul_position(), 7);
 933     /// ```
 934     #[must_use]
 935     #[stable(feature = "rust1", since = "1.0.0")]
 936     pub fn nul_position(&self) -> usize {
 937         self.0
 938     }
 939
 940     /// Consumes this error, returning the underlying vector of bytes which
 941     /// generated the error in the first place.
 942     ///
 943     /// # Examples
 944     ///
 945     /// ```
 946     /// use std::ffi::CString;
 947     ///
 948     /// let nul_error = CString::new("foo\0bar").unwrap_err();
 949     /// assert_eq!(nul_error.into_vec(), b"foo\0bar");
 950     /// ```
 951     #[must_use = "`self` will be dropped if the result is not used"]
 952     #[stable(feature = "rust1", since = "1.0.0")]
 953     pub fn into_vec(self) -> Vec<u8> {
 954         self.1
 955     }
 956 }
 957
 958 #[stable(feature = "rust1", since = "1.0.0")]
 959 impl fmt::Display for NulError {
 960     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 961         write!(f, "nul byte found in provided data at position: {}", self.0)
 962     }
 963 }
 964
 965 #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
 966 impl fmt::Display for FromVecWithNulError {
 967     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 968         match self.error_kind {
 969             FromBytesWithNulErrorKind::InteriorNul(pos) => {
 970                 write!(f, "data provided contains an interior nul byte at pos {pos}")
 971             }
 972             FromBytesWithNulErrorKind::NotNulTerminated => {
 973                 write!(f, "data provided is not nul terminated")
 974             }
 975         }
 976     }
 977 }
 978
 979 impl IntoStringError {
 980     /// Consumes this error, returning original [`CString`] which generated the
 981     /// error.
 982     #[must_use = "`self` will be dropped if the result is not used"]
 983     #[stable(feature = "cstring_into", since = "1.7.0")]
 984     pub fn into_cstring(self) -> CString {
 985         self.inner
 986     }
 987
 988     /// Access the underlying UTF-8 error that was the cause of this error.
 989     #[must_use]
 990     #[stable(feature = "cstring_into", since = "1.7.0")]
 991     pub fn utf8_error(&self) -> Utf8Error {
 992         self.error
 993     }
 994
 995     #[doc(hidden)]
 996     #[unstable(feature = "cstr_internals", issue = "none")]
 997     pub fn __source(&self) -> &Utf8Error {
 998         &self.error
 999     }
1000 }
1001
1002 impl IntoStringError {
1003     fn description(&self) -> &str {
1004         "C string contained non-utf8 bytes"
1005     }
1006 }
1007
1008 #[stable(feature = "cstring_into", since = "1.7.0")]
1009 impl fmt::Display for IntoStringError {
1010     #[allow(deprecated, deprecated_in_future)]
1011     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1012         self.description().fmt(f)
1013     }
1014 }
1015
1016 #[stable(feature = "cstr_borrow", since = "1.3.0")]
1017 impl ToOwned for CStr {
1018     type Owned = CString;
1019
1020     fn to_owned(&self) -> CString {
1021         CString { inner: self.to_bytes_with_nul().into() }
1022     }
1023
1024     fn clone_into(&self, target: &mut CString) {
1025         let mut b = into_vec(mem::take(&mut target.inner));
1026         self.to_bytes_with_nul().clone_into(&mut b);
1027         target.inner = b.into_boxed_slice();
1028     }
1029 }
1030
1031 #[stable(feature = "cstring_asref", since = "1.7.0")]
1032 impl From<&CStr> for CString {
1033     fn from(s: &CStr) -> CString {
1034         s.to_owned()
1035     }
1036 }
1037
1038 #[stable(feature = "cstring_asref", since = "1.7.0")]
1039 impl ops::Index<ops::RangeFull> for CString {
1040     type Output = CStr;
1041
1042     #[inline]
1043     fn index(&self, _index: ops::RangeFull) -> &CStr {
1044         self
1045     }
1046 }
1047
1048 #[stable(feature = "cstring_asref", since = "1.7.0")]
1049 impl AsRef<CStr> for CString {
1050     #[inline]
1051     fn as_ref(&self) -> &CStr {
1052         self
1053     }
1054 }
1055
1056 #[cfg(not(test))]
1057 impl CStr {
1058     /// Converts a `CStr` into a <code>[Cow]<[str]></code>.
1059     ///
1060     /// If the contents of the `CStr` are valid UTF-8 data, this
1061     /// function will return a <code>[Cow]::[Borrowed]\(&[str])</code>
1062     /// with the corresponding <code>&[str]</code> slice. Otherwise, it will
1063     /// replace any invalid UTF-8 sequences with
1064     /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a
1065     /// <code>[Cow]::[Owned]\(&[str])</code> with the result.
1066     ///
1067     /// [str]: prim@str "str"
1068     /// [Borrowed]: Cow::Borrowed
1069     /// [Owned]: Cow::Owned
1070     /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER "std::char::REPLACEMENT_CHARACTER"
1071     ///
1072     /// # Examples
1073     ///
1074     /// Calling `to_string_lossy` on a `CStr` containing valid UTF-8:
1075     ///
1076     /// ```
1077     /// use std::borrow::Cow;
1078     /// use std::ffi::CStr;
1079     ///
1080     /// let cstr = CStr::from_bytes_with_nul(b"Hello World\0")
1081     ///                  .expect("CStr::from_bytes_with_nul failed");
1082     /// assert_eq!(cstr.to_string_lossy(), Cow::Borrowed("Hello World"));
1083     /// ```
1084     ///
1085     /// Calling `to_string_lossy` on a `CStr` containing invalid UTF-8:
1086     ///
1087     /// ```
1088     /// use std::borrow::Cow;
1089     /// use std::ffi::CStr;
1090     ///
1091     /// let cstr = CStr::from_bytes_with_nul(b"Hello \xF0\x90\x80World\0")
1092     ///                  .expect("CStr::from_bytes_with_nul failed");
1093     /// assert_eq!(
1094     ///     cstr.to_string_lossy(),
1095     ///     Cow::Owned(String::from("Hello �World")) as Cow<'_, str>
1096     /// );
1097     /// ```
1098     #[rustc_allow_incoherent_impl]
1099     #[must_use = "this returns the result of the operation, \
1100                   without modifying the original"]
1101     #[stable(feature = "cstr_to_str", since = "1.4.0")]
1102     pub fn to_string_lossy(&self) -> Cow<'_, str> {
1103         String::from_utf8_lossy(self.to_bytes())
1104     }
1105
1106     /// Converts a <code>[Box]<[CStr]></code> into a [`CString`] without copying or allocating.
1107     ///
1108     /// # Examples
1109     ///
1110     /// ```
1111     /// use std::ffi::CString;
1112     ///
1113     /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed");
1114     /// let boxed = c_string.into_boxed_c_str();
1115     /// assert_eq!(boxed.into_c_string(), CString::new("foo").expect("CString::new failed"));
1116     /// ```
1117     #[rustc_allow_incoherent_impl]
1118     #[must_use = "`self` will be dropped if the result is not used"]
1119     #[stable(feature = "into_boxed_c_str", since = "1.20.0")]
1120     pub fn into_c_string(self: Box<Self>) -> CString {
1121         CString::from(self)
1122     }
1123 }