summaryrefslogtreecommitdiffstats
path: root/man3/strerror.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/strerror.368
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)