1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2025 The FreeBSD Foundation 4.\" Copyright (c) 2026 Capabilities Limited 5.\" 6.\" This documentation was written by 7.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 8.\" from the FreeBSD Foundation. 9.\" 10.\" This software was developed by Capabilities Limited with funding from 11.\" Innovate UK and the Department for Science, Innovation and Technology 12.\" for the adoption and diffusion of CHERI technology under project 13.\" 10168042 (“CheriBSD feature extraction, maturity, and testing”). 14.\" 15.Dd August 20, 2026 16.Dt UEXTERROR 3 17.Os 18.Sh NAME 19.Nm uexterror 20.Nd provide extended error information from user-space code 21.Sh SYNOPSIS 22.Bd -literal -offset left -compact 23#define UEXTERR_CATEGORY "path/to/this/file.c" 24.Ed 25.In uexterror.h 26.Ft void 27.Fn UEXTERROR "int error" "const char *msg" ... 28.Sh DESCRIPTION 29The 30.Nm 31framework allows user-space code to report errors using the 32same 33.Xr exterror 9 34infrastructure the kernel uses to return additional information about an 35error along with the standard 36.Xr errno 3 37error code, which is terse and often lacking context. 38.Pp 39The terseness is especially visible with commonly overloaded error codes like 40.Er EINVAL 41or 42.Er EIO , 43which occur at many places for a given syscall, or even 44outside the context of the current call. 45Identifying the specific cause for the returned error using only the 46.Va errno 47value requires searching for all instances that the error is returned 48in user-space and the kernel and trying to guess which is the most 49likely code path to have returned the error. 50.Nm 51attaches additional data to the error itself 52and records the error category and 53the source code file line number. 54The intent of 55.Nm 56is to make it easier for a user to identify the cause of the error. 57.Sh USAGE 58Before 59.Nm 60can be used in the given source .c file, the category of extended errors 61must be defined. 62This can be done by setting the 63.Va UEXTERR_CATEGORY 64macro to a string containing the name of the file relative to 65.Pa src/sys 66directory. 67.Pp 68A typical code fragment to report an error is to set errno 69.D1 errno = EINVAL; 70An extended error can augment the error code with additional information: 71.D1 UEXTERROR(EINVAL, \[dq]Invalid length\[dq])); 72The error data and metadata is saved in the current thread storage. 73The metadata includes the category and the source file line number. 74.Pp 75Arguments to the 76.Fn UEXTERROR 77macro: 78.Bl -dash 79.It 80The first argument to 81.Fn UEXTERROR 82is the errno error code. 83.It 84The second argument is a constant string with the unbound lifetime, 85which should tersely provide enough human-readable details about 86the error. 87.It 88The 89.Fn UEXTERROR 90macro can take two optional uintptr_t or 64-bit integer arguments, 91whose meaning is specific to the subsystem. 92The format string may include up to two printf-like format 93specifiers to insert the optional argument values in the 94user output, which is done in userspace. 95.Pp 96The format specifier must be for an character, integer, or pointer type. 97Note that userspace printing assumes all 98.Dt long Ns -derived 99types such as 100.Dt size_t 101are 64-bit and prints them accordingly. 102Signed integer types should thus be cast to 103.Dt int64_t 104or similar to insure proper sign extension. 105.El 106.Pp 107Note that unlike its kernel counterpart 108.Xr EXTERROR 9 109the 110.Nm 111macro does not return a value and sets 112.Xr errno 3 113directly. 114.Pp 115The name of the file and strings passed as the second argument are 116retained in the program or library text as long as the translation unit 117was not compiled with the 118.Cd NO_UEXTERR_STRINGS 119macro defined. 120.Sh SEE ALSO 121.Xr errno 3 , 122.Xr err 3 , 123.Xr uexterr_gettext 3 , 124.Xr exterror 9 125.Sh HISTORY 126The 127.Nm 128facility was introduced in 129.Fx 16.0 . 130.Sh AUTHORS 131This software and this manual page were developed by Capabilities 132Limited with funding from Innovate UK and the Department for Science, 133Innovation and Technology for the adoption and diffusion of CHERI 134technology under project 10168042 135.Pq Do CheriBSD feature extraction, maturity, and testing Dc . 136