diff options
Diffstat (limited to 'share/man/man9/exterror.9')
| -rw-r--r-- | share/man/man9/exterror.9 | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/share/man/man9/exterror.9 b/share/man/man9/exterror.9 new file mode 100644 index 000000000000..fd4b732b8213 --- /dev/null +++ b/share/man/man9/exterror.9 @@ -0,0 +1,219 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.Dd November 5, 2025 +.Dt EXTERROR 9 +.Os +.Sh NAME +.Nm exterror +.Nd provide extended error information to userspace +.Sh SYNOPSIS +.Bd -literal -offset left -compact +#define EXTERR_CATEGORY EXTERR_CAT_MYCATEGORY +.Ed +.In sys/exterrvar.h +.Vt struct kexterr; +.Ft void +.Fn exterr_clear "struct kexterr *ke" +.Ft int +.Fn exterr_set_from "const struct kexterr *ke" +.Ft int +.Fn EXTERROR "int error" "const char *msg" ... +.Ft void +.Fn EXTERROR_KE "struct kexterr *ke" "int error" "const char *msg" ... +.Sh DESCRIPTION +The +.Nm +framework allows the kernel to return additional information about an error +along with the standard +.Xr errno 3 +error code, which is terse and often lacking context. +.Pp +The terseness is especially visible with commonly overloaded error codes like +.Er EINVAL +or +.Er EIO , +which occur at many places for a given syscall, or even +outside the context of the current kernel call. +Identifying the specific cause for the returned error using only the +.Va errno +value requires searching for all instances that the error is returned +in the kernel and trying to guess which is the most likely code path +to have returned the error. +.Nm +attaches additional data to the error itself +and records the error category and +the kernel source code file line number. +The intent of +.Nm +is to make it easier for a user to identify the cause of the error. +.Sh USAGE +Before +.Nm +can be used in the given source .c file, the category of extended errors +should be allocated in the +.In sys/exterr_cat.h +file. +The category is the unique integer, that, together with the source +line number, uniquely identifies the extended error occurrence. +Then, the +.Va EXTERR_CATEGORY +symbol should be defined as an alias for the allocated category, as +shown in the summary. +.Pp +A typical code fragment to report an error is just +.D1 return (EINVAL); +An extended error can augment the error code with additional information: +.D1 return (EXTERROR(EINVAL, \[dq]Invalid length\[dq])); +The error data and metadata is saved in the current thread storage. +The metadata includes the category and the source file line number. +.Pp +Arguments to the +.Fn EXTERROR +macro: +.Bl -dash +.It +The first argument to +.Fn EXTERROR +is the errno error code. +.It +The second argument is a constant string with the unbound lifetime, +which should tersely provide enough human-readable details about +the error. +.It +The +.Fn EXTERROR +macro can take two optional 64-bit integer arguments, +whose meaning is specific to the subsystem. +.El +.Pp +The strings passed as the second argument are only retained +in the kernel text if the +.Cd option EXTERR_STRINGS +was enabled in the kernel config. +Otherwise they are stripped at compile time and are not available +to userspace at runtime. +.Pp +The +.Fn EXTERROR +macro can be used in any context where the current thread is defined. +Specifically, +.Fn EXTERROR +cannot be used in interrupt contexts and context switch code. +Additionally, use of +.Fn EXTERROR +in kernel threads is not sensible as there is no userspace to retrieve +the extended error data. +.Pp +The +.Fn EXTERROR_KE +macro is similar to +.Fn EXTERROR , +but it takes an explicit pointer +.Fa kep +to the +.Vt struct kexterr +to fill with the extended error information. +The macro expression value is +.Vt void . +See below for description of the asynchronous i/o error facilities. +.Pp +The +.Fn exterr_clear +function clears the content of the +.Vt struct kexterr +pointed to by the argument +.Fa ke . +.Pp +The +.Fn exterr_set_from +function sets the current thread extended error data from the +.Fa struct kexterr +pointed to by the argument +.Fa ke . +.Sh USERSPACE ACCESS TO EXTENDED ERROR DATA +There is no syscall overhead for using +.Nm +in the non-error case. +When an error occurs that has supplied extended information, +the kernel copies out that information into the userspace +per-thread area that was registered with the kernel, typically on +image activation, or later at thread startup. +The area is controlled by the +.Xr exterrctl 2 +internal syscall, normally done by the userspace C runtime. +.Pp +Userspace programs do not need to access the extended information +area directly. +There is no field that is stable for the specific error condition. +Instead, the base +.Lb c +functions +.Xr err 3 +and +.Xr warn 3 +were modified to print the extended information if it is available +in addition to the usual +.Va errno +decoding. +.Sh ASYNCHRONOUS INPUT/OUTPUT +Due to the nature of the +.Fx +i/o subsystem, most input/output requests, presented as buffers (as in +.Vt struct buf ) +and geom bio's ( +.Vt struct bio ) +are processed asynchronously in filesystem- and geom-private threads. +This makes it challenging to pass any extended error information +from the geom providers and drivers, where an error typically occurs, +back to the thread that initiated the request, and is the consumer of +the result. +.Pp +To alleviate the mismatch, both +.Vt struct buf +and +.Vt struct bio +have member of the +.Vt struct kexterr +type. +For buffers, the +.Va b_exterr +for +.Vt struct buf , +and +.Va bio_exterr +for +.Vt struct bio . +Asynchronous i/o code can use the +.Fn EXTERROR_KE +macro, passing the pointer to the current request's embedded +.Vt struct kexterr , +to record the extended error. +In both cases, the +.Va BIO_EXTERR +flag should be set to indicate that whole extended error is valid, +not only the +.Va b_error +or +.Va bio_error +values. +.Pp +Both VFS and geom generic layers, and several geom providers that generate +subordinate bio's from the original request, are aware of the extended +errors. +They pass +.Vt kexterr +from the failed request back to the thread that create the request. +.Sh SEE ALSO +.Xr errno 3 , +.Xr err 3 +.Sh HISTORY +The +.Nm +facility was introduced in +.Fx 15.0 . |