From nobody Fri Nov 21 08:41:34 2025 X-Original-To: dev-commits-src-branches@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4dCTGQ59HQz6Gqbc for ; Fri, 21 Nov 2025 08:41:34 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R12" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4dCTGQ3YVdz42wH for ; Fri, 21 Nov 2025 08:41:34 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1763714494; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yZcOEsfF1zyxkiTDJdNUcLMHrE2ovZlYjkrN1FTNoh8=; b=vpJVyCme4up1h/M73BRqrAv7OfLcKvru3T+QKqPjUqoWQcHBN025pXxY1uNH+fD718cdTV yyaYyNh+VBp6e956c9H3qWX+oeTCoKEJu2awBs8CrhAkYT5PoBP4E0ZZ3pue2eLjMGinz4 I3dRJD9FMm6Z8kAZyqpTCDoCRxkmZY0szMmCV2tpLKXsQG+KMpuaEZj2XFyLT7bW67rds9 +FvSPVxilEgAdk6cC3a9lJPQPCbS6pJ1cjKOeHnjL61kpt1lQm68iwpbKirzMCmonU+ack Jj+Q4QRqKO1GG8HvRd6I6hJ13H+Cs8QpwpUFsW9HIuUMzdSo52D9Xxwa3Nnwhw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1763714494; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yZcOEsfF1zyxkiTDJdNUcLMHrE2ovZlYjkrN1FTNoh8=; b=SZ1oBGkiKI8TAiu4mwMT1LmvDU0B1k+wgmpb9o9wPPGIh3PN1sfDb8kLfTlTsYb9jhA5cK QL0DKHFpo42XthJSbQX6JqP3cnGODC3IqLym02R+mseOPbZ5wvRdmF9qVBbAZxfzaCy4r6 +RjwhsfOYzwr+IvXEbdOWkmCU9eKJBpdRwiQ8p63Q8AgNGjcDIM5ic/xDUSNP9kOSFoU0c m8VBeO+zMqt8SYYyZ0bFCCxpdQo6bnjlIZV/eEz851vjbI/BHgC3aVP+aEF/U8zS5SBaCw 8kTrRmUc52xRXPpws/l4hSZ7AyxtRC6goaOO7W+jMX5SOirrJZTZ5wK3xVL2LQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1763714494; a=rsa-sha256; cv=none; b=HLCWeSS/H//+u99edQy1Cnh2Ihy0/MhOb4Kl9+QT4M9IfZOVI+JV52qUkwNEOyIHAkGIol MuvFpO6pnssCndPnxA8Yn3lI2XsY+YwbGn0zq1XgZWmGUfxVz4I6xebYDGouuL30hCdSD7 yu+bJTvEgug+jQYw6BNcU+fOZRa/WixhjySJxTUIxMop7sPQv3VDOi0ZSGE41SQihCTvFt hKs7Auw5VXKaCWTwtPUGRhxWnSP4aBcXqOzCXDgeOckXRgYRkStc6GW5NrvK7S4ipN3I18 +SvQkTPNWlWmtCTg8jX6yDOsSATjDTO/eHe+c8JTgEbMAFEIfThbcmmssz/hxg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4dCTGQ2hHVz14Hj for ; Fri, 21 Nov 2025 08:41:34 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 31b1e by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Fri, 21 Nov 2025 08:41:34 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: 0d8535e7724a - stable/15 - exterror.9 man page List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-branches@freebsd.org Sender: owner-dev-commits-src-branches@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/stable/15 X-Git-Reftype: branch X-Git-Commit: 0d8535e7724a5e7e9119b2c46a74b8d7fc7ae87d Auto-Submitted: auto-generated Date: Fri, 21 Nov 2025 08:41:34 +0000 Message-Id: <692025be.31b1e.341fc556@gitrepo.freebsd.org> The branch stable/15 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=0d8535e7724a5e7e9119b2c46a74b8d7fc7ae87d commit 0d8535e7724a5e7e9119b2c46a74b8d7fc7ae87d Author: Konstantin Belousov AuthorDate: 2025-11-04 21:45:55 +0000 Commit: Konstantin Belousov CommitDate: 2025-11-21 08:41:11 +0000 exterror.9 man page (cherry picked from commit 0eca7fa1c96f779039dd70eeeb0585ac12d153da) --- share/man/man9/Makefile | 1 + share/man/man9/exterror.9 | 137 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 4cea099b6c07..bdf85363c8e1 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -150,6 +150,7 @@ MAN= accept_filter.9 \ EVENTHANDLER.9 \ eventtimers.9 \ extattr.9 \ + exterror.9 \ fail.9 \ fdt_pinctrl.9 \ fetch.9 \ diff --git a/share/man/man9/exterror.9 b/share/man/man9/exterror.9 new file mode 100644 index 000000000000..79197e4a187d --- /dev/null +++ b/share/man/man9/exterror.9 @@ -0,0 +1,137 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov 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 +.Ft int +.Fn EXTERROR "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. +.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 SEE ALSO +.Xr errno 3 , +.Xr err 3 +.Sh HISTORY +The +.Nm +facility was introduced in +.Fx 15.0 .