SETLOCALE(3) AerieBSD 1.0 Refernce Manual SETLOCALE(3)

NAME

setlocale — localeconv natural language formatting for C

SYNOPSIS

#include <locale.h>

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

structlconv * 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. The real work is done by the setrunelocale(); function.
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 only function in the library that sets the locale is setlocale();; the locale is never changed as a side effect of some other routine.

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;
};

The individual fields have the following meanings:
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.
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:

0
Parentheses around the entire string.
1
Before the string.
2
After the string.
3
Just before currency_symbol.
4
Just after currency_symbol.
n_sign_posn
Like p_sign_posn but for negative currency values.

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();.

SEE ALSO

mklocale(1), strcoll(3), strxfrm(3)

STANDARDS

The setlocale(); and localeconv(); functions conform to

HISTORY

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

BUGS

The current implementation supports only the "\&""C"" and "\&""POSIX"" locales for all but the LC_CTYPE locale.

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

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

AerieBSD 1.0 Reference Manual August 26 2008 SETLOCALE(3)