Module Name:    src
Committed By:   kre
Date:           Wed Mar 25 18:45:42 UTC 2020

Modified Files:
        src/distrib/sets/lists/comp: mi
        src/lib/libc/string: Makefile.inc strerror.3

Log Message:
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.


To generate a diff of this commit:
cvs rdiff -u -r1.2315 -r1.2316 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.83 -r1.84 src/lib/libc/string/Makefile.inc
cvs rdiff -u -r1.19 -r1.20 src/lib/libc/string/strerror.3

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2315 src/distrib/sets/lists/comp/mi:1.2316
--- src/distrib/sets/lists/comp/mi:1.2315	Wed Mar 25 17:13:49 2020
+++ src/distrib/sets/lists/comp/mi	Wed Mar 25 18:45:42 2020
@@ -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

Index: src/lib/libc/string/Makefile.inc
diff -u src/lib/libc/string/Makefile.inc:1.83 src/lib/libc/string/Makefile.inc:1.84
--- src/lib/libc/string/Makefile.inc:1.83	Thu Jan 12 00:35:38 2017
+++ src/lib/libc/string/Makefile.inc	Wed Mar 25 18:45:42 2020
@@ -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+=strchr.3 strchrnul.3
 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

Index: src/lib/libc/string/strerror.3
diff -u src/lib/libc/string/strerror.3:1.19 src/lib/libc/string/strerror.3:1.20
--- src/lib/libc/string/strerror.3:1.19	Mon Jul  3 21:32:50 2017
+++ src/lib/libc/string/strerror.3	Wed Mar 25 18:45:42 2020
@@ -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 @@ function accepts an error number argumen
 .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 @@ for a maximum of
 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 @@ family of functions is preferable to
 .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 @@ If insufficient storage is provided in
 .Fa buflen )
 to contain the error string,
 .Fn strerror_r
+.\" and
+.\" .Fn strerror_lr
 returns
 .Er ERANGE
 and
@@ -140,8 +185,20 @@ will contain an error message that has b
 .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 @@ The external value
 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 @@ The
 .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 @@ The
 .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 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
-function will return its result in a static buffer which
-may be overwritten by subsequent calls.
+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

Reply via email to