github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-12 16:18:45 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

rust: error: clarify that from_err_ptr can return Ok(NULL)

Browse Source 
Improve the doc comment of `from_err_ptr` by explicitly stating that it
will return `Ok(NULL)` when passed a null pointer, as it isn't an error
value.

Add a doctest case that tests the behavior described above, as well as
other scenarios (non-null/non-error pointer, error value).

Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Link: https://lore.kernel.org/rust-for-linux/20260322193830.89324-1-ojeda@kernel.org/
Link: https://github.com/Rust-for-Linux/linux/issues/1231
Signed-off-by: Mirko Adzic <adzicmirko97@gmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://patch.msgid.link/20260329104319.131057-1-adzicmirko97@gmail.com
[ - Added `expect` for `clippy::missing_safety_doc`.
  - Simplified and removed unsafe block using `Error::to_ptr()`.
  - Added intra-doc link.
      - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
This commit is contained in:
Mirko Adzic 2026-03-29 12:41:10 +02:00 committed by Miguel Ojeda
parent 3418d86267
commit 7ccef29b5d
1 changed files with 31 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
rust/kernel/error.rs
View File

@ -452,6 +452,9 @@ pub fn to_result(err: crate::ffi::c_int) -> Result {
/// for errors. This function performs the check and converts the "error pointer"
/// to a normal pointer in an idiomatic fashion.
///
/// Note that a `NULL` pointer is not considered an error pointer, and is returned
/// as-is, wrapped in [`Ok`].
///
/// # Examples
///
/// ```ignore
@ -466,6 +469,34 @@ pub fn to_result(err: crate::ffi::c_int) -> Result {
/// from_err_ptr(unsafe { bindings::devm_platform_ioremap_resource(pdev.to_ptr(), index) })
/// }
/// ```
///
/// ```
/// # use kernel::error::from_err_ptr;
/// # mod bindings {
/// # #![expect(clippy::missing_safety_doc)]
/// # use kernel::prelude::*;
/// # pub(super) unsafe fn einval_err_ptr() -> *mut kernel::ffi::c_void {
/// # EINVAL.to_ptr()
/// # }
/// # pub(super) unsafe fn null_ptr() -> *mut kernel::ffi::c_void {
/// # core::ptr::null_mut()
/// # }
/// # pub(super) unsafe fn non_null_ptr() -> *mut kernel::ffi::c_void {
/// # 0x1234 as *mut kernel::ffi::c_void
/// # }
/// # }
/// // SAFETY: ...
/// let einval_err = from_err_ptr(unsafe { bindings::einval_err_ptr() });
/// assert_eq!(einval_err, Err(EINVAL));
///
/// // SAFETY: ...
/// let null_ok = from_err_ptr(unsafe { bindings::null_ptr() });
/// assert_eq!(null_ok, Ok(core::ptr::null_mut()));
///
/// // SAFETY: ...
/// let non_null = from_err_ptr(unsafe { bindings::non_null_ptr() }).unwrap();
/// assert_ne!(non_null, core::ptr::null_mut());
/// ```
pub fn from_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
// CAST: Casting a pointer to `*const crate::ffi::c_void` is always valid.
let const_ptr: *const crate::ffi::c_void = ptr.cast();