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
