NEWLOCALE(3) | Library Functions Manual | NEWLOCALE(3)

# 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.

June 25, 2019 | Debian