From 0b552d524cafbf365659f387478aecba0942c807 Mon Sep 17 00:00:00 2001
From: joerg <joerg@FreeBSD.org>
Date: Sat, 27 Jun 2020 20:55:47 +0000
Subject: [PATCH] Explain how to learn about possible recognized locale names

Posix says that the interpretation of the locale string is
"implementation-defined", so we ought to document what is
actually recognized.

Also add a cross reference to locale(1).

PR:		247553
MFC after:	1 week
---
 lib/libc/locale/setlocale.3 | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/lib/libc/locale/setlocale.3 b/lib/libc/locale/setlocale.3
index 64597333ad8..586d82dd3dc 100644
--- a/lib/libc/locale/setlocale.3
+++ b/lib/libc/locale/setlocale.3
@@ -115,9 +115,24 @@ argument of
 causes
 .Fn setlocale
 to return the current locale.
+.Pp
+The option
+.Fl a
+to the
+.Xr locale 1
+command can be used to display all further possible names for the
+.Fa locale
+argument that are recognized.
+Specifying any unrecognized value for
+.Fa locale
+makes
+.Fn setlocale
+fail.
+.Pp
 By default, C programs start in the
 .Li \&"C"
 locale.
+.Pp
 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.
@@ -150,6 +165,7 @@ and the category
 .Sh ERRORS
 No errors are defined.
 .Sh SEE ALSO
+.Xr locale 1 ,
 .Xr localedef 1 ,
 .Xr catopen 3 ,
 .Xr ctype 3 ,
-- 
2.45.0