From d2c55aa77d989fae7760bd8c9e2b0f8a36b661a2 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sat, 17 Oct 2020 22:29:50 +0200 Subject: [PATCH] strerror.3: Document strerrorname_np() and strerrordesc_np() strerrorname_np() and strerrordesc_np() were added in glibc 2.32. Signed-off-by: Michael Kerrisk --- man3/strerror.3 | 60 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 54 insertions(+), 6 deletions(-) diff --git a/man3/strerror.3 b/man3/strerror.3 index ac72ad2ec..8f59e59ad 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 +.\" and Copyright (C) 2005, 2014, 2020 Michael Kerrisk .\" .\" %%%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 .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),