Warn against using any categories but LC_CTYPE in setlocale(3) and

list many (hopefully the most important) functions affected by the
locale, such that the CAVEATS sections in individual manual pages
can be kept shorter in the future;
basic idea from millert@; feedback and OK jmc@; OK deraadt@.

1 files changed, 122 insertions, 3 deletions

diff --git a/lib/libc/locale/setlocale.3 b/lib/libc/locale/setlocale.3
index 82af6f47162..f34bcd8926a 100644
--- a/lib/libc/locale/setlocale.3
+++ b/lib/libc/locale/setlocale.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: setlocale.3,v 1.22 2018/04/04 14:57:51 schwarze Exp $
+.\"	$OpenBSD: setlocale.3,v 1.23 2019/01/13 22:57:08 schwarze Exp $
 .\"	$NetBSD: setlocale.3,v 1.3 1997/07/14 23:19:47 kleink Exp $
 .\"
 .\" Copyright (c) 1993
@@ -33,7 +33,7 @@
 .\"
 .\"	@(#)setlocale.3	8.1 (Berkeley) 6/9/93
 .\"
-.Dd $Mdocdate: April 4 2018 $
+.Dd $Mdocdate: January 13 2019 $
 .Dt SETLOCALE 3
 .Os
 .Sh NAME
@@ -78,7 +78,8 @@ and
 C library.
 A category of
 .Dv LC_ALL
-sets the entire locale generically.
+sets the entire locale generically, which is strongly discouraged for
+security reasons in portable programs.
 .Pp
 The syntax and semantics of the
 .Fa locale
@@ -126,6 +127,29 @@ locale.
 The only function in the library that sets the locale is
 .Fn setlocale ;
 the locale is never changed as a side effect of some other routine.
+.Pp
+The
+.Dv LC_CTYPE
+category modifies the behaviour of at least the following functions:
+.Xr iswctype 3 ,
+.Xr mblen 3 ,
+.Xr mbrlen 3 ,
+.Xr mbrtowc 3 ,
+.Xr mbsrtowcs 3 ,
+.Xr mbstowcs 3 ,
+.Xr mbtowc 3 ,
+.Xr towctrans 3 ,
+.Xr towlower 3 ,
+.Xr towupper 3 ,
+.Xr wcrtomb 3 ,
+.Xr wcscasecmp 3 ,
+.Xr wcsrtombs 3 ,
+.Xr wcstombs 3 ,
+.Xr wctomb 3 ,
+.Xr wctrans 3 ,
+.Xr wctype 3 ,
+and the functions documented in
+.Xr iswalnum 3 .
 .Sh RETURN VALUES
 In case of success,
 .Fn setlocale
@@ -205,3 +229,98 @@ The
 .Fn setlocale
 function first appeared in
 .Bx 4.4 .
+.Sh CAVEATS
+On systems other than
+.Ox ,
+calling
+.Fn setlocale
+or
+.Xr uselocale 3
+with a
+.Fa category
+other than
+.Dv LC_CTYPE
+can cause erratic behaviour of many library functions.
+For security reasons, make sure that portable programs only use
+.Dv LC_CTYPE .
+.Pp
+For example, the following functions may be affected.
+The list is probably incomplete.
+For example, additional library functions may be impacted
+if they directly or indirectly call affected functions,
+or if they attempt to imitate aspects of their behaviour.
+Functions that are not standardized may be affected too.
+.Bl -tag -width Ds
+.It Dv LC_COLLATE
+.Xr glob 3 ,
+.Xr strcoll 3 ,
+.Xr strxfrm 3 ,
+.Xr wcscoll 3 ,
+.Xr wcsxfrm 3 ,
+and the functions documented in
+.Xr regexec 3
+.It Dv LC_MESSAGES
+.Xr catgets 3 ,
+.Xr catopen 3 ,
+.Xr nl_langinfo 3 ,
+.Xr perror 3 ,
+.Xr psignal 3 ,
+.Xr strerror 3 ,
+.Xr strsignal 3 ,
+and the functions documented in
+.Xr err 3
+.It Dv LC_MONETARY
+.Xr localeconv 3 ,
+.Xr nl_langinfo 3 ,
+.Fn strfmon
+.It Dv LC_NUMERIC
+.Xr atof 3 ,
+.Xr localeconv 3 ,
+.Xr nl_langinfo 3 ,
+.Fn strfmon ,
+and the functions documented in
+.Xr printf 3 ,
+.Xr scanf 3 ,
+.Xr strtod 3 ,
+.Xr wcstod 3 ,
+.Xr wprintf 3 ,
+.Xr wscanf 3 .
+This category is particularly dangerous because it can cause bugs
+in the parsing and formatting of numbers, for example failures to
+recognize or properly write decimal points.
+.It Dv LC_TIME
+.Fn getdate ,
+.Xr nl_langinfo 3 ,
+.Xr strftime 3 ,
+.Xr strptime 3 .
+Similarly, this is prone to causing bugs in the parsing and formatting
+of date strings.
+.It Dv LC_CTYPE
+On systems other than
+.Ox ,
+this category may affect the behaviour of additional functions,
+for example:
+.Xr btowc 3 ,
+.Xr isalnum 3 ,
+.Xr isalpha 3 ,
+.Xr isblank 3 ,
+.Xr iscntrl 3 ,
+.Xr isdigit 3 ,
+.Xr isgraph 3 ,
+.Xr islower 3 ,
+.Xr isprint 3 ,
+.Xr ispunct 3 ,
+.Xr isspace 3 ,
+.Xr isupper 3 ,
+.Xr isxdigit 3 ,
+.Xr mbsinit 3 ,
+.Xr strcasecmp 3 ,
+.Xr strcoll 3 ,
+.Xr strxfrm 3 ,
+.Xr tolower 3 ,
+.Xr toupper 3 ,
+.Xr vis 3 ,
+.Xr wcscoll 3 ,
+.Xr wcsxfrm 3 ,
+.Xr wctob 3
+.El