This file and its contents are supplied under the terms of the
Common Development and Distribution License ("CDDL"), version 1.0.
You may only use this file in accordance with the terms of version
1.0 of the CDDL.
A full copy of the text of the CDDL should have accompanied this
source. A copy of the CDDL is also available via the Internet at
http://www.illumos.org/license/CDDL.
Copyright (c) 2014 Joyent, Inc. All rights reserved.
Copyright 2014 Garrett D'Amore <garrett@damore.org>
#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):
LC_CTYPE_MASK Character classification and case conversion.
LC_NUMERIC_MASK Numeric formatting.
LC_TIME_MASK Date and time formatting.
LC_COLLATE_MASK Collation order.
LC_MONETARY_MASK Monetary formatting.
LC_MESSAGES_MASK Formats of informative and diagnostic messages and interactive responses.
LC_ALL_MASK 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:
ENOMEM Insufficient memory was available to create the locale object or to load the requested locale data.
The newlocale() function will fail if:
EINVAL An unknown bit is specified in category_mask .
ENOENT Locale data was not found for a category specified in
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Standard |
| MT-Level Safe |