SETLOCALE(3)

NAME
setlocale - select character encoding

SYNOPSIS
#include <locale.h>
char *
setlocale(int category, const char *locale);

DESCRIPTION
The setlocale() function sets and retrieves the active locale for the current process. The locale modifies the behaviour of some functions in the C library with respect to the character encoding and some language and cultural conventions. For more information about locales in general, see the locale(1) manual page.

The possible values for category are LC_CTYPE, to set character encoding, character classification, and case conversion; LC_COLLATE, sets ordering rules; LC_MESSAGES sets language prefered; LC_MONETARY, sets conventions for monetary quantities; LC_NUMERIC, sets conventions for numeric quantities and LC_TIME sets conventions for date and time. A category of LC_ALL sets the entire locale generically, which is strongly discouraged for security reasons in portable programs.

In OpenBSD, if the locale string ends with ".UTF-8", the UTF-8 locale is selected; otherwise, the "C" locale is selected, which uses the ASCII character set. If the locale contains a dot but does not end with ".UTF-8", setlocale() fails.

If locale is an empty string (""), the value of the environment variable LC_ALL, with a fallback to the variable corresponding to category, and with a further fallback to LANG, is used instead, as documented in the locale(1) manual page.

If locale is NULL, the locale remains unchanged. This can be used to determine the currently active locale.

By default, C programs start in the "C" locale. The only function in the library that sets the locale is setlocale(); the locale is never changed as a side effect of some other routine.

For example the LC_CTYPE category modifies the behaviour of at least the following functions: iswctype(3), mblen(3), mbrlen(3), mbrtowc(3), mbsrtowcs(3), mbstowcs(3), mbtowc(3), towctrans(3), towlower(3), towupper(3), wcrtomb(3), wcscasecmp(3), wcsrtombs(3), wcstombs(3), wctomb(3), wctrans(3), wctype(3), and the functions documented in iswalnum(3).

RETURN VALUES
In case of success, setlocale() returns a pointer to a static string describing the locale that is in force after the call. Subsequent calls to setlocale() may change the content of the string. The format of the string is not standardized and varies among operating systems.

On OpenBSD, if setlocale() was never called with a non-NULL locale argument, the string "C" is returned. Otherwise, if the category was not LC_ALL or if the locale is the same for all categories, a copy of the locale argument is returned. Otherwise, the locales for the six categories LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME are concatenated in that order, with slash (‘/’) characters in between.

In case of failure, setlocale() returns NULL. On OpenBSD, that can only happen if the category is invalid, if a character encoding other than UTF-8 is requested, if the requested locale name is of excessive length, or if memory allocation fails.

EXAMPLES
Calling

    setlocale(LC_CTYPE, "en_US.UTF-8");

at the beginning of a program selects the UTF-8 locale and returns "en_US.UTF-8". Calling

    setlocale(LC_ALL, NULL);

right afterwards leaves the locale unchanged and returns "C/en_US.UTF-8/C/C/C/C".

SEE ALSO
locale(1), localeconv(3), newlocale(3), nl_langinfo(3), uselocale(3)

STANDARDS
The setlocale() function conforms to ansiC.

HISTORY
The setlocale() function first appeared in 4.4BSD.