[src/trunk]: src Document strerror_l()

[kre <kre%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a288fdca26ac
branches:  trunk
changeset: 746236:a288fdca26ac
user:      kre <kre%NetBSD.org@localhost>
date:      Wed Mar 25 18:45:42 2020 +0000

description:
Document strerror_l()

While here also document (but comment it out since it isn't
available - yet) strerror_lr().   To include that, simply
uncomment the relevant lines, and (twice I think) s/returns/return/
on lines just after currently commented out lines (that is, it
currently says, "A returns" after the comments are returned, we
need it to be "A and B return" - the "and B" appears when the comment
markers are removed, removing the 's' from returns must be done manually.

In addition to adding strerror_l() some additional enhancements were
made to the general strerror() doc.

diffstat:

 distrib/sets/lists/comp/mi   |    5 +-
 lib/libc/string/Makefile.inc |    3 +-
 lib/libc/string/strerror.3   |  121 ++++++++++++++++++++++++++++++++++++++----
 3 files changed, 114 insertions(+), 15 deletions(-)

diffs (275 lines):

diff -r 4035d26e3000 -r a288fdca26ac distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Wed Mar 25 18:42:16 2020 +0000
+++ b/distrib/sets/lists/comp/mi        Wed Mar 25 18:45:42 2020 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.2315 2020/03/25 17:13:49 christos Exp $
+#      $NetBSD: mi,v 1.2316 2020/03/25 18:45:42 kre Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp                           comp-sys-root
@@ -9989,6 +9989,7 @@
 ./usr/share/man/cat3/strcspn.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/strdup.0                  comp-c-catman           .cat
 ./usr/share/man/cat3/strerror.0                        comp-c-catman           .cat
+./usr/share/man/cat3/strerror_l.0              comp-c-catman           .cat
 ./usr/share/man/cat3/strerror_r.0              comp-c-catman           .cat
 ./usr/share/man/cat3/stresep.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/strfmon.0                 comp-c-catman           .cat
@@ -17993,6 +17994,7 @@
 ./usr/share/man/html3/strcspn.html             comp-c-htmlman          html
 ./usr/share/man/html3/strdup.html              comp-c-htmlman          html
 ./usr/share/man/html3/strerror.html            comp-c-htmlman          html
+./usr/share/man/html3/strerror_l.html          comp-c-htmlman          html
 ./usr/share/man/html3/strerror_r.html          comp-c-htmlman          html
 ./usr/share/man/html3/stresep.html             comp-c-htmlman          html
 ./usr/share/man/html3/strfmon.html             comp-c-htmlman          html
@@ -26029,6 +26031,7 @@
 ./usr/share/man/man3/strcspn.3                 comp-c-man              .man
 ./usr/share/man/man3/strdup.3                  comp-c-man              .man
 ./usr/share/man/man3/strerror.3                        comp-c-man              .man
+./usr/share/man/man3/strerror_l.3              comp-c-man              .man
 ./usr/share/man/man3/strerror_r.3              comp-c-man              .man
 ./usr/share/man/man3/stresep.3                 comp-c-man              .man
 ./usr/share/man/man3/strfmon.3                 comp-c-man              .man
diff -r 4035d26e3000 -r a288fdca26ac lib/libc/string/Makefile.inc
--- a/lib/libc/string/Makefile.inc      Wed Mar 25 18:42:16 2020 +0000
+++ b/lib/libc/string/Makefile.inc      Wed Mar 25 18:45:42 2020 +0000
@@ -1,5 +1,5 @@
 #      from: @(#)Makefile.inc  8.1 (Berkeley) 6/4/93
-#      $NetBSD: Makefile.inc,v 1.83 2017/01/12 00:35:38 christos Exp $
+#      $NetBSD: Makefile.inc,v 1.84 2020/03/25 18:45:42 kre Exp $
 
 # string sources
 .PATH: ${ARCHDIR}/string ${.CURDIR}/string
@@ -63,6 +63,7 @@
 MLINKS+=memchr.3 memrchr.3
 MLINKS+=strtok.3 strtok_r.3
 MLINKS+=strerror.3 strerror_r.3 strerror.3 perror.3 \
+       strerror.3 strerror_l.3 \
        strerror.3 sys_errlist.3 strerror.3 sys_nerr.3
 MLINKS+=strdup.3 strndup.3
 MLINKS+=strsep.3 stresep.3
diff -r 4035d26e3000 -r a288fdca26ac lib/libc/string/strerror.3
--- a/lib/libc/string/strerror.3        Wed Mar 25 18:42:16 2020 +0000
+++ b/lib/libc/string/strerror.3        Wed Mar 25 18:45:42 2020 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: strerror.3,v 1.19 2017/07/03 21:32:50 wiz Exp $
+.\" $NetBSD: strerror.3,v 1.20 2020/03/25 18:45:42 kre Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -32,12 +32,14 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)strerror.3 8.1 (Berkeley) 6/9/93
-.Dd May 9, 2015
+.Dd March 24, 2020
 .Dt STRERROR 3
 .Os
 .Sh NAME
 .Nm perror ,
 .Nm strerror ,
+.Nm strerror_l ,
+.\" .Nm strerror_lr ,
 .Nm strerror_r ,
 .Nm sys_errlist ,
 .Nm sys_nerr
@@ -56,9 +58,15 @@
 .Fn strerror "int errnum"
 .Ft int
 .Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen"
+.Ft "char *"
+.Fn strerror_l "int errnum" "locale_t loc"
+.\".Ft int
+.\".Fn strerror_lr "int errnum" "char *strerrbuf" "size_t buflen" "locale_t loc"
 .Sh DESCRIPTION
 The
 .Fn strerror ,
+.Fn strerror_l ,
+.\".Fn strerror_lr ,
 .Fn strerror_r ,
 and
 .Fn perror
@@ -71,6 +79,8 @@
 .Fa errnum
 and returns a pointer to the corresponding
 message string.
+The application should not attempt to modify the
+returned string, it may be shared, or read only.
 .Pp
 The
 .Fn strerror_r
@@ -81,6 +91,24 @@
 characters and returns 0 upon success.
 .Pp
 The
+.Fn strerror_l
+function is like
+.Fn strerror
+but provides in
+.Fa loc
+the locale to be used to obtain the language for the message,
+rather than using the application's current locale.
+.\".Pp
+.\"The
+.\".Fn strerror_lr
+.\"function is to
+.\".Fn strerror_l
+.\"as
+.\".Fn strerror_r
+.\"is to
+.\".Fn strerror .
+.Pp
+The
 .Fn perror
 function finds the error message corresponding to the current
 value of the global variable
@@ -106,20 +134,35 @@
 .Fn perror ;
 they are more flexible and also print the program name.
 .Pp
-If the error number is not recognized, these functions pass an error message
+If the error number is not recognized, these functions return an error message
 string containing
+.\" , in the appropriate language,
 .Dq Li "Unknown error:\ "
 followed by the error number in decimal.
 To warn about this,
 .Fn strerror
-sets
+and
+.Fn strerror_l
+set
 .Dv errno
 to
 .Er EINVAL ,
 and
 .Fn strerror_r
+.\"and
+.\".Fn strerror_lr
 returns
 .Er EINVAL .
+In other cases, except where noted below,
+.Dv errno
+is not altered, so applications should set it to a known value
+(usually zero) before calling either
+.Fn strerror
+or
+.Fn strerror_l
+if the resulting value in
+.Dv errno
+is to be tested for this condition.
 Error numbers recognized by this implementation fall in
 the range 0 <
 .Fa errnum
@@ -132,6 +175,8 @@
 .Fa buflen )
 to contain the error string,
 .Fn strerror_r
+.\" and
+.\" .Fn strerror_lr
 returns
 .Er ERANGE
 and
@@ -140,8 +185,20 @@
 .Dv NUL
 terminated to fit the length specified by
 .Fa buflen .
+In extraordinary cases, it is possible that the internal
+buffer used by
+.Fn strerror
+and
+.Fn strerror_l
+may be too small for a translated message,
+in which case it will be truncated as indicated for
+.Fn strerror_r
+and
+.Dv errno
+will be set to
+.Er ERANGE .
 .Pp
-The message strings can be accessed directly using the external
+The POSIX locale message strings can be accessed directly using the external
 array
 .Va sys_errlist .
 The external value
@@ -149,10 +206,9 @@
 contains a count of the messages in
 .Va sys_errlist .
 The use of these variables is deprecated;
+one of the
 .Fn strerror
-or
-.Fn strerror_r
-should be used instead.
+family of functions should be used instead.
 .Sh SEE ALSO
 .Xr intro 2 ,
 .Xr err 3 ,
@@ -169,6 +225,10 @@
 .Fn strerror_r
 function conforms to
 .St -p1003.1-2001 .
+The
+.Fn strerror_l
+function conforms to
+.St -p1003.1-2008 .
 .Sh HISTORY
 The
 .Fn perror
@@ -182,15 +242,50 @@
 .Fn strerror_r
 function first appeared in
 .Nx 4.0 .
+The
+.Fn strerror_l
+function was first released in
+.Nx 7.0 .
+.\"The
+.\".Fn strerror_lr
+.\"function first appeared in
+.\".Nx 10.0 .
 .Sh BUGS
-For unknown error numbers, the
+The
 .Fn strerror
-function will return its result in a static buffer which
-may be overwritten by subsequent calls.
+function may return its result in a static buffer which
+will be overwritten by subsequent calls.
+For portable use, this must be assumed to be a subsequent
+call from the current, or any other, thread in the process.
+This implementation limits the issue to calls from the
+current thread.
+The
+.Fn strerror_l
+function has a similar restriction, but even in other
+implementations, is required to use thread local storage,
+so only other calls from the calling thread can overwrite
+the result.
+Both
+.Fn strerror
+and
+.Fn strerror_l
+use the same thread local storage, a call to either will destroy
+the result from an earlier call by the same thread of either of them.
+.\"
+.\" Is this following para really true any more?   All the strerror()
+.\" family of functions return the result in a malloc'd array (or if
+.\" ! _REENTRANT a static buffer in the function) or in a buffer
+.\" provided by the caller - nothing actually returns a pointer into
+.\" sys_errlist[] any more (strerror_ss() excepted, but we ignore that).
+.\" The POSIX (and historic) functions had no "const" qualifier.
+.\" POSIX does say that callers must not (attempt to) modify the result,
+.\" but for our implementation I see no defect that can cause.
 .Pp
-The return type for
+The return types for
 .Fn strerror
-is missing a type-qualifier; it should actually be
+and
+.Fn strerror_l
+are both missing a type-qualifier; it should actually be
 .Vt const char * .
 .Pp
 Programs that use the deprecated