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 <[email protected]> Reviewed-by: Alice Ryhl <[email protected]> Signed-off-by: Tamir Duberstein <[email protected]> --- This patch completes the work of replacing our custom `CStr` with upstream's. --- Changes in v2: - Drop rename, keep only documentation update. (Gary Guo) - Add example of misuse to documentation. (Gary Guo) - Link to v1: https://patch.msgid.link/[email protected] --- rust/kernel/str.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs index fa87779d2253..6dae82e7d875 100644 --- a/rust/kernel/str.rs +++ b/rust/kernel/str.rs @@ -376,19 +376,32 @@ fn as_ref(&self) -> &BStr { } } -/// Creates a new [`CStr`] from a string literal. +/// Creates a new [`CStr`] at compile time. /// -/// The string literal should not contain any `NUL` bytes. +/// Rust supports C string literals since Rust 1.77, and they should be used instead of this macro +/// where possible. This macro exists to allow static *non-literal* C strings to be created at +/// compile time. This is most often used in other macros. +/// +/// # Panics +/// +/// This macro panics if the operand contains an interior `NUL` byte. /// /// # Examples /// /// ``` /// # use kernel::c_str; /// # use kernel::str::CStr; -/// const MY_CSTR: &CStr = c_str!("My awesome CStr!"); +/// // This is allowed, but `c"literal"` should be preferred for literals. +/// const BAD: &CStr = c_str!("literal"); +/// +/// // `c_str!` is still needed for static non-literal C strings. +/// const GOOD: &CStr = c_str!(concat!(file!(), ":", line!(), ": My CStr!")); /// ``` #[macro_export] macro_rules! c_str { + // NB: we could write `($str:lit) => compile_error!("use a C string literal instead");` here but + // that would trigger when the literal is at the top of several macro expansions. That would be + // too limiting to macro authors. ($str:expr) => {{ const S: &str = concat!($str, "\0"); const C: &$crate::str::CStr = match $crate::str::CStr::from_bytes_with_nul(S.as_bytes()) { --- base-commit: 11439c4635edd669ae435eec308f4ab8a0804808 change-id: 20260302-cstr-rename-macro-64201be6c969 Best regards, -- Tamir Duberstein <[email protected]>
