./_Man_SunOS_4.1.3_html/html3/setlocale.3v.html

Manual page for SETLOCALE(3V)

setlocale, nl_init - set international environment

SYNOPSIS

#include <locale.h>

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

int nl_init(lang)
char *lang;

DESCRIPTION

setlocale() selects the appropriate piece of the program's locale as specified by category, and may be used to change or query the program's international environment. The entire locale may be changed by calling setlocale() with category set to LC_ALL. The other possible values for category query or change only a part of the program's complete international locale:

LC_CTYPE: Affects the behavior of the character classification and conversion functions. See ctype.3v and mblen.3
LC_COLLATE: Affects the behavior of the string collation functions strcoll (3) and strxfrm.3v
LC_TIME: Affects the behavior of the time conversion functions. See printf.3v scanf.3v strtod.3 and ctime.3v for strftime(), strptime(), and ctime().
LC_NUMERIC: Affects the radix character for the formatted input/output functions and the string conversion functions, gcvt.3v printf.3v strtod.3 gconvert(), sgconvert() (see econvert.3 file_to_decimal(), and func_to_decimal() (see string_to_decimal.3 Also affects the non-monetary formatting information returned by the localeconv() function.
LC_MONETARY: Affects the monetary formatting information returned by the localeconv() function.
LC_MESSAGES: Affects the behavior of functions that present messages, namely gettext(), and textdomain().

The locale argument is a pointer to a character string containing the required setting of category. The following preset values of locale are defined for all settings of category:

"C": Specifies the minimal environment for C translation. If setlocale() is not invoked, the "C" locale is the default. Operational behavior within the "C" locale is defined separately for each interface function.

At program startup, the equivalent of:

"": In this case, setlocale() will first check the value of the corresponding environment variable (for example, LC_CTYPE for the LC_CTYPE category) and if valid (that is, points to the name of a valid locale), setlocale() sets the specified category of the international environment to that value and returns the string corresponding to the locale set (that is, the value of the environment variable, not ""). If the value is invalid, setlocale() returns a NULL pointer and the international environment is not changed by this call.
: If the environment variable corresponding to the specified category is not set or is set to the empty string, setlocale() will examine the LANG environment variable. If both the LANG environment variable, and the environment variable corresponding to the specified category are not set or are set to the empty string, then the LC_default environment variable is examined. If this contains a valid setting, then the category is set to the value of LC_default. If the LANG environment variable is set and valid this will set the category to the corresponding value of LANG. If LC_default is not set, then setlocale() returns that category to the default "C" locale.

To set all categories in the international environment, setlocale() is invoked in the following manner:

setlocale (LC_ALL,  "" );

To satisfy this request, setlocale() first checks all the relevant environment variables LC_CTYPE, LC_COLLATE, LC_TIME, LC_NUMERIC, LC_MONETARY, LC_MESSAGES. If any one of these relevant environment variables is invalid, this call to setlocale() will return a NULL pointer, and the international environment will not be changed. If all the relevant environment variables are valid, setlocale() sets the international environment to reflect the values of the environment variables. The categories are set in the following order:

LC_CTYPE
LC_COLLATE
LC_TIME
LC_NUMERIC
LC_MONETARY
LC_MESSAGES

Using this scheme, the categories corresponding to the environment variables will override the value of the LANG and LC_default environment variables for a particular category.

nl_init() is equivalent to

setlocale(LC_ALL, "");

and is supplied for compatibility with X/Open XPG2.

RETURN VALUES

If a valid string is given for the locale parameter, and the selection can be honored, setlocale() returns the string associated with the specified category for the new locale. If the selection cannot be honored, setlocale() returns a null pointer and the program's locale is not changed.

A NULL pointer for locale causes setlocale() to return the string associated with the category for the program's current locale; the program's locale is not changed. The string contains information relating to each piece part of the whole international environment. This inquiry can fail by returning a null pointer if any category is invalid.

The string returned by such a setlocale() call is such that a subsequent call with the string and its associated category will restore that part of the program's locale. The string returned by:

: ptr = setlocale(LC_ALL, (char *) 0);

is such that in a subsequent call:

: setlocale(LC_ALL, ptr);

will reset each and every category to the state when the string was first returned. The string returned must not be modified by the program, but will be overwritten by a subsequent call to setlocale().

FILES

/etc/locale/locale/category: locale is the directory that contains numerous files (categories), each relating to a single category of a valid locale as selected by category argument to setlocale(). Generally this is classed as a private directory. This directory is searched by setlocale(), prior to searching:
/usr/share/lib/locale/locale/category: locale is the directory that contains numerous files (categories), each relating to a single category of a valid locale as selected by category argument to setlocale(). Generally this data is classed as global and sharable.

DIAGNOSTICS

setlocale() returns a null pointer if a relevant environment variable has an invalid setting. setlocale() also returns a null pointer if category is invalid.