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>
---
 rust/kernel/error.rs | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
index 935787c2a91c..9a4388c74f43 100644
--- a/rust/kernel/error.rs
+++ b/rust/kernel/error.rs
@@ -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,41 @@ 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 {
+/// #     use kernel::prelude::*;
+/// #     pub(super) unsafe fn einval_err_ptr() -> *mut kernel::ffi::c_void {
+/// #         let einval = -(kernel::bindings::EINVAL as isize);
+/// #         // SAFETY: `einval` is a valid error.
+/// #         unsafe { kernel::bindings::ERR_PTR(einval) }
+/// #     }
+/// #     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
+/// #     }
+/// # }
+/// fn einval_err_ptr() {
+///     // SAFETY: ...
+///     let result = from_err_ptr(unsafe { bindings::einval_err_ptr() });
+///     assert_eq!(result, Err(EINVAL));
+/// }
+///
+/// fn null_ptr() {
+///     // SAFETY: ...
+///     let result = from_err_ptr(unsafe { bindings::null_ptr() });
+///     assert_eq!(result, Ok(core::ptr::null_mut()));
+/// }
+///
+/// fn non_null_ptr() {
+///     // SAFETY: ...
+///     let result = from_err_ptr(unsafe { bindings::non_null_ptr() });
+///     assert_eq!(result, Ok(0x1234 as *mut kernel::ffi::c_void));
+/// }
+/// ```
 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();
-- 
2.53.0

On Sat, Mar 28, 2026 at 4:51 PM Mirko Adzic <adzicmirko97@gmail.com> wrote:
>
> +/// ```
> +/// # use kernel::error::from_err_ptr;
> +/// # mod bindings {

I see you followed the way we provide "dummy bindings" from elsewhere
-- that is good, thanks!

> +/// fn einval_err_ptr() {
> +///     // SAFETY: ...
> +///     let result = from_err_ptr(unsafe { bindings::einval_err_ptr() });
> +///     assert_eq!(result, Err(EINVAL));
> +/// }

Like you yourself mentioned in the GitHub issue, code inside functions
is not called, so please move it out -- you can keep the "blocks"
separated with a newline so that it is easier to see the different
cases.

> +///     assert_eq!(result, Ok(0x1234 as *mut kernel::ffi::c_void));

Since you are asserting the value, but the bindings are hidden, it may
be best to just assert it is not null.

Thanks for the patch! Please feel free to send a v2 fixing those.

Cheers,
Miguel

Hi, thank you for the review.

On Sat, Mar 28, 2026 at 7:01 PM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
> > +/// fn einval_err_ptr() {
> > +///     // SAFETY: ...
> > +///     let result = from_err_ptr(unsafe { bindings::einval_err_ptr() });
> > +///     assert_eq!(result, Err(EINVAL));
> > +/// }
>
> Like you yourself mentioned in the GitHub issue, code inside functions
> is not called, so please move it out -- you can keep the "blocks"
> separated with a newline so that it is easier to see the different
> cases.

Will do, thanks.

> > +///     assert_eq!(result, Ok(0x1234 as *mut kernel::ffi::c_void));
>
> Since you are asserting the value, but the bindings are hidden, it may
> be best to just assert it is not null.

Makes total sense, will be addressed in v2.

Best,
Mirko