locale_t newlocale(int category_mask,
                   const char *locale,
                   locale_t base);

newlocale creates a new locale object or modifies an existing one. If the base argument is NULL, a new locale object is created.

category_mask specifies the locale categories to be set or modified. Values for category_mask are 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.

For each category with the corresponding bit set in category_mask, the data from the locale named by locale is used. In the case of modifying an existing locale object, the data from the locale named by locale replaces 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 are taken from the default locale.

The locales ‘C’ and ‘POSIX’ are equivalent and defined for all settings of category_mask:

If locale is NULL, then the ‘C’ locale is used. If locale is an empty string, newlocale will use the default locale.

If base is NULL, the current locale is used. If base is LC_GLOBAL_LOCALE, the global locale is used.

If mask is LC_ALL_MASK, base is ignored.


POSIX.1-2008 does not specify whether the locale object pointed to by base is modified or whether it is freed and a new locale object created.


The category mask LC_MESSAGES_MASK is not implemented as POSIX messages are not implemented.