Add manual pages for POSIX locale extensions duplocale/freelocale/newlocale/uselocale

diff --git a/man3/duplocale.3 b/man3/duplocale.3
new file mode 100644 (file)
index 0000000..9758be2
--- /dev/null
+++ b/man3/duplocale.3
@@ -0,0 +1 @@
+.so man3/posix_locale.3
\ No newline at end of file

diff --git a/man3/freelocale.3 b/man3/freelocale.3
new file mode 100644 (file)
index 0000000..9758be2
--- /dev/null
+++ b/man3/freelocale.3
@@ -0,0 +1 @@
+.so man3/posix_locale.3
\ No newline at end of file

diff --git a/man3/newlocale.3 b/man3/newlocale.3
new file mode 100644 (file)
index 0000000..9758be2
--- /dev/null
+++ b/man3/newlocale.3
@@ -0,0 +1 @@
+.so man3/posix_locale.3
\ No newline at end of file

diff --git a/man3/posix_locale.3 b/man3/posix_locale.3
new file mode 100644 (file)
index 0000000..78e77e6
--- /dev/null
+++ b/man3/posix_locale.3
@@ -0,0 +1,147 @@
+.\" This file is part of the Public Domain C Library (PDCLib).\r
+.\" Permission is granted to use, modify, and / or redistribute at will.\r
+.\"\r
+.Dd\r
+.Dt posix_locale 3\r
+.Os\r
+.\"\r
+.Sh NAME\r
+.Nm posix_locale\r
+.Nd POSIX extended locale functions\r
+.\"\r
+.Sh SYNOPSIS\r
+.Sy #define _POSIX_C_SOURCE >= 200112L\r
+.In locale.h\r
+.Vt typedef <anonymous> locale_t;\r
+.br\r
+#define \r
+.Va LC_GLOBAL_LOCALE\r
+<constant of type locale_t>;\r
+.Fn "locale_t uselocale" "locale_t newlocale"\r
+.Fn "locale_t duplocale" "locale_t loc"\r
+.Fn "locale_t newlocale" "int category_mask" "const char *locale" "locale_t base"\r
+.Fn "void freelocale" "locale_t loc"\r
+.\"\r
+.Sh DESCRIPTION\r
+The ISO C standard defines the\r
+.Xr setlocale 3\r
+function, which can be used for modifying the application global locale. In \r
+multithreaded programs, it can sometimes be useful to allow a thread to, either\r
+temporarily or permanently, assume a different locale from the rest of the \r
+application. POSIX defines extended locale functions which permit this.\r
+.\"\r
+.Pp\r
+The function\r
+.Fn uselocale\r
+is used to change the locale of the current thread. If \r
+.Fa newlocale\r
+is the symbolic constant\r
+.Dv LC_GLOBAL_LOCALE ,\r
+then the thread locale will be set to the application global locale. If\r
+.Fa newlocale\r
+is\r
+.Dv NULL ,\r
+then the locale will not be changed. Otherwise, \r
+.Fa newlocale\r
+should be a value returned from either of the\r
+.Fn newlocale\r
+or\r
+.Fn duplocale\r
+functions. The return value will be the previous thread locale; or \r
+.Dv LC_GLOBAL_LOCALE\r
+if the thread has no current locale.\r
+.Pp\r
+.\"\r
+The function\r
+.Fn duplocale\r
+is used to make an exact copy of an existing locale. The passed locale object \r
+must have been returned from a call to either\r
+.Fn duplocale\r
+or\r
+.Fn newlocale .\r
+.Pp\r
+.\"\r
+The function\r
+.Fn newlocale\r
+is used to modify an existing locale or create a new locale. The returned locale\r
+will have the properties defined by\r
+.Fa category_mask\r
+set to the values from\r
+.Fa locale\r
+as per \r
+.Xr setlocale 3 ,\r
+with the remainder being taken from either\r
+.Fa base\r
+(which must be a locale object previously returned by\r
+.Fn duplocale\r
+or\r
+.Fn newlocale )\r
+if it is specified, or otherwise from the "C" locale.\r
+.Pp\r
+It is undefined if \r
+.Fn newlocale\r
+modifies\r
+.Fa base\r
+or frees it and creates a new locale.\r
+.Pp\r
+.\"\r
+The \r
+.Fn freelocale\r
+function is used to free a locale previously created via\r
+.Fn duplocale\r
+or\r
+.Fn newlocale .\r
+.\"\r
+.\"\r
+.Sh ERRORS\r
+For uselocale,\r
+.Er EINVAL\r
+may be returned if\r
+.Fa locale\r
+is not a valid locale.\r
+.Pp\r
+.\"\r
+For \r
+.Fn duplocale ,\r
+.Bl -tag -width 8\r
+.It Er EINVAL\r
+may be returned if\r
+.Fa locale\r
+is not a valid locale\r
+.It Er ENOMEM\r
+shall be returned if the system had insufficient memory to satisfy the request.\r
+.El\r
+.Pp\r
+.\"\r
+For \r
+.Fn newlocale ,\r
+.Bl -tag -width 8\r
+.It Er EINVAL\r
+shall be returned if \r
+.Fa category_mask\r
+contains a bit which does not correspond to a valid category, and may be \r
+returned if\r
+.Fa locale\r
+is not a valid locale object.\r
+.It Er ENOMEM\r
+shall be returned if the system did not have enough memory to allocate a new \r
+locale object or read the locale data\r
+.It Er ENOENT\r
+shall be returned if the locale specified does not contain data for all the \r
+specified categories\r
+.El\r
+.Pp\r
+.\"\r
+.Fn freelocale\r
+has no errors\r
+.\"\r
+.Sh IMPLEMENTATION NOTES\r
+None\r
+.\"\r
+.Sh SEE ALSO\r
+.Xr lconv 3\r
+.Xr setlocale 3\r
+.\"\r
+.Sh STANDARDS\r
+Conforming to\r
+.St -p1003.1-2008 .
\ No newline at end of file

diff --git a/man3/uselocale.3 b/man3/uselocale.3
new file mode 100644 (file)
index 0000000..9758be2
--- /dev/null
+++ b/man3/uselocale.3
@@ -0,0 +1 @@
+.so man3/posix_locale.3
\ No newline at end of file