illumos: manual page: newlocale.3c

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

NAME

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

SYNOPSIS

#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);

DESCRIPTION

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.

RETURN VALUES

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.

ERRORS

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