OpenBSD manual page server

Manual Page Search Parameters
SETLOCALE(3) Library Functions Manual SETLOCALE(3)

setlocale, localeconv — select character encoding

#include <locale.h>

char *
setlocale(int category, const char *locale);

struct lconv *
localeconv(void);

The () 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 on other operating systems also with respect to some language and cultural conventions. For more information about locales in general, see the locale(1) manual page.

On OpenBSD, the only useful value for the category is LC_CTYPE. It sets the locale used for character encoding, character classification, and case conversion. For compatibility with natural language support in packages(7), all other categories — LC_COLLATE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME — can be set and retrieved, too, but their values are ignored by the OpenBSD C library. A category of LC_ALL sets the entire locale generically.

The syntax and semantics of the locale argument are not standardized and vary among operating systems. On 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", () 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 (); the locale is never changed as a side effect of some other routine.

The () function returns a pointer to a static structure which provides parameters for formatting numbers. On OpenBSD, nothing in the returned structure ever changes.

It provides the following fields of type char *:

decimal_point
The decimal point character, except for currency values.
thousands_sep
The separator between groups of digits before the decimal point, except for currency values.
grouping
The sizes of the groups of digits, except for currency values. This is a pointer to a vector of integers, each of size char, representing group size from low order digit groups to high order (right to left). The list may be terminated with 0 or CHAR_MAX. If the list is terminated with 0, the last group size before the 0 is repeated to account for all the digits. If the list is terminated with CHAR_MAX, no more grouping is performed.
int_curr_symbol
The standardized international currency symbol.
currency_symbol
The local currency symbol.
mon_decimal_point
The decimal point character for currency values.
mon_thousands_sep
The separator for digit groups in currency values.
mon_grouping
Like grouping but for currency values.
positive_sign
The character used to denote non-negative currency values, usually the empty string.
negative_sign
The character used to denote negative currency values, usually a minus sign.

It also provides the following fields of type char:

int_frac_digits
The number of digits after the decimal point in an international-style currency value.
frac_digits
The number of digits after the decimal point in the local style for currency values.
p_cs_precedes
1 if the currency symbol precedes the currency value for non-negative values, 0 if it follows.
p_sep_by_space
1 if a space is inserted between the currency symbol and the currency value for non-negative values, 0 otherwise.
n_cs_precedes
Like p_cs_precedes but for negative values.
n_sep_by_space
Like p_sep_by_space but for negative values.
p_sign_posn
The location of the positive_sign with respect to a non-negative quantity and the currency_symbol, coded as follows:

Parentheses around the entire string.
Before the string.
After the string.
Just before currency_symbol.
Just after currency_symbol.
n_sign_posn
Like p_sign_posn but for negative currency values.
int_p_cs_precedes
Like p_cs_precedes but for the international symbol.
int_n_cs_precedes
Like n_cs_precedes but for the international symbol.
int_p_sep_by_space
Like p_sep_by_space but for the international symbol.
int_n_sep_by_space
Like n_sep_by_space but for the international symbol.
int_p_sign_posn
Like p_sign_posn but for the international symbol.
int_n_sign_posn
Like n_sign_posn but for the international symbol.

Unless mentioned above, an empty string as a value for a field indicates a zero length result or a value that is not in the current locale. A CHAR_MAX result similarly denotes an unavailable value.

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.

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

The setlocale() and localeconv() functions conform to ANSI X3.159-1989 (“ANSI C89”).

The setlocale() and localeconv() functions first appeared in 4.4BSD.

March 22, 2018 OpenBSD-6.3