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.
On OpenBSD,
mask is only meaningful if it 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; otherwise,
newlocale()
always returns the C locale.
On OpenBSD,
newlocale()
ignores oldloc, and passing
(locale_t)0 is recommended.
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”).
HISTORY
These functions have been available since OpenBSD 6.2.