LDP: Update original to LDP v3.79

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

diff --git a/original/man3/strerror.3 b/original/man3/strerror.3
index 3ccac23..ecc0fe8 100644 (file)
--- a/original/man3/strerror.3
+++ b/original/man3/strerror.3
@@ -1,6 +1,7 @@
 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
-.\" and Copyright (C) 2005, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2005, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
@@ -20,6 +21,7 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
 .\" References consulted:
 .\"     Linux libc source code
@@ -34,9 +36,9 @@
 .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description
 .\"         Addition of extra material on portability and standards.
 .\"
-.TH STRERROR 3  2012-04-22 "" "Linux Programmer's Manual"
+.TH STRERROR 3  2014-03-18 "" "Linux Programmer's Manual"
 .SH NAME
-strerror, strerror_r \- return string describing error number
+strerror, strerror_r, strerror_l \- return string describing error number
 .SH SYNOPSIS
 .nf
 .B #include <string.h>
@@ -48,20 +50,25 @@ strerror, strerror_r \- return string describing error number
 .sp
 .BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen );
             /* GNU-specific */
+
+.BI "char *strerror_l(int " errnum ", locale_t " locale );
 .fi
 .sp
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
+.ad l
 .sp
-The XSI-compliant version of
-.BR strerror_r ()
-is provided if:
+.BR strerror_r ():
+.RS 4
+The XSI-compliant version is provided if:
 .br
 (_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600) && !\ _GNU_SOURCE
 .br
 Otherwise, the GNU-specific version is provided.
+.RE
+.ad
 .SH DESCRIPTION
 The
 .BR strerror ()
@@ -75,14 +82,17 @@ part of the current locale to select the appropriate language.
 .I errnum
 is
 .BR EINVAL ,
-the returned description will "Invalid argument".)
+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
-.BR strerror ().
-No library function, including
+.BR strerror ()
+or
+.BR strerror_l ().
+No other library function, including
 .BR perror (3),
 will modify this string.
-
+.\"
+.SS strerror_r()
 The
 .BR strerror_r ()
 function is similar to
@@ -130,18 +140,46 @@ bytes are stored (the string may be truncated if
 is too small and
 .I errnum
 is unknown).
-The string always includes a terminating null byte.
-.SH "RETURN VALUE"
+The string always includes a terminating null byte (\(aq\\0\(aq).
+.\"
+.SS strerror_l()
+.BR strerror_l ()
+is like
+.BR strerror (),
+but maps
+.I errnum
+to a locale-dependent error message in the locale specified by
+.IR locale .
+The behavior of
+.BR strerror_l ()
+is undefined if
+.I locale
+is the special locale object
+.BR LC_GLOBAL_LOCALE
+or is not a valid locale object handle.
+.SH RETURN VALUE
 The
-.BR strerror ()
+.BR strerror (),
+.BR strerror_l (),
 and the GNU-specific
 .BR strerror_r ()
 functions return
 the appropriate error description string,
 or an "Unknown error nnn" message if the error number is unknown.
 
+The XSI-compliant
+.BR strerror_r ()
+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 (glibc versions before 2.13).
+
 POSIX.1-2001 and POSIX.1-2008 require that a successful call to
-.BR strerror (3)
+.BR strerror ()
+or
+.BR strerror_l ()
 shall leave
 .I errno
 unchanged, and note that,
@@ -152,15 +190,6 @@ 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,
-a (positive) error number is returned (since glibc 2.13),
-or \-1 is returned and
-.I errno
-is set to indicate the error (glibc versions before 2.13).
 .SH ERRORS
 .TP
 .B EINVAL
@@ -170,11 +199,28 @@ is not a valid error number.
 .TP
 .B ERANGE
 Insufficient storage was supplied to contain the error description string.
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR strerror ()
+function is not thread-safe.
+.LP
+The
+.BR strerror_r ()
+function is thread-safe.
+.\" FIXME . Need a thread-safety statement about strerror_l()
+.SH VERSIONS
+The
+.BR strerror_l ()
+function first appeared in glibc 2.6.
+.SH CONFORMING TO
 .BR strerror ()
-is specified by POSIX.1-2001, C89, C99.
+is specified by POSIX.1-2001, POSIX.1-2008, C89, and C99.
 .BR strerror_r ()
-is specified by POSIX.1-2001.
+is specified by POSIX.1-2001 and POSIX.1-2008.
+
+.BR strerror_l ()
+is specified in POSIX.1-2008.
 
 The GNU-specific
 .BR strerror_r ()
@@ -199,9 +245,19 @@ 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"
+.SH SEE ALSO
 .BR err (3),
 .BR errno (3),
 .BR error (3),
 .BR perror (3),
-.BR strsignal (3)
+.BR strsignal (3),
+.BR locale (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.