---
name: "uexterror"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/uexterror"
---

# uexterror(3)

provide extended error information from user-space code

## NAME

**uexterror** – provide extended error information from user-space code

## SYNOPSIS

```
#define UEXTERR_CATEGORY "path/to/this/file.c"
```

**#include \<uexterror.h\>**

*void*\

**UEXTERROR**(*int error*, *const char \*msg*, *...*);

## DESCRIPTION

The **uexterror** framework allows user-space code to report errors using the same [exterror(9)](/exterror/9.md) infrastructure the kernel uses to return additional information about an error along with the standard [errno(3)](/errno/3.md) error code, which is terse and often lacking context.

The terseness is especially visible with commonly overloaded error codes like EINVAL or 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 *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. **uexterror** attaches additional data to the error itself and records the error category and the source code file line number. The intent of **uexterror** is to make it easier for a user to identify the cause of the error.

## USAGE

Before **uexterror** can be used in the given source .c file, the category of extended errors must be defined. This can be done by setting the *UEXTERR\_CATEGORY* macro to a string containing the name of the file relative to *src/sys* directory.

A typical code fragment to report an error is to set errno

errno = EINVAL;

An extended error can augment the error code with additional information:

UEXTERROR(EINVAL, "Invalid length"));

The error data and metadata is saved in the current thread storage. The metadata includes the category and the source file line number.

Arguments to the **UEXTERROR**() macro:

- The first argument to **UEXTERROR**() is the errno error code.

- The second argument is a constant string with the unbound lifetime, which should tersely provide enough human-readable details about the error.

- The **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.

  The format specifier must be for an character, integer, or pointer type. Note that userspace printing assumes all types such as are 64-bit and prints them accordingly. Signed integer types should thus be cast to or similar to insure proper sign extension.

Note that unlike its kernel counterpart EXTERROR(9) the **uexterror** macro does not return a value and sets [errno(3)](/errno/3.md) directly.

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 **NO\_UEXTERR\_STRINGS** macro defined.

## SEE ALSO

[err(3)](/err/3.md), [errno(3)](/errno/3.md), [uexterr\_gettext(3)](/uexterr_gettext/3.md), [exterror(9)](/exterror/9.md)

## HISTORY

The **uexterror** facility was introduced in FreeBSD 16.0.

## 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 (“CheriBSD feature extraction, maturity, and testing”).