NAME
newlocale,
duplocale, freelocale
— create and destroy locale
objects
SYNOPSIS
#include
<locale.h>
locale_t
newlocale(int mask,
const char *locname, locale_t
oldloc);
locale_t
duplocale(locale_t oldloc);
void
freelocale(locale_t oldloc);
DESCRIPTION
The function
newlocale()
creates a new locale object for use with
uselocale(3) and with many functions that accept
locale_t arguments. Locale categories not contained in
the mask are copied from oldloc
to the new locale object, or from the "C" locale if
oldloc is (locale_t)0.
On OpenBSD, locname
only affects the return value if mask includes
LC_CTYPE_MASK, and locname is
only meaningful if it is "C" or "POSIX", if it ends with
".UTF-8", or if it is an empty string. Other
locname arguments have the same effect as
"C".
The function
duplocale()
copies oldloc, or the global locale if given the
special argument LC_GLOBAL_LOCALE.
For portability, when an object returned from
newlocale()
or duplocale() is no longer needed, pass it to
freelocale(),
even though the latter has no effect on OpenBSD. The
oldloc objects passed to
newlocale() or freelocale()
become invalid, and using them or passing them once again to
freelocale() results in undefined behaviour, whereas
objects passed to duplocale() remain valid and can
be passed to freelocale() later on.
RETURN VALUES
The functions newlocale() and
duplocale() return the new locale object on success
or (locale_t)0 on failure.
ENVIRONMENT
If locname is an empty string,
newlocale inspects LC_ALL,
LC_CTYPE, and LANG as
described in locale(1).
ERRORS
The function newlocale() fails if:
- [
EINVAL] - An invalid bit is set in mask, or
locname is
NULL. - [
ENOENT] - Locale data is not available for locname.
On other operating systems, newlocale()
and duplocale() may also fail with
ENOMEM.
SEE ALSO
iswalnum(3), iswctype(3), towctrans(3), towlower(3), uselocale(3), wcscasecmp(3), wctrans(3), wctype(3)
STANDARDS
These functions conform to IEEE Std 1003.1-2008 (“POSIX.1”) including Technical Corrigendum 3.
HISTORY
These functions have been available since OpenBSD 6.2.
CAVEATS
Calling newlocale() with an
oldloc argument of
LC_GLOBAL_LOCALE results in undefined behaviour.