All of lore.kernel.org
 help / color / mirror / Atom feed
From: Miguel Ojeda <ojeda@kernel.org>
To: "Miguel Ojeda" <ojeda@kernel.org>,
	"Wedson Almeida Filho" <wedsonaf@gmail.com>,
	"Alex Gaynor" <alex.gaynor@gmail.com>,
	"Boqun Feng" <boqun.feng@gmail.com>,
	"Gary Guo" <gary@garyguo.net>,
	"Björn Roy Baron" <bjorn3_gh@protonmail.com>
Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org,
	patches@lists.linux.dev, Milan Landaverde <milan@mdaverde.com>
Subject: [PATCH v1 16/28] rust: str: add `CStr` type
Date: Thu, 10 Nov 2022 17:41:28 +0100	[thread overview]
Message-ID: <20221110164152.26136-17-ojeda@kernel.org> (raw)
In-Reply-To: <20221110164152.26136-1-ojeda@kernel.org>

From: Gary Guo <gary@garyguo.net>

Add the `CStr` type, which is a borrowed string that is guaranteed
to have exactly one `NUL` byte, which is at the end.

It is used for interoperability with kernel APIs that take C strings.

Add it to the prelude too.

Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com>
Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com>
Co-developed-by: Milan Landaverde <milan@mdaverde.com>
Signed-off-by: Milan Landaverde <milan@mdaverde.com>
Signed-off-by: Gary Guo <gary@garyguo.net>
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 rust/kernel/prelude.rs |   2 +-
 rust/kernel/str.rs     | 169 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 170 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/prelude.rs b/rust/kernel/prelude.rs
index 1e08b08e9420..89c2c9f4e7a7 100644
--- a/rust/kernel/prelude.rs
+++ b/rust/kernel/prelude.rs
@@ -21,4 +21,4 @@ pub use super::{pr_alert, pr_crit, pr_debug, pr_emerg, pr_err, pr_info, pr_notic
 
 pub use super::error::{code::*, Error, Result};
 
-pub use super::ThisModule;
+pub use super::{str::CStr, ThisModule};
diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
index 95eb757c619d..d66565f92f71 100644
--- a/rust/kernel/str.rs
+++ b/rust/kernel/str.rs
@@ -4,6 +4,11 @@
 
 use core::fmt;
 
+use crate::{
+    bindings,
+    error::{code::*, Error},
+};
+
 /// Byte string without UTF-8 validity guarantee.
 ///
 /// `BStr` is simply an alias to `[u8]`, but has a more evident semantical meaning.
@@ -30,6 +35,170 @@ macro_rules! b_str {
     }};
 }
 
+/// Possible errors when using conversion functions in [`CStr`].
+#[derive(Debug, Clone, Copy)]
+pub enum CStrConvertError {
+    /// Supplied bytes contain an interior `NUL`.
+    InteriorNul,
+
+    /// Supplied bytes are not terminated by `NUL`.
+    NotNulTerminated,
+}
+
+impl From<CStrConvertError> for Error {
+    #[inline]
+    fn from(_: CStrConvertError) -> Error {
+        EINVAL
+    }
+}
+
+/// A string that is guaranteed to have exactly one `NUL` byte, which is at the
+/// end.
+///
+/// Used for interoperability with kernel APIs that take C strings.
+#[repr(transparent)]
+pub struct CStr([u8]);
+
+impl CStr {
+    /// Returns the length of this string excluding `NUL`.
+    #[inline]
+    pub const fn len(&self) -> usize {
+        self.len_with_nul() - 1
+    }
+
+    /// Returns the length of this string with `NUL`.
+    #[inline]
+    pub const fn len_with_nul(&self) -> usize {
+        // SAFETY: This is one of the invariant of `CStr`.
+        // We add a `unreachable_unchecked` here to hint the optimizer that
+        // the value returned from this function is non-zero.
+        if self.0.is_empty() {
+            unsafe { core::hint::unreachable_unchecked() };
+        }
+        self.0.len()
+    }
+
+    /// Returns `true` if the string only includes `NUL`.
+    #[inline]
+    pub const fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// Wraps a raw C string pointer.
+    ///
+    /// # Safety
+    ///
+    /// `ptr` must be a valid pointer to a `NUL`-terminated C string, and it must
+    /// last at least `'a`. When `CStr` is alive, the memory pointed by `ptr`
+    /// must not be mutated.
+    #[inline]
+    pub unsafe fn from_char_ptr<'a>(ptr: *const core::ffi::c_char) -> &'a Self {
+        // SAFETY: The safety precondition guarantees `ptr` is a valid pointer
+        // to a `NUL`-terminated C string.
+        let len = unsafe { bindings::strlen(ptr) } + 1;
+        // SAFETY: Lifetime guaranteed by the safety precondition.
+        let bytes = unsafe { core::slice::from_raw_parts(ptr as _, len as _) };
+        // SAFETY: As `len` is returned by `strlen`, `bytes` does not contain interior `NUL`.
+        // As we have added 1 to `len`, the last byte is known to be `NUL`.
+        unsafe { Self::from_bytes_with_nul_unchecked(bytes) }
+    }
+
+    /// Creates a [`CStr`] from a `[u8]`.
+    ///
+    /// The provided slice must be `NUL`-terminated, does not contain any
+    /// interior `NUL` bytes.
+    pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, CStrConvertError> {
+        if bytes.is_empty() {
+            return Err(CStrConvertError::NotNulTerminated);
+        }
+        if bytes[bytes.len() - 1] != 0 {
+            return Err(CStrConvertError::NotNulTerminated);
+        }
+        let mut i = 0;
+        // `i + 1 < bytes.len()` allows LLVM to optimize away bounds checking,
+        // while it couldn't optimize away bounds checks for `i < bytes.len() - 1`.
+        while i + 1 < bytes.len() {
+            if bytes[i] == 0 {
+                return Err(CStrConvertError::InteriorNul);
+            }
+            i += 1;
+        }
+        // SAFETY: We just checked that all properties hold.
+        Ok(unsafe { Self::from_bytes_with_nul_unchecked(bytes) })
+    }
+
+    /// Creates a [`CStr`] from a `[u8]` without performing any additional
+    /// checks.
+    ///
+    /// # Safety
+    ///
+    /// `bytes` *must* end with a `NUL` byte, and should only have a single
+    /// `NUL` byte (or the string will be truncated).
+    #[inline]
+    pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr {
+        // SAFETY: Properties of `bytes` guaranteed by the safety precondition.
+        unsafe { core::mem::transmute(bytes) }
+    }
+
+    /// Returns a C pointer to the string.
+    #[inline]
+    pub const fn as_char_ptr(&self) -> *const core::ffi::c_char {
+        self.0.as_ptr() as _
+    }
+
+    /// Convert the string to a byte slice without the trailing 0 byte.
+    #[inline]
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.0[..self.len()]
+    }
+
+    /// Convert the string to a byte slice containing the trailing 0 byte.
+    #[inline]
+    pub const fn as_bytes_with_nul(&self) -> &[u8] {
+        &self.0
+    }
+
+    /// Yields a [`&str`] slice if the [`CStr`] contains valid UTF-8.
+    ///
+    /// If the contents of the [`CStr`] are valid UTF-8 data, this
+    /// function will return the corresponding [`&str`] slice. Otherwise,
+    /// it will return an error with details of where UTF-8 validation failed.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use kernel::str::CStr;
+    /// let cstr = CStr::from_bytes_with_nul(b"foo\0").unwrap();
+    /// assert_eq!(cstr.to_str(), Ok("foo"));
+    /// ```
+    #[inline]
+    pub fn to_str(&self) -> Result<&str, core::str::Utf8Error> {
+        core::str::from_utf8(self.as_bytes())
+    }
+
+    /// Unsafely convert this [`CStr`] into a [`&str`], without checking for
+    /// valid UTF-8.
+    ///
+    /// # Safety
+    ///
+    /// The contents must be valid UTF-8.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use kernel::c_str;
+    /// # use kernel::str::CStr;
+    /// // SAFETY: String literals are guaranteed to be valid UTF-8
+    /// // by the Rust compiler.
+    /// let bar = c_str!("ツ");
+    /// assert_eq!(unsafe { bar.as_str_unchecked() }, "ツ");
+    /// ```
+    #[inline]
+    pub unsafe fn as_str_unchecked(&self) -> &str {
+        unsafe { core::str::from_utf8_unchecked(self.as_bytes()) }
+    }
+}
+
 /// Allows formatting of [`fmt::Arguments`] into a raw buffer.
 ///
 /// It does not fail if callers write past the end of the buffer so that they can calculate the
-- 
2.38.1


  parent reply	other threads:[~2022-11-10 16:43 UTC|newest]

Thread overview: 68+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-11-10 16:41 [PATCH v1 00/28] Rust core additions Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 01/28] rust: prelude: split re-exports into groups Miguel Ojeda
2022-11-10 18:05   ` Boqun Feng
2022-11-14 14:40   ` Wei Liu
2022-11-10 16:41 ` [PATCH v1 02/28] rust: print: add more `pr_*!` levels Miguel Ojeda
2022-11-10 18:12   ` Boqun Feng
2022-11-14 14:40   ` Wei Liu
2022-11-14 15:01     ` Sergio González Collado
2022-11-10 16:41 ` [PATCH v1 03/28] rust: print: add `pr_cont!` macro Miguel Ojeda
2022-11-14 14:40   ` Wei Liu
2022-11-14 15:04   ` Sergio González Collado
2022-11-10 16:41 ` [PATCH v1 04/28] rust: samples: add `rust_print` example Miguel Ojeda
2022-11-11  9:40   ` Finn Behrens
2022-11-11 17:31     ` Miguel Ojeda
2022-11-14 14:41   ` Wei Liu
2022-11-21 22:51   ` Sergio González Collado
2022-11-10 16:41 ` [PATCH v1 05/28] rust: macros: add `concat_idents!` proc macro Miguel Ojeda
2022-11-11  9:25   ` Finn Behrens
2022-11-14 14:26   ` Gary Guo
2022-11-14 14:39     ` Björn Roy Baron
2022-11-14 17:22     ` Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 06/28] rust: macros: add `#[vtable]` " Miguel Ojeda
2022-11-14 15:06   ` Sergio González Collado
2022-11-10 16:41 ` [PATCH v1 07/28] rust: macros: take string literals in `module!` Miguel Ojeda
2022-11-14 14:47   ` Wei Liu
2022-11-14 16:46     ` Miguel Ojeda
2022-11-14 17:25       ` Wei Liu
2022-11-10 16:41 ` [PATCH v1 08/28] rust: error: declare errors using macro Miguel Ojeda
2022-11-14 14:28   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 09/28] rust: error: add codes from `errno-base.h` Miguel Ojeda
2022-11-14 14:29   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 10/28] rust: error: add `From` implementations for `Error` Miguel Ojeda
2022-11-11  9:50   ` Finn Behrens
2022-11-10 16:41 ` [PATCH v1 11/28] rust: prelude: add `error::code::*` constant items Miguel Ojeda
2022-11-14 14:32   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 12/28] rust: alloc: add `RawVec::try_with_capacity_in()` constructor Miguel Ojeda
2022-11-14 14:34   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 13/28] rust: alloc: add `Vec::try_with_capacity{,_in}()` constructors Miguel Ojeda
2022-11-14 14:35   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 14/28] rust: str: add `BStr` type Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 15/28] rust: str: add `b_str!` macro Miguel Ojeda
2022-11-10 16:41 ` Miguel Ojeda [this message]
2022-11-10 16:41 ` [PATCH v1 17/28] rust: str: implement several traits for `CStr` Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 18/28] rust: str: add `CStr` unit tests Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 19/28] rust: str: add `c_str!` macro Miguel Ojeda
2022-11-14 14:39   ` Gary Guo
2022-11-14 18:28     ` Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 20/28] rust: str: add `Formatter` type Miguel Ojeda
2022-11-14 14:42   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 21/28] rust: str: add `CString` type Miguel Ojeda
2022-11-14 14:53   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 22/28] rust: str: add `fmt!` macro Miguel Ojeda
2022-11-14 14:58   ` Gary Guo
2022-11-10 16:41 ` [PATCH v1 23/28] rust: std_vendor: add `dbg!` macro based on `std`'s one Miguel Ojeda
2022-11-10 18:01   ` Boqun Feng
2022-11-10 19:14     ` Miguel Ojeda
2022-11-10 19:16       ` Boqun Feng
2022-11-10 19:20         ` Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 24/28] rust: static_assert: add `static_assert!` macro Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 25/28] rust: add `build_error` crate Miguel Ojeda
2022-11-14 14:30   ` Wei Liu
2022-11-14 18:22     ` Miguel Ojeda
2022-11-14 21:06       ` Wei Liu
2022-11-10 16:41 ` [PATCH v1 26/28] rust: build_assert: add `build_{error,assert}!` macros Miguel Ojeda
2022-11-10 16:41 ` [PATCH v1 27/28] rust: types: add `Either` type Miguel Ojeda
2022-11-14 14:32   ` Wei Liu
2022-11-10 16:41 ` [PATCH v1 28/28] rust: types: add `Opaque` type Miguel Ojeda
2022-11-14 15:03   ` Gary Guo

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20221110164152.26136-17-ojeda@kernel.org \
    --to=ojeda@kernel.org \
    --cc=alex.gaynor@gmail.com \
    --cc=bjorn3_gh@protonmail.com \
    --cc=boqun.feng@gmail.com \
    --cc=gary@garyguo.net \
    --cc=linux-kernel@vger.kernel.org \
    --cc=milan@mdaverde.com \
    --cc=patches@lists.linux.dev \
    --cc=rust-for-linux@vger.kernel.org \
    --cc=wedsonaf@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.