git: 3088263177da - main - man pages: provide some description for extended errors

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=3088263177da2813dd09364171feadd0e31d1fc3

commit 3088263177da2813dd09364171feadd0e31d1fc3
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2025-12-28 20:41:38 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2025-12-29 01:16:25 +0000

    man pages: provide some description for extended errors
    
    , related functions, and the EXTERROR_VERBOSE environment variable.
    
    Reviewed by:    emaste, mckusick
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D54380
---
 lib/libc/gen/err.3       | 16 ++++++++++++++++
 share/man/man7/environ.7 | 16 +++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/lib/libc/gen/err.3 b/lib/libc/gen/err.3
index 088ead71239b..70a214152a19 100644
--- a/lib/libc/gen/err.3
+++ b/lib/libc/gen/err.3
@@ -114,6 +114,22 @@ preceded by another colon and space unless the
 argument is
 .Dv NULL .
 .Pp
+If the kernel returned an extended error string in addition to the
+.Va errno
+code, the
+.Fn err
+function prints the string with interpolated values for parameters,
+as provided to the corresponding invocation of
+.Xr EXTERROR 9 .
+If the extended error string was not provided, but extended error
+information was, or even if string was provided and the
+.Ev EXTERROR_VERBOSE
+environment variable is present, an additional report is printed.
+The report includes at least the category of the error, the name of
+the source file (if known by the used version of libc),
+the source line number, and parameters.
+The format of the printed string is not contractual and might be changed.
+.Pp
 In the case of the
 .Fn errc ,
 .Fn verrc ,
diff --git a/share/man/man7/environ.7 b/share/man/man7/environ.7
index 51fb6544fc5a..ada2cc45a650 100644
--- a/share/man/man7/environ.7
+++ b/share/man/man7/environ.7
@@ -114,6 +114,18 @@ A startup list of commands read by
 .Xr ex 1
 and
 .Xr vi 1 .
+.It Ev EXTERROR_VERBOSE
+Request the
+.Xr err 3
+and
+.Xr uexterr_gettext
+functions to unconditionally report additional information,
+mostly useful for the (kernel) developer to diagnose the issue.
+See
+.Xr err 3
+and
+.Xr exterror 9
+for more details.
 .It Ev HOME
 A user's login directory, set by
 .Xr login 1
@@ -298,6 +310,7 @@ built-in command in
 .Xr cd 1 ,
 .Xr csh 1 ,
 .Xr env 1 ,
+.Xr err 3 ,
 .Xr ex 1 ,
 .Xr login 1 ,
 .Xr printenv 1 ,
@@ -311,7 +324,8 @@ built-in command in
 .Xr system 3 ,
 .Xr termcap 3 ,
 .Xr termcap 5 ,
-.Xr simd 7
+.Xr simd 7 ,
+.Xr exterror 9
 .Sh HISTORY
 The
 .Nm