diff options
Diffstat (limited to 'man3/strerror.3')
| -rw-r--r-- | man3/strerror.3 | 68 |
1 files changed, 35 insertions, 33 deletions
diff --git a/man3/strerror.3 b/man3/strerror.3 index 5ed507e..89f4e9b 100644 --- a/man3/strerror.3 +++ b/man3/strerror.3 @@ -17,7 +17,7 @@ .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description .\" Addition of extra material on portability and standards. .\" -.TH strerror 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strerror 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- return string describing error number @@ -27,31 +27,31 @@ Standard C library .SH SYNOPSIS .nf .B #include <string.h> -.PP +.P .BI "char *strerror(int " errnum ); .BI "const char *strerrorname_np(int " errnum ); .BI "const char *strerrordesc_np(int " errnum ); -.PP +.P .BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); /* XSI-compliant */ -.PP +.P .BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); /* GNU-specific */ -.PP +.P .BI "char *strerror_l(int " errnum ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strerrorname_np (), .BR strerrordesc_np (): .nf _GNU_SOURCE .fi -.PP +.P .BR strerror_r (): .nf The XSI-compliant version is provided if: @@ -72,15 +72,16 @@ part of the current locale to select the appropriate language. is .BR EINVAL , the returned description will be "Invalid argument".) -This string must not be modified by the application, but may be -modified by a subsequent call to +This string must not be modified by the application, +and the returned pointer will be invalidated on a subsequent call to .BR strerror () or -.BR strerror_l (). +.BR strerror_l (), +or if the thread that obtained the string exits. No other library function, including .BR perror (3), will modify this string. -.PP +.P Like .BR strerror (), the @@ -90,7 +91,7 @@ code passed in the argument .IR errnum , with the difference that the returned string is not translated according to the current locale. -.PP +.P The .BR strerrorname_np () function returns a pointer to a string containing the name of the error @@ -99,14 +100,18 @@ code passed in the argument For example, given .B EPERM as an argument, this function returns a pointer to the string "EPERM". +Given +.B 0 +as an argument, +this function returns a pointer to the string "0". .\" .SS strerror_r() -The .BR strerror_r () -function is similar to +is like .BR strerror (), -but is -thread safe. +but might use the supplied buffer +.I buf +instead of allocating one internally. This function is available in two versions: an XSI-compliant version specified in POSIX.1-2001 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), @@ -121,7 +126,7 @@ is defined by default with the value 200112L, so that the XSI-compliant version of .BR strerror_r () is provided by default. -.PP +.P The XSI-compliant .BR strerror_r () is preferred for portable applications. @@ -129,7 +134,7 @@ It returns the error string in the user-supplied buffer .I buf of length .IR buflen . -.PP +.P The GNU-specific .BR strerror_r () returns a pointer to a string containing the error message. @@ -174,7 +179,7 @@ and the GNU-specific functions return the appropriate error description string, or an "Unknown error nnn" message if the error number is unknown. -.PP +.P On success, .BR strerrorname_np () and @@ -183,7 +188,7 @@ return the appropriate error description string. If .I errnum is an invalid error number, these functions return NULL. -.PP +.P The XSI-compliant .BR strerror_r () function returns 0 on success. @@ -192,7 +197,7 @@ a (positive) error number is returned (since glibc 2.13), or \-1 is returned and .I errno is set to indicate the error (before glibc 2.13). -.PP +.P POSIX.1-2001 and POSIX.1-2008 require that a successful call to .BR strerror () or @@ -231,7 +236,7 @@ T{ T} Thread safety T{ .na .nh -MT-Unsafe race:strerror +MT-Safe T} T{ .na @@ -246,7 +251,10 @@ T{ .BR strerror_l () T} Thread safety MT-Safe .TE -.sp 1 +.P +Before glibc 2.32, +.BR strerror () +is not MT-Safe. .SH STANDARDS .TP .BR strerror () @@ -265,7 +273,7 @@ POSIX.1-2008. .TQ .BR strerrordesc_np () GNU. -.PP +.P POSIX.1-2001 permits .BR strerror () to set @@ -302,13 +310,6 @@ POSIX.1-2008. .BR strerrordesc_np () glibc 2.32. .SH NOTES -The GNU C Library uses a buffer of 1024 characters for -.BR strerror (). -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 () @@ -319,4 +320,5 @@ are thread-safe and async-signal-safe. .BR error (3), .BR perror (3), .BR strsignal (3), -.BR locale (7) +.BR locale (7), +.BR signal-safety (7) |