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