From 5ef60b7e6a0abad86fe637197f738f8a90b525c8 Mon Sep 17 00:00:00 2001 From: Corinna Vinschen Date: Mon, 15 Aug 2016 17:34:40 +0200 Subject: [PATCH] Add documentation for duplocale, freelocale, newlocale, and uselocale. Signed-off-by: Corinna Vinschen --- 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 666ca5f39..7312654e1 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 43b7f8840..0f605f3ef 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 6c4c79313..7bd89eafc 100644 --- a/newlib/libc/locale/duplocale.c +++ b/newlib/libc/locale/duplocale.c @@ -1,3 +1,39 @@ +/* +FUNCTION + <>---duplicate a locale object + +INDEX + duplocale + +INDEX + _duplocale_r + +ANSI_SYNOPSIS + #include + locale_t duplocale(locale_t <[locobj]>); + + locale_t _duplocale_r(void *<[reent]>, locale_t <[locobj]>); + +DESCRIPTION +The <> 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 <> function shall return a +handle for a new locale object. Otherwise <> shall return +(locale_t) <<0>> and set errno to indicate the error. + +PORTABILITY +<> is POSIX-1.2008. +*/ + #include #include #include diff --git a/newlib/libc/locale/freelocale.c b/newlib/libc/locale/freelocale.c index d7eb5bf8f..e18b45333 100644 --- a/newlib/libc/locale/freelocale.c +++ b/newlib/libc/locale/freelocale.c @@ -1,3 +1,37 @@ +/* +FUNCTION + <>---free resources allocated for a locale object + +INDEX + freelocale + +INDEX + _freelocale_r + +ANSI_SYNOPSIS + #include + locale_t freelocale(locale_t <[locobj]>); + + locale_t _freelocale_r(void *<[reent]>, locale_t <[locobj]>); + +DESCRIPTION +The <> function shall cause the resources allocated for a +locale object returned by a call to the <> or <> +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 +<> is POSIX-1.2008. +*/ + #include #include #include diff --git a/newlib/libc/locale/newlocale.c b/newlib/libc/locale/newlocale.c index 224b7abcc..239173bca 100644 --- a/newlib/libc/locale/newlocale.c +++ b/newlib/libc/locale/newlocale.c @@ -1,3 +1,78 @@ +/* +FUNCTION + <>---create or modify a locale object + +INDEX + newlocale + +INDEX + _newlocale_r + +ANSI_SYNOPSIS + #include + 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 <> 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 . + +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 <> +function call succeeds, the contents of base are unspecified. +Applications shall ensure that they stop using base as a locale object +before calling <>. 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 <> function shall return a +handle which the caller may use on subsequent calls to <>, +<>, and other functions taking a locale_t argument. + +Upon failure, the <> function shall return (locale_t) <<0>> +and set errno to indicate the error. + +PORTABILITY +<> is POSIX-1.2008. +*/ + #include #include #include diff --git a/newlib/libc/locale/uselocale.c b/newlib/libc/locale/uselocale.c index dbf0d3393..810590fc0 100644 --- a/newlib/libc/locale/uselocale.c +++ b/newlib/libc/locale/uselocale.c @@ -1,3 +1,55 @@ +/* +FUNCTION + <>---free resources allocated for a locale object + +INDEX + uselocale + +INDEX + _uselocale_r + +ANSI_SYNOPSIS + #include + locale_t uselocale(locale_t <[locobj]>); + + locale_t _uselocale_r(void *<[reent]>, locale_t <[locobj]>); + +DESCRIPTION +The <> 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 <> or <> functions + +2. The special locale object descriptor LC_GLOBAL_LOCALE + +3. (locale_t) <<0>> + +Once the <> 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 +<> for the current thread. + +If the newloc argument is LC_GLOBAL_LOCALE, the thread shall use the +global locale determined by the <> function. + +RETURNS +Upon successful completion, the <> 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, +<> shall return (locale_t) <<0>> and set errno to indicate +the error. + + +PORTABILITY +<> is POSIX-1.2008. +*/ + #include #include #include