strerror.3: Document strerrorname_np() and strerrordesc_np()

strerrorname_np() and strerrordesc_np() were added in glibc 2.32.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 54 insertions, 6 deletions

diff --git a/man3/strerror.3 b/man3/strerror.3
index ac72ad2ecf..8f59e59ad5 100644
--- a/man3/strerror.3
+++ b/man3/strerror.3
@@ -1,5 +1,5 @@
 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
-.\" and Copyright (C) 2005, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2005, 2014, 2020 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -38,12 +38,14 @@
 .\"
 .TH STRERROR 3  2019-03-06 "" "Linux Programmer's Manual"
 .SH NAME
-strerror, strerror_r, strerror_l \- return string describing error number
+strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- return string describing error number
 .SH SYNOPSIS
 .nf
 .B #include <string.h>
 .PP
 .BI "char *strerror(int " errnum );
+.BI "const char *strerrorname_np(int " errnum );
+.BI "const char *strerrordesc_np(int " errnum );
 .PP
 .BI "int strerror_r(int " errnum ", char *" buf ", size_t " buflen );
             /* XSI-compliant */
@@ -60,6 +62,11 @@ Feature Test Macro Requirements for glibc (see
 .RE
 .ad l
 .PP
+.PD 0
+.BR strerrorname_np (),
+.BR strerrordesc_np ():
+    _GNU_SOURCE
+.PP
 .BR strerror_r ():
 .RS 4
 The XSI-compliant version is provided if:
@@ -68,6 +75,7 @@ The XSI-compliant version is provided if:
 .br
 Otherwise, the GNU-specific version is provided.
 .RE
+.PD
 .ad
 .SH DESCRIPTION
 The
@@ -91,6 +99,25 @@ or
 No other library function, including
 .BR perror (3),
 will modify this string.
+.PP
+Like
+.BR strerror (),
+the
+.BR strerrordesc_np ()
+function returns a pointer to a string that describes the error
+code passed in the argument
+.IR errnum ,
+with the difference that the returned string is not translated
+according to the current locale.
+.PP
+The
+.BR strerrorname_np ()
+function returns a pointer to a string containing the name of the error
+code passed in the argument
+.IR errnum .
+For example, given
+.BR EPERM
+as an argument, this function returns a pointer to the string "EPERM".
 .\"
 .SS strerror_r()
 The
@@ -167,6 +194,15 @@ functions return
 the appropriate error description string,
 or an "Unknown error nnn" message if the error number is unknown.
 .PP
+On success,
+.BR strerrorname_np ()
+and
+.BR strerrordesc_np ()
+return the appropriate error description string.
+If
+.I errnum
+is an invalid error number, these functions return NULL.
+.PP
 The XSI-compliant
 .BR strerror_r ()
 function returns 0 on success.
@@ -208,13 +244,17 @@ For an explanation of the terms used in this section, see
 .BR attributes (7).
 .TS
 allbox;
-lbw14 lb lb
+lbw18 lb lb
 l l l.
 Interface	Attribute	Value
 T{
 .BR strerror ()
 T}	Thread safety	MT-Unsafe race:strerror
 T{
+.BR strerrorname_np (),
+.BR strerrordesc ()
+T}	Thread safety	MT-Safe
+T{
 .BR strerror_r (),
 .br
 .BR strerror_l ()
@@ -233,9 +273,12 @@ is specified by POSIX.1-2001 and POSIX.1-2008.
 .BR strerror_l ()
 is specified in POSIX.1-2008.
 .PP
-The GNU-specific
-.BR strerror_r ()
-function is a nonstandard extension.
+The GNU-specific functions
+.BR strerror_r (),
+.BR strerrorname_np (),
+and
+.BR strerrordesc_np ()
+are nonstandard extensions.
 .PP
 POSIX.1-2001 permits
 .BR strerror ()
@@ -263,6 +306,11 @@ This buffer size therefore should be sufficient to avoid an
 .B ERANGE
 error when calling
 .BR strerror_r ().
+.PP
+.BR strerrorname_np ()
+and
+.BR strerrordesc_np ()
+are thread-safe and async-signal-safe.
 .SH SEE ALSO
 .BR err (3),
 .BR errno (3),