NEWLOCALE(3C) Standard C Library Functions NEWLOCALE(3C)

duplocale, freelocale, newlocale - create, duplicate, and destroy locale objects

#include <locale.h>
locale_t newlocale(int category_mask, const char *locale,


    locale_t base);

locale_t duplocale(locale_t loc);

void freelocale(locale_t loc);

These functions manipulate locale objects that can be used uselocale(3C) and functions that take arguments of type locale_t.

The function newlocale() can be used to create a new locale object. It can also be used to modify an existing locale object, the new locale object will be a replacement for the modified locale object. To create a new locale, the argument base should be passed the special argument (locale_t)0. This will use a copy of the current global locale as a starting point. To modify an existing locale object, it should be passed in as the argument base. The new locale object is constructed by taking the categories specified in category_mask from the locale specified by the string locale, and filling in the remaining categories from the locale base. When newlocale() returns, callers must no longer use base and assume that freelocale(3C) has been called on it. In addition to locales defined on the system, the following three locales may always be passed in as the string locale:

"C"
Specifies the traditional UNIX system behavior.
"POSIX"
An alternate name for the locale "C".
""
Indicates that the locale should be processed based in the values in the environment. See setlocale(3C) and environ(7) for more information.

The value of category_mask is a bitwise-inclusive or of the following macros which correspond to categories as defined in locale(7) and environ(7):

Character classification and case conversion.
Numeric formatting.
Date and time formatting.
Collation order.
Monetary formatting.
Formats of informative and diagnostic messages and interactive responses.
Mask of all categories.

The function duplocale() duplicates the locale object specified by loc. If the locale object passed is LC_GLOBAL_LOCALE, duplocale() creates a copy of the current global locale as defined through calls to setlocale(3C).

The function freelocale() removes and releases all resources associated with the locale object loc. Programs must not call freelocale() on LC_GLOBAL_LOCALE.

On success, the functions newlocale() and duplocale() return a new locale object that can be used with functions that take a locale_t. Locale objects created this way should be freed with freelocale(). On error, the functions newlocale() and duplocale() return (locale_t)0 and errno is set to indicate the error. The freelocale() function does not set errno.

The newlocale() and duplocale() functions will fail if:

Insufficient memory was available to create the locale object or to load the requested locale data.

The newlocale() function will fail if:

An unknown bit is specified in category_mask.
Locale data was not found for a category specified in

ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Standard
MT-Level Safe

locale(1), setlocale(3C), uselocale(3C), environ(7), locale(7)

November 26, 2017 OmniOS