SETLOCALE(3)

SETLOCALE(3) | Library Functions Manual | SETLOCALE(3)

# NAME

`setlocale`, `localeconv` —
natural language formatting for C

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <locale.h>`

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

struct lconv *
`localeconv`(void);

# DESCRIPTION

The `setlocale`() function sets the C library's notion of natural language formatting style for particular sets of routines. Each such style is called a ‘locale’ and is invoked using an appropriate name passed as a C string. The `localeconv`() routine returns the current locale's parameters for formatting numbers.

The `setlocale`() function recognizes several categories of routines. These are the categories and the sets of routines they select:

`LC_ALL`
  Set the entire locale generically.
`LC_COLLATE`
  Set a locale for string collation routines. This controls alphabetic ordering in `strcoll`() and `strxfrm`().
`LC_CTYPE`
  Set a locale for the ctype(3) functions. This controls recognition of upper and lower case, alphabetic or non-alphabetic characters, and so on.
`LC_MESSAGES`
  Set a locale for message catalogs. This controls the selection of message catalogs by the catgets(3) and gettext(3) families of functions.
`LC_MONETARY`
  Set a locale for formatting monetary values; this affects the `localeconv`() function.
`LC_NUMERIC`
  Set a locale for formatting numbers. This controls the formatting of decimal points in input and output of floating point numbers in functions such as `printf`() and `scanf`(), as well as values returned by `localeconv`().
`LC_TIME`
  Set a locale for formatting dates and times using the `strftime`() function.

Only three locales are defined by default, the empty string `""` which denotes the native environment, and the `"C"` and `"POSIX"` locales, which denote the C language environment. A locale argument of `NULL` causes `setlocale`() to return the current locale. By default, C programs start in the `"C"` locale. The format of the locale string is described in nls(7).

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.

Changing the setting of `LC_MESSAGES` has no effect on catalogs that have already been opened by catopen(3).

The `localeconv`() function returns a pointer to a structure which provides parameters for formatting numbers, especially currency values:

    struct lconv {
    	char	*decimal_point;
    	char	*thousands_sep;
    	char	*grouping;
    	char	*int_curr_symbol;
    	char	*currency_symbol;
    	char	*mon_decimal_point;
    	char	*mon_thousands_sep;
    	char	*mon_grouping;
    	char	*positive_sign;
    	char	*negative_sign;
    	char	int_frac_digits;
    	char	frac_digits;
    	char	p_cs_precedes;
    	char	p_sep_by_space;
    	char	n_cs_precedes;
    	char	n_sep_by_space;
    	char	p_sign_posn;
    	char	n_sign_posn;
    	char	int_p_cs_precedes;
    	char	int_n_cs_precedes;
    	char	int_p_sep_by_space;
    	char	int_n_sep_by_space;
    	char	int_p_sign_posn;
    	char	int_n_sign_posn;
    };

The individual fields have the following meanings:

decimal_point
  The decimal point character, except for monetary values.
thousands_sep
  The separator between groups of digits before the decimal point, except for monetary values.
grouping
  The sizes of the groups of digits, except for monetary 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 (ISO 4217:1995) international currency symbol.
currency_symbol
  The local currency symbol.
mon_decimal_point
  The decimal point character for monetary values.
mon_thousands_sep
  The separator for digit groups in monetary values.
mon_grouping
  Like grouping but for monetary values.
positive_sign
  The character used to denote nonnegative monetary values, usually the empty string.
negative_sign
  The character used to denote negative monetary values, usually a minus sign.
int_frac_digits
  The number of digits after the decimal point in an internationally formatted monetary value.
frac_digits
  The number of digits after the decimal point in an locally formatted monetary value.
p_cs_precedes
  1 if the currency symbol precedes the monetary value for nonnegative values, 0 if it follows.
p_sep_by_space
  1 if a space is inserted between the currency symbol and the monetary value for nonnegative 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 nonnegative quantity and the currency_symbol.
n_sign_posn
  Like p_sign_posn but for negative currency values.
int_p_cs_precedes
  1 if the currency symbol precedes the internationally formatted monetary value for nonnegative values, 0 if it follows.
int_n_cs_precedes
  Like int_p_cs_precedes but for negative values.
int_p_sep_by_space
  1 if a space is inserted between the currency symbol and the internationally formatted monetary value for nonnegative values, 0 otherwise.
int_n_sep_by_space
  Like int_p_sep_by_space but for negative values.
int_p_sign_posn
  The location of the positive_sign with respect to a nonnegative quantity and the currency_symbol, for internationally formatted nonnegative monetary values.
int_n_sign_posn
  Like int_p_sign_posn but for negative values.

The positional parameters in p_sign_posn, n_sign_posn, int_p_sign_posn and int_n_sign_posn are encoded as follows:

`0`
  Parentheses around the entire string.
`1`
  Before the string.
`2`
  After the string.
`3`
  Just before currency_symbol.
`4`
  Just after currency_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.

# RETURN VALUES

The `setlocale`() function returns `NULL` and fails to change the locale if the given combination of category and locale makes no sense. The `localeconv`() function returns a pointer to a static object which may be altered by later calls to `setlocale`() or `localeconv`().

Currently, `setlocale`() returns `NULL` and fails to change the locale when `LC_COLLATE` is modified independently of other values.

# EXAMPLES

The following code illustrates how a program can initialize the international environment for one language, while selectively modifying the program's locale such that regular expressions and string operations can be applied to text recorded in a different language:

    	setlocale(LC_ALL, "de");
    	setlocale(LC_NUMERIC, "C");

When a process is started, its current locale is set to the C or POSIX locale. An internationalized program that depends on locale data not defined in the C or POSIX locale must invoke the setlocale subroutine in the following manner before using any of the locale-specific information:

    	setlocale(LC_ALL, "");

# FILES

The use of multibyte locales requires shared libraries located in /usr/lib/i18n.

# SEE ALSO

catopen(3), gettext(3), nl_langinfo(3), nls(7)

# STANDARDS

The `setlocale`() and `localeconv`() functions conform to ANSI X3.159-1989 (“ANSI C89”) and ISO/IEC 9899:1990 (“ISO C90”).

The int_p_cs_precedes, int_n_cs_precedes, int_p_sep_by_space, int_n_sep_by_space, int_p_sign_posn and int_n_sign_posn members of struct lconv were introduced in ISO/IEC 9899:1999 (“ISO C99”).

# HISTORY

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

# BUGS

In spite of the gnarly currency support in `localeconv`(), the standards don't include any functions for generalized currency formatting.

`LC_COLLATE` is unimplemented (but does not make sense for many languages). Use of `LC_MONETARY` could lead to misleading results until we have a real time currency conversion function. `LC_NUMERIC` and `LC_TIME` are personal choices and should not be wrapped up with the other categories.

Multibyte locales aren't supported for static binaries.

December 31, 2022 | NetBSD 10.0