[newlib-cygwin] Add documentation for duplocale, freelocale, newlocale, and uselocale.

[Corinna Vinschen <corinna at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=5ef60b7e6a0abad86fe637197f738f8a90b525c8

commit 5ef60b7e6a0abad86fe637197f738f8a90b525c8
Author: Corinna Vinschen <corinna@vinschen.de>
Date:   Mon Aug 15 17:34:40 2016 +0200

    Add documentation for duplocale, freelocale, newlocale, and uselocale.
    
    Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

Diff:
---
 newlib/libc/locale/Makefile.am  |  7 +++-
 newlib/libc/locale/Makefile.in  |  7 +++-
 newlib/libc/locale/duplocale.c  | 36 ++++++++++++++++++++
 newlib/libc/locale/freelocale.c | 34 +++++++++++++++++++
 newlib/libc/locale/newlocale.c  | 75 +++++++++++++++++++++++++++++++++++++++++
 newlib/libc/locale/uselocale.c  | 52 ++++++++++++++++++++++++++++
 6 files changed, 209 insertions(+), 2 deletions(-)

diff --git a/newlib/libc/locale/Makefile.am b/newlib/libc/locale/Makefile.am
index 666ca5f..7312654 100644
--- a/newlib/libc/locale/Makefile.am
+++ b/newlib/libc/locale/Makefile.am
@@ -38,6 +38,11 @@ endif # USE_LIBTOOL
 
 include $(srcdir)/../../Makefile.shared
 
-CHEWOUT_FILES = locale.def
+CHEWOUT_FILES = \
+	duplocale.def \
+	freelocale.def \
+	locale.def \
+	newlocale.def \
+	uselocale.def
 
 CHAPTERS = locale.tex
diff --git a/newlib/libc/locale/Makefile.in b/newlib/libc/locale/Makefile.in
index 43b7f88..0f605f3 100644
--- a/newlib/libc/locale/Makefile.in
+++ b/newlib/libc/locale/Makefile.in
@@ -297,7 +297,12 @@ DOCBOOK_CHEW = ${top_srcdir}/../doc/makedocbook.py
 DOCBOOK_OUT_FILES = $(CHEWOUT_FILES:.def=.xml)
 DOCBOOK_CHAPTERS = $(CHAPTERS:.tex=.xml)
 CLEANFILES = $(CHEWOUT_FILES) $(CHEWOUT_FILES:.def=.ref) $(DOCBOOK_OUT_FILES)
-CHEWOUT_FILES = locale.def
+CHEWOUT_FILES = \
+	duplocale.def \
+	freelocale.def \
+	locale.def \
+	newlocale.def \
+	uselocale.def
 CHAPTERS = locale.tex
 all: all-am
 
diff --git a/newlib/libc/locale/duplocale.c b/newlib/libc/locale/duplocale.c
index 6c4c793..7bd89ea 100644
--- a/newlib/libc/locale/duplocale.c
+++ b/newlib/libc/locale/duplocale.c
@@ -1,3 +1,39 @@
+/*
+FUNCTION
+	<<duplocale>>---duplicate a locale object
+
+INDEX
+	duplocale
+
+INDEX
+	_duplocale_r
+
+ANSI_SYNOPSIS
+	#include <locale.h>
+	locale_t duplocale(locale_t <[locobj]>);
+
+	locale_t _duplocale_r(void *<[reent]>, locale_t <[locobj]>);
+
+DESCRIPTION
+The <<duplocale>> function shall create a duplicate copy of the locale
+object referenced by the <[locobj]> argument.
+
+If the <[locobj]> argument is LC_GLOBAL_LOCALE, duplocale() shall create
+a new locale object containing a copy of the global locale determined by
+the setlocale() function.
+
+The behavior is undefined if the <[locobj]> argument is not a valid locale
+object handle.
+
+RETURNS
+Upon successful completion, the <<duplocale>> function shall return a
+handle for a new locale object.  Otherwise <<duplocale>> shall return
+(locale_t) <<0>> and set errno to indicate the error.
+
+PORTABILITY
+<<duplocale>> is POSIX-1.2008.
+*/
+
 #include <newlib.h>
 #include <reent.h>
 #include <stdlib.h>
diff --git a/newlib/libc/locale/freelocale.c b/newlib/libc/locale/freelocale.c
index d7eb5bf..e18b453 100644
--- a/newlib/libc/locale/freelocale.c
+++ b/newlib/libc/locale/freelocale.c
@@ -1,3 +1,37 @@
+/*
+FUNCTION
+	<<freelocale>>---free resources allocated for a locale object
+
+INDEX
+	freelocale
+
+INDEX
+	_freelocale_r
+
+ANSI_SYNOPSIS
+	#include <locale.h>
+	locale_t freelocale(locale_t <[locobj]>);
+
+	locale_t _freelocale_r(void *<[reent]>, locale_t <[locobj]>);
+
+DESCRIPTION
+The <<freelocale>> function shall cause the resources allocated for a
+locale object returned by a call to the <<newlocale>> or <<duplocale>>
+functions to be released.
+
+The behavior is undefined if the <[locobj]> argument is the special locale
+object LC_GLOBAL_LOCALE or is not a valid locale object handle.
+
+Any use of a locale object that has been freed results in undefined
+behavior.
+
+RETURNS
+None.
+
+PORTABILITY
+<<freelocale>> is POSIX-1.2008.
+*/
+
 #include <newlib.h>
 #include <reent.h>
 #include <stdlib.h>
diff --git a/newlib/libc/locale/newlocale.c b/newlib/libc/locale/newlocale.c
index 224b7ab..239173b 100644
--- a/newlib/libc/locale/newlocale.c
+++ b/newlib/libc/locale/newlocale.c
@@ -1,3 +1,78 @@
+/*
+FUNCTION
+	<<newlocale>>---create or modify a locale object
+
+INDEX
+	newlocale
+
+INDEX
+	_newlocale_r
+
+ANSI_SYNOPSIS
+	#include <locale.h>
+	locale_t newlocale(int <[category_mask]>, const char *<[locale]>,
+			   locale_t <[locobj]>);
+
+	locale_t _newlocale_r(void *<[reent]>, int <[category_mask]>,
+			      const char *<[locale]>, locale_t <[locobj]>);
+
+DESCRIPTION
+The <<newlocale>> function shall create a new locale object or modify an
+existing one.  If the base argument is (locale_t) <<0>>, a new locale
+object shall be created. It is unspecified whether the locale object
+pointed to by base shall be modified, or freed and a new locale object
+created.
+
+The category_mask argument specifies the locale categories to be set or
+modified.  Values for category_mask shall be constructed by a
+bitwise-inclusive OR of the symbolic constants LC_CTYPE_MASK,
+LC_NUMERIC_MASK, LC_TIME_MASK, LC_COLLATE_MASK, LC_MONETARY_MASK, and
+LC_MESSAGES_MASK, or any of the other implementation-defined LC_*_MASK
+values defined in <locale.h>.
+
+For each category with the corresponding bit set in category_mask the
+data from the locale named by locale shall be used. In the case of
+modifying an existing locale object, the data from the locale named by
+locale shall replace the existing data within the locale object. If a
+completely new locale object is created, the data for all sections not
+requested by category_mask shall be taken from the default locale.
+
+The following preset values of locale are defined for all settings of
+category_mask:
+
+"POSIX"	Specifies the minimal environment for C-language translation
+called the POSIX locale.
+
+"C"	Equivalent to "POSIX".
+
+""	Specifies an implementation-defined native environment.  This
+	corresponds to the value of the associated environment variables,
+	LC_* and LANG; see the Base Definitions volume of POSIX.1â??2008,
+	Chapter 7, Locale and Chapter 8, Environment Variables.
+
+If the base argument is not (locale_t) <<0>> and the <<newlocale>>
+function call succeeds, the contents of base are unspecified.
+Applications shall ensure that they stop using base as a locale object
+before calling <<newlocale>>.  If the function call fails and the base
+argument is not (locale_t) <<0>>, the contents of base shall remain
+valid and unchanged.
+
+The behavior is undefined if the base argument is the special locale
+object LC_GLOBAL_LOCALE, or is not a valid locale object handle and is
+not (locale_t) <<0>>.
+
+RETURNS
+Upon successful completion, the <<newlocale>> function shall return a
+handle which the caller may use on subsequent calls to <<duplocale>>,
+<<freelocale>>, and other functions taking a locale_t argument.
+
+Upon failure, the <<newlocale>> function shall return (locale_t) <<0>>
+and set errno to indicate the error.
+
+PORTABILITY
+<<newlocale>> is POSIX-1.2008.
+*/
+
 #include <newlib.h>
 #include <errno.h>
 #include <reent.h>
diff --git a/newlib/libc/locale/uselocale.c b/newlib/libc/locale/uselocale.c
index dbf0d33..810590f 100644
--- a/newlib/libc/locale/uselocale.c
+++ b/newlib/libc/locale/uselocale.c
@@ -1,3 +1,55 @@
+/*
+FUNCTION
+	<<uselocale>>---free resources allocated for a locale object
+
+INDEX
+	uselocale
+
+INDEX
+	_uselocale_r
+
+ANSI_SYNOPSIS
+	#include <locale.h>
+	locale_t uselocale(locale_t <[locobj]>);
+
+	locale_t _uselocale_r(void *<[reent]>, locale_t <[locobj]>);
+
+DESCRIPTION
+The <<uselocale>> function shall set the current locale for the current
+thread to the locale represented by newloc.
+
+The value for the newloc argument shall be one of the following:
+
+1. A value returned by the <<newlocale>> or <<duplocale>> functions
+
+2. The special locale object descriptor LC_GLOBAL_LOCALE
+
+3. (locale_t) <<0>>
+
+Once the <<uselocale>> function has been called to install a thread-local
+locale, the behavior of every interface using data from the current
+locale shall be affected for the calling thread. The current locale for
+other threads shall remain unchanged.
+
+If the newloc argument is (locale_t) <<0>>, the object returned is the
+current locale or LC_GLOBAL_LOCALE if there has been no previous call to
+<<uselocale>> for the current thread.
+
+If the newloc argument is LC_GLOBAL_LOCALE, the thread shall use the
+global locale determined by the <<setlocale>> function.
+
+RETURNS
+Upon successful completion, the <<uselocale>> function shall return the
+locale handle from the previous call for the current thread, or
+LC_GLOBAL_LOCALE if there was no such previous call.  Otherwise,
+<<uselocale>> shall return (locale_t) <<0>> and set errno to indicate
+the error.
+
+
+PORTABILITY
+<<uselocale>> is POSIX-1.2008.
+*/
+
 #include <newlib.h>
 #include <reent.h>
 #include <stdlib.h>