git: 95e33099c74d - main - runtime: add the ability to set exterrors in userspace

The branch main has been updated by brooks:

URL: https://cgit.FreeBSD.org/src/commit/?id=95e33099c74d9fc7963968f052b7546ad3040317

commit 95e33099c74d9fc7963968f052b7546ad3040317
Author:     Brooks Davis <[email protected]>
AuthorDate: 2026-08-20 10:39:00 +0000
Commit:     Brooks Davis <[email protected]>
CommitDate: 2026-08-20 10:39:00 +0000

    runtime: add the ability to set exterrors in userspace
    
    The UEXTERROR(3) macro is a partial analog to EXTERROR(9) that sets
    the current user exterror state and errno.  The main difference is
    that it returns no value and sets errno directly since that's the
    typical pattern in libraries.
    
    While here move the storage and constructor for single-threaded
    program's uexterr to its own file.
    
    Reviewed by:    kib
    Effort:         CHERI upstreaming
    Sponsored by:   Innovate UK
    Differential Revision:  https://reviews.freebsd.org/D58059
---
 include/Makefile                      |   3 +-
 include/uexterror.h                   |  65 ++++++++++++++++
 lib/libc/gen/Makefile.inc             |   3 +
 lib/libc/gen/Symbol.map               |   2 +
 lib/libc/gen/libc_interposing_table.c |   1 +
 lib/libc/gen/uexterr_gettext.c        |  18 -----
 lib/libc/gen/uexterr_init.c           |  26 +++++++
 lib/libc/gen/uexterr_set.c            |  50 +++++++++++++
 lib/libc/gen/uexterror.3              | 135 ++++++++++++++++++++++++++++++++++
 lib/libc/include/libc_private.h       |   6 ++
 lib/libthr/thread/thr_syscalls.c      |  13 ++++
 share/man/man9/exterror.9             |   1 +
 12 files changed, 304 insertions(+), 19 deletions(-)

diff --git a/include/Makefile b/include/Makefile
index 60c2ca5819dc..bfa82a0bb706 100644
--- a/include/Makefile
+++ b/include/Makefile
@@ -33,7 +33,8 @@ INCS=	a.out.h ar.h assert.h bitstring.h byteswap.h \
 	stddef.h stdnoreturn.h stdio.h stdlib.h string.h stringlist.h \
 	strings.h sysexits.h tar.h termios.h tgmath.h \
 	time.h timeconv.h timers.h ttyent.h \
-	uchar.h ulimit.h unistd.h utime.h utmpx.h uuid.h varargs.h \
+	uchar.h uexterror.h ulimit.h unistd.h utime.h utmpx.h uuid.h \
+	varargs.h \
 	wchar.h wctype.h wordexp.h xlocale.h
 
 .PATH: ${SRCTOP}/contrib/libc-vis
diff --git a/include/uexterror.h b/include/uexterror.h
new file mode 100644
index 000000000000..d2044ff97b0c
--- /dev/null
+++ b/include/uexterror.h
@@ -0,0 +1,65 @@
+/*-
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * Copyright (c) 2025 The FreeBSD Foundation
+ * Copyright (c) 2026 Capabilities Limited
+ * All rights reserved.
+ *
+ * This software were developed by Konstantin Belousov <[email protected]>
+ * under sponsorship from the FreeBSD Foundation.
+ *
+ * This software was developed by Capabilities Limited with funding from
+ * Innovate UK and the Department for Science, Innovation and Technology
+ * for the adoption and diffusion of CHERI technology under project
+ * 10168042 (“CheriBSD feature extraction, maturity, and testing”).
+ */
+
+#ifndef _UEXTERROR_H_
+#define	_UEXTERROR_H_
+
+#include <sys/types.h>
+#include <sys/linker_set.h>
+
+struct exterr_cat {
+	unsigned int	cat;
+	const char	*file;
+};
+
+#ifndef UEXTERR_CATEGORY
+#error "Specify error category before including uexterror.h"
+#endif
+
+#ifndef NO_UEXTERR_STRINGS
+static struct exterr_cat __dynamic_cat = { .file = UEXTERR_CATEGORY };
+DATA_WSET(exterr_cats, __dynamic_cat);
+#define	_UEXTERR_CATEGORY						\
+	(__dynamic_cat.cat | EXTERR_CAT_SRC_USER)
+#else
+#define	_UEXTERR_CATEGORY	(EXTERR_CAT_NONE | EXTERR_CAT_SRC_USER)
+#endif
+
+
+#ifdef NO_UEXTERR_STRINGS
+#define	SET_ERROR_MSG(mmsg)	NULL
+#else
+#define	SET_ERROR_MSG(mmsg)	(mmsg)
+#endif
+
+#define	_SET_ERROR2(eerror, mmsg, pp1, pp2)				\
+	uexterr_set(eerror, _UEXTERR_CATEGORY, SET_ERROR_MSG(mmsg),	\
+	    (uint64ptr_t)(pp1), (uint64ptr_t)(pp2), __LINE__)
+#define	_SET_ERROR0(eerror, mmsg)	_SET_ERROR2(eerror, mmsg, 0, 0)
+#define	_SET_ERROR1(eerror, mmsg, pp1)	_SET_ERROR2(eerror, mmsg, pp1, 0)
+
+#define	_UEXTERROR_MACRO(eerror, mmsg, _1, _2, NAME, ...)		\
+	NAME
+#define	UEXTERROR(...)							\
+	_UEXTERROR_MACRO(__VA_ARGS__, _SET_ERROR2, _SET_ERROR1,		\
+	    _SET_ERROR0)(__VA_ARGS__)
+
+__BEGIN_DECLS
+void uexterr_set(int error, int category, const char *mmsg, uint64ptr_t pp1,
+    uint64ptr_t pp2, int line);
+__END_DECLS
+
+#endif
diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index f60425f27318..bd67d75a1c0e 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -165,6 +165,8 @@ SRCS+= \
 	ualarm.c \
 	uexterr_format.c \
 	uexterr_gettext.c \
+	uexterr_init.c \
+	uexterr_set.c \
 	ulimit.c \
 	uname.c \
 	unvis-compat.c \
@@ -325,6 +327,7 @@ MAN+=	alarm.3 \
 	ttyname.3 \
 	ualarm.3 \
 	ucontext.3 \
+	uexterr.3 \
 	uexterr_gettext.3 \
 	ulimit.3 \
 	uname.3 \
diff --git a/lib/libc/gen/Symbol.map b/lib/libc/gen/Symbol.map
index ff3653945296..4a75421777e5 100644
--- a/lib/libc/gen/Symbol.map
+++ b/lib/libc/gen/Symbol.map
@@ -483,6 +483,7 @@ FBSD_1.9 {
 	posix_spawnattr_getprocdescp_np;
 	posix_spawnattr_setexecfd_np;
 	posix_spawnattr_setprocdescp_np;
+	uexterr_set;
 };
 
 FBSDprivate_1.0 {
@@ -613,4 +614,5 @@ FBSDprivate_1.0 {
 	__getcontextx_size;
 	__makecontext;
 	__uexterr_format;
+	__uexterr_set_ue;
 };
diff --git a/lib/libc/gen/libc_interposing_table.c b/lib/libc/gen/libc_interposing_table.c
index 025a67ac3eac..66a63e2c27b5 100644
--- a/lib/libc/gen/libc_interposing_table.c
+++ b/lib/libc/gen/libc_interposing_table.c
@@ -43,6 +43,7 @@ interpos_func_t __libc_interposing[INTERPOS_MAX] = {
 	SLOT(spinunlock, __libc_spinunlock_stub),
 	SLOT(map_stacks_exec, __libc_map_stacks_exec),
 	SLOT(uexterr_gettext, __libc_uexterr_gettext),
+	SLOT(uexterr_set, __libc_uexterr_set),
 };
 #undef SLOT
 
diff --git a/lib/libc/gen/uexterr_gettext.c b/lib/libc/gen/uexterr_gettext.c
index 5b8a5cd17a48..dd501ff6ddbc 100644
--- a/lib/libc/gen/uexterr_gettext.c
+++ b/lib/libc/gen/uexterr_gettext.c
@@ -8,27 +8,9 @@
  * under sponsorship from the FreeBSD Foundation.
  */
 
-#define	_WANT_P_OSREL
-#include <sys/param.h>
-#include <sys/exterrvar.h>
 #include <exterr.h>
-#include <string.h>
 #include "libc_private.h"
 
-static struct uexterror uexterr = {
-	.ver = UEXTERROR_VER,
-};
-
-int __getosreldate(void);
-
-static void uexterr_ctr(void) __attribute__((constructor));
-static void
-uexterr_ctr(void)
-{
-	if (__getosreldate() >= P_OSREL_EXTERRCTL)
-		exterrctl(EXTERRCTL_ENABLE, 0, &uexterr);
-}
-
 int
 __libc_uexterr_gettext(char *buf, size_t bufsz)
 {
diff --git a/lib/libc/gen/uexterr_init.c b/lib/libc/gen/uexterr_init.c
new file mode 100644
index 000000000000..b85648ca82bf
--- /dev/null
+++ b/lib/libc/gen/uexterr_init.c
@@ -0,0 +1,26 @@
+/*-
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * Copyright (c) 2025 The FreeBSD Foundation
+ * All rights reserved.
+ *
+ * This software were developed by Konstantin Belousov <[email protected]>
+ * under sponsorship from the FreeBSD Foundation.
+ */
+
+#define	_WANT_P_OSREL
+#include <sys/param.h>
+#include <sys/exterrvar.h>
+#include "libc_private.h"
+
+struct uexterror uexterr = {
+	.ver = UEXTERROR_VER,
+};
+
+static void uexterr_ctr(void) __attribute__((constructor));
+static void
+uexterr_ctr(void)
+{
+	if (__getosreldate() >= P_OSREL_EXTERRCTL)
+		exterrctl(EXTERRCTL_ENABLE, 0, &uexterr);
+}
diff --git a/lib/libc/gen/uexterr_set.c b/lib/libc/gen/uexterr_set.c
new file mode 100644
index 000000000000..e8acd7b65aca
--- /dev/null
+++ b/lib/libc/gen/uexterr_set.c
@@ -0,0 +1,50 @@
+/*-
+ * Copyright (c) 2026 Capabilities Limited
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * This software was developed by Capabilities Limited with funding from
+ * Innovate UK and the Department for Science, Innovation and Technology
+ * for the adoption and diffusion of CHERI technology under project
+ * 10168042 (“CheriBSD feature extraction, maturity, and testing”).
+ */
+
+#include <sys/exterrvar.h>
+#include <errno.h>
+#include <exterr.h>
+#include <string.h>
+#include "libc_private.h"
+
+void
+__uexterr_set_ue(struct uexterror *ue, int error, int category,
+    const char *mmsg, uint64ptr_t pp1, uint64ptr_t pp2, int line)
+{
+	memset((char *)ue + offsetof(struct uexterror, error), 0,
+	    sizeof(struct uexterror) - offsetof(struct uexterror, error));
+	ue->error = error;
+	ue->cat = category | EXTERR_CAT_SRC_USER;
+	ue->src_line = line;
+	ue->p1 = pp1;
+	ue->p2 = pp2;
+	if (mmsg != NULL)
+		strlcpy(ue->msg, mmsg, sizeof(ue->msg));
+	else
+		ue->msg[0] = '\0';
+	errno = error;
+}
+
+void
+__libc_uexterr_set(int error, int category, const char *mmsg, uint64ptr_t pp1,
+    uint64ptr_t pp2, int line)
+{
+	__uexterr_set_ue(&uexterr, error, category, mmsg, pp1, pp2, line);
+}
+
+void
+uexterr_set(int error, int category, const char *mmsg, uint64ptr_t pp1,
+    uint64ptr_t pp2, int line)
+{
+	((void (*)(int, int, const char *, uint64ptr_t, uint64ptr_t, int))
+	    __libc_interposing[INTERPOS_uexterr_set])(error, category,
+	    mmsg, pp1, pp2, line);
+}
diff --git a/lib/libc/gen/uexterror.3 b/lib/libc/gen/uexterror.3
new file mode 100644
index 000000000000..0015e88d61a3
--- /dev/null
+++ b/lib/libc/gen/uexterror.3
@@ -0,0 +1,135 @@
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2025 The FreeBSD Foundation
+.\" Copyright (c) 2026 Capabilities Limited
+.\"
+.\" This documentation was written by
+.\" Konstantin Belousov <[email protected]> under sponsorship
+.\" from the FreeBSD Foundation.
+.\"
+.\" This software was developed by Capabilities Limited with funding from
+.\" Innovate UK and the Department for Science, Innovation and Technology
+.\" for the adoption and diffusion of CHERI technology under project
+.\" 10168042 (“CheriBSD feature extraction, maturity, and testing”).
+.\"
+.Dd August 20, 2026
+.Dt UEXTERROR 3
+.Os
+.Sh NAME
+.Nm uexterror
+.Nd provide extended error information from user-space code
+.Sh SYNOPSIS
+.Bd -literal -offset left -compact
+#define UEXTERR_CATEGORY "path/to/this/file.c"
+.Ed
+.In uexterror.h
+.Ft void
+.Fn UEXTERROR "int error" "const char *msg" ...
+.Sh DESCRIPTION
+The
+.Nm
+framework allows user-space code to report errors using the
+same
+.Xr exterror 9
+infrastructure the kernel uses 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 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 user-space and 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 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
+must be defined.
+This can be done by setting the
+.Va UEXTERR_CATEGORY
+macro to a string containing the name of the file relative to
+.Pa src/sys
+directory.
+.Pp
+A typical code fragment to report an error is to set errno
+.D1 errno = EINVAL;
+An extended error can augment the error code with additional information:
+.D1 UEXTERROR(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 UEXTERROR
+macro:
+.Bl -dash
+.It
+The first argument to
+.Fn UEXTERROR
+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 UEXTERROR
+macro can take two optional uintptr_t or 64-bit integer arguments,
+whose meaning is specific to the subsystem.
+The format string may include up to two printf-like format
+specifiers to insert the optional argument values in the
+user output, which is done in userspace.
+.Pp
+The format specifier must be for an character, integer, or pointer type.
+Note that userspace printing assumes all
+.Dt long Ns -derived
+types such as
+.Dt size_t
+are 64-bit and prints them accordingly.
+Signed integer types should thus be cast to
+.Dt int64_t
+or similar to insure proper sign extension.
+.El
+.Pp
+Note that unlike its kernel counterpart
+.Xr EXTERROR 9
+the
+.Nm
+macro does not return a value and sets
+.Xr errno 3
+directly.
+.Pp
+The name of the file and strings passed as the second argument are
+retained in the program or library text as long as the translation unit
+was not compiled with the
+.Cd NO_UEXTERR_STRINGS
+macro defined.
+.Sh SEE ALSO
+.Xr errno 3 ,
+.Xr err 3 ,
+.Xr uexterr_gettext 3 ,
+.Xr exterror 9
+.Sh HISTORY
+The
+.Nm
+facility was introduced in
+.Fx 16.0 .
+.Sh AUTHORS
+This software and this manual page were developed by Capabilities
+Limited with funding from Innovate UK and the Department for Science,
+Innovation and Technology for the adoption and diffusion of CHERI
+technology under project 10168042
+.Pq Do CheriBSD feature extraction, maturity, and testing Dc .
diff --git a/lib/libc/include/libc_private.h b/lib/libc/include/libc_private.h
index 299629fce2ad..205f0453ffc7 100644
--- a/lib/libc/include/libc_private.h
+++ b/lib/libc/include/libc_private.h
@@ -253,6 +253,7 @@ enum {
 	INTERPOS_pdfork,
 	INTERPOS_uexterr_gettext,
 	INTERPOS_pdwait,
+	INTERPOS_uexterr_set,
 	INTERPOS_MAX
 };
 
@@ -381,7 +382,12 @@ int __strerror_rl(int errnum, char *strerrbuf, size_t buflen,
 	    struct _xlocale *locale);
 
 struct uexterror;
+extern struct uexterror uexterr;
 int __uexterr_format(const struct uexterror *ue, char *buf, size_t bufsz);
+void __uexterr_set_ue(struct uexterror *ue, int error, int category,
+    const char *mmsg, uint64ptr_t pp1, uint64ptr_t pp2, int line);
 int __libc_uexterr_gettext(char *buf, size_t bufsz);
+void __libc_uexterr_set(int eerror, int category, const char *mmsg,
+    uint64ptr_t pp1, uint64ptr_t pp2, int line);
 
 #endif /* _LIBC_PRIVATE_H_ */
diff --git a/lib/libthr/thread/thr_syscalls.c b/lib/libthr/thread/thr_syscalls.c
index bff2d0624aee..20c78ff39bd6 100644
--- a/lib/libthr/thread/thr_syscalls.c
+++ b/lib/libthr/thread/thr_syscalls.c
@@ -643,6 +643,18 @@ __thr_uexterr_gettext(char *buf, size_t bufsz)
 	return (__uexterr_format(&curthread->uexterr, buf, bufsz));
 }
 
+static void
+__thr_uexterr_set(int error, int category, const char *mmsg, uint64ptr_t pp1,
+    uint64ptr_t pp2, int line)
+{
+	struct pthread *curthread;
+
+	curthread = _get_curthread();
+
+	__uexterr_set_ue(&curthread->uexterr, error, category, mmsg,
+	    pp1, pp2, line);
+}
+
 void
 __thr_interpose_libc(void)
 {
@@ -700,6 +712,7 @@ __thr_interpose_libc(void)
 	SLOT(pdfork);
 	SLOT(uexterr_gettext);
 	SLOT(pdwait);
+	SLOT(uexterr_set);
 #undef SLOT
 	*(__libc_interposing_slot(
 	    INTERPOS__pthread_mutex_init_calloc_cb)) =
diff --git a/share/man/man9/exterror.9 b/share/man/man9/exterror.9
index ff4033c6fc1d..6b3725a5d8c6 100644
--- a/share/man/man9/exterror.9
+++ b/share/man/man9/exterror.9
@@ -244,6 +244,7 @@ from the failed request back to the thread that create the request.
 .Xr errno 3 ,
 .Xr err 3 ,
 .Xr uexterr_gettext 3
+.Xr uexterr 3
 .Sh HISTORY
 The
 .Nm