(split) LDP: Update original to LDP v3.40.

[linuxjm/LDP_man-pages.git] / original / man3 / strerror.3

diff --git a/original/man3/strerror.3 b/original/man3/strerror.3
index 37fc95d..3ccac23 100644 (file)
--- a/original/man3/strerror.3
+++ b/original/man3/strerror.3
@@ -34,7 +34,7 @@
 .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description
 .\"         Addition of extra material on portability and standards.
 .\"
-.TH STRERROR 3  2009-03-30 "" "Linux Programmer's Manual"
+.TH STRERROR 3  2012-04-22 "" "Linux Programmer's Manual"
 .SH NAME
 strerror, strerror_r \- return string describing error number
 .SH SYNOPSIS
@@ -66,15 +66,22 @@ Otherwise, the GNU-specific version is provided.
 The
 .BR strerror ()
 function returns a pointer to a string that describes the error
-code passed in the argument \fIerrnum\fP, possibly using the
+code passed in the argument
+.IR errnum ,
+possibly using the
 .B LC_MESSAGES
 part of the current locale to select the appropriate language.
+(For example, if
+.I errnum
+is
+.BR EINVAL ,
+the returned description will "Invalid argument".)
 This string must not be modified by the application, but may be
 modified by a subsequent call to
-.BR perror (3)
-or
 .BR strerror ().
-No library function will modify this string.
+No library function, including
+.BR perror (3),
+will modify this string.
 
 The
 .BR strerror_r ()
@@ -84,7 +91,7 @@ but is
 thread safe.
 This function is available in two versions:
 an XSI-compliant version specified in POSIX.1-2001
-(available since glibc 2.3.4),
+(available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13),
 and a GNU-specific version (available since glibc 2.0).
 The XSI-compliant version is provided with the feature test macros
 settings shown in the SYNOPSIS;
@@ -120,7 +127,10 @@ then at most
 .I buflen
 bytes are stored (the string may be truncated if
 .I buflen
-is too small) and the string always includes a terminating null byte.
+is too small and
+.I errnum
+is unknown).
+The string always includes a terminating null byte.
 .SH "RETURN VALUE"
 The
 .BR strerror ()
@@ -130,12 +140,27 @@ functions return
 the appropriate error description string,
 or an "Unknown error nnn" message if the error number is unknown.
 
+POSIX.1-2001 and POSIX.1-2008 require that a successful call to
+.BR strerror (3)
+shall leave
+.I errno
+unchanged, and note that,
+since no function return value is reserved to indicate an error,
+an application that wishes to check for errors should initialize
+.I errno
+to zero before the call,
+and then check
+.I errno
+after the call.
+
 The XSI-compliant
 .BR strerror_r ()
-function returns 0 on success;
-on error, \-1 is returned and
+function returns 0 on success.
+On error,
+a (positive) error number is returned (since glibc 2.13),
+or \-1 is returned and
 .I errno
-is set to indicate the error.
+is set to indicate the error (glibc versions before 2.13).
 .SH ERRORS
 .TP
 .B EINVAL
@@ -173,6 +198,7 @@ returns a string something like "Error nnn occurred" and sets
 to
 .B EINVAL
 if the error number is unknown.
+C99 and POSIX.1-2008 require the return value to be non-NULL.
 .SH "SEE ALSO"
 .BR err (3),
 .BR errno (3),