Tribblix: 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