tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

rust: str: update `c_str!` documentation

Now that all literals are C-Strings, update the documentation to explain
that use of this macro should be limited to non-literal strings.

Link: https://github.com/Rust-for-Linux/linux/issues/1075
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Tamir Duberstein <tamird@kernel.org>
Reviewed-by: Gary Guo <gary@garyguo.net>
Link: https://patch.msgid.link/20260309-cstr-rename-macro-v2-1-25f7de75944e@kernel.org
[ Apply sentence case to comment. Reword title. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

authored by

Tamir Duberstein and committed by
Miguel Ojeda 1353b8f3 b3d161f2

+16 -3
+16 -3
rust/kernel/str.rs
··· 379 379 } 380 380 } 381 381 382 - /// Creates a new [`CStr`] from a string literal. 382 + /// Creates a new [`CStr`] at compile time. 383 383 /// 384 - /// The string literal should not contain any `NUL` bytes. 384 + /// Rust supports C string literals since Rust 1.77, and they should be used instead of this macro 385 + /// where possible. This macro exists to allow static *non-literal* C strings to be created at 386 + /// compile time. This is most often used in other macros. 387 + /// 388 + /// # Panics 389 + /// 390 + /// This macro panics if the operand contains an interior `NUL` byte. 385 391 /// 386 392 /// # Examples 387 393 /// 388 394 /// ``` 389 395 /// # use kernel::c_str; 390 396 /// # use kernel::str::CStr; 391 - /// const MY_CSTR: &CStr = c_str!("My awesome CStr!"); 397 + /// // This is allowed, but `c"literal"` should be preferred for literals. 398 + /// const BAD: &CStr = c_str!("literal"); 399 + /// 400 + /// // `c_str!` is still needed for static non-literal C strings. 401 + /// const GOOD: &CStr = c_str!(concat!(file!(), ":", line!(), ": My CStr!")); 392 402 /// ``` 393 403 #[macro_export] 394 404 macro_rules! c_str { 405 + // NB: We could write `($str:lit) => compile_error!("use a C string literal instead");` here but 406 + // that would trigger when the literal is at the top of several macro expansions. That would be 407 + // too limiting to macro authors. 395 408 ($str:expr) => {{ 396 409 const S: &str = concat!($str, "\0"); 397 410 const C: &$crate::str::CStr = match $crate::str::CStr::from_bytes_with_nul(S.as_bytes()) {