| 1 |
/// A macro for [`CStr`] literals. |
| 2 |
/// |
| 3 |
/// This can make passing string literals to rustix APIs more efficient, since |
| 4 |
/// most underlying system calls with string arguments expect NUL-terminated |
| 5 |
/// strings, and passing strings to rustix as `CStr`s means that rustix doesn't |
| 6 |
/// need to copy them into a separate buffer to NUL-terminate them. |
| 7 |
/// |
| 8 |
/// [`CStr`]: crate::ffi::CStr |
| 9 |
/// |
| 10 |
/// # Examples |
| 11 |
/// |
| 12 |
/// ``` |
| 13 |
/// # #[cfg(feature = "fs")] |
| 14 |
/// # fn main() -> rustix::io::Result<()> { |
| 15 |
/// use rustix::cstr; |
| 16 |
/// use rustix::fs::{statat, AtFlags, CWD}; |
| 17 |
/// |
| 18 |
/// let metadata = statat(CWD, cstr!("Cargo.toml"), AtFlags::empty())?; |
| 19 |
/// # Ok(()) |
| 20 |
/// # } |
| 21 |
/// # #[cfg(not(feature = "fs"))] |
| 22 |
/// # fn main() {} |
| 23 |
/// ``` |
| 24 |
#[allow(unused_macros)] |
| 25 |
#[macro_export] |
| 26 |
macro_rules! cstr { |
| 27 |
($str:literal) => {{ |
| 28 |
// Check for NUL manually, to ensure safety. |
| 29 |
// |
| 30 |
// In release builds, with strings that don't contain NULs, this |
| 31 |
// constant-folds away. |
| 32 |
// |
| 33 |
// We don't use std's `CStr::from_bytes_with_nul`; as of this writing, |
| 34 |
// that function isn't defined as `#[inline]` in std and doesn't |
| 35 |
// constant-fold away. |
| 36 |
assert!( |
| 37 |
!$str.bytes().any(|b| b == b'\0'), |
| 38 |
"cstr argument contains embedded NUL bytes", |
| 39 |
); |
| 40 |
|
| 41 |
#[allow(unsafe_code, unused_unsafe)] |
| 42 |
{ |
| 43 |
// Now that we know the string doesn't have embedded NULs, we can |
| 44 |
// call `from_bytes_with_nul_unchecked`, which as of this writing |
| 45 |
// is defined as `#[inline]` and completely optimizes away. |
| 46 |
// |
| 47 |
// SAFETY: We have manually checked that the string does not |
| 48 |
// contain embedded NULs above, and we append or own NUL terminator |
| 49 |
// here. |
| 50 |
unsafe { |
| 51 |
$crate::ffi::CStr::from_bytes_with_nul_unchecked(concat!($str, "\0").as_bytes()) |
| 52 |
} |
| 53 |
} |
| 54 |
}}; |
| 55 |
} |
| 56 |
|
| 57 |
#[test] |
| 58 |
fn test_cstr() { |
| 59 |
use crate::ffi::CString; |
| 60 |
use alloc::borrow::ToOwned; |
| 61 |
assert_eq!(cstr!(""), &*CString::new("").unwrap()); |
| 62 |
assert_eq!(cstr!("").to_owned(), CString::new("").unwrap()); |
| 63 |
assert_eq!(cstr!("hello"), &*CString::new("hello").unwrap()); |
| 64 |
assert_eq!(cstr!("hello").to_owned(), CString::new("hello").unwrap()); |
| 65 |
} |
| 66 |
|
| 67 |
#[test] |
| 68 |
#[should_panic] |
| 69 |
fn test_invalid_cstr() { |
| 70 |
let _ = cstr!("hello\0world"); |
| 71 |
} |
| 72 |
|
| 73 |
#[test] |
| 74 |
#[should_panic] |
| 75 |
fn test_invalid_empty_cstr() { |
| 76 |
let _ = cstr!("\0"); |
| 77 |
} |