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

@@ -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 ,

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