NAME

setlocale - sets locale environment

SYNOPSIS

#include <locale.h>
 char ∗setlocale(category, locale)
int category;
char ∗locale;

DESCRIPTION

Programs supporting multiple languages cannot execute correctly unless the character code and language to use in messages are set at execution time for the proper environment.  This environment is called the locale. 

setlocale sets the locale environment to the category specified by the argument category. 

Category names are defined in <locale.h>, and have the following meanings. 

LC_ALL
Used when simultaneously changing all of the categories listed below.

LC_CTYPE
This category is related to character code sets. This affects macros such as ctype(3) which classify character types.

LC_NUMERIC
This category is related to numeric expressions. For example, whether a "." or a "," should be used for decimal points.

LC_TIME
This category is related to time and date expressions.

LC_COLLATE
This category is related to the standard order to use for character strings.

LC_MONETARY
This category is related to monetary expressions.

LC_MESSAGES
This category is related to messages.

The argument locale represents a character string which must match the name of a file or directory beneath the directory corresponding to the category used as an argument.  For example, this file must be within /usr/lib/locale/LC_CTYPE when executing setlocale(LC_CTYPE, locale).

If the argument locale is specified as "" (the empty string), the value of the environment variable matching the category is used as the locale name.  For example, the call setlocale(LC_CTYPE, "") will return a value equal to the environment variable LC_CTYPE.  If this environment variable does not exist, the value of the environment variable LANG will be used.  If this environment variable does not exist, the value of either LC_CTYPE or LANG written in the file $HOME/.userinfo will be used.  If neither of these exists, the value of either LC_CTYPE or LANG written in the file /etc/sysinfo will be used.  If neither of these exists, "C" will be used as the value of locale. 

setlocale returns a pointer to the character string to which locale has actually been set.  If locale could not be set, the function will return a NULL pointer.  In this case, the locale environment will not be changed. 

If the category used is LC_ALL and locale cannot be set for even one of all the categories, the locale environment will not be changed and the function will return a NULL pointer. 

If locale is specified as 0 (a NULL pointer), setlocale will return a pointer to the locale string currently set for the category specified.  In this case, the locale environment will not be changed. 

By default, locale is set to "C" before any calls have been made to setlocale. 

FILES

/usr/lib/locale/category/locale
/etc/sysinfo
$HOME/.userinfo

SEE ALSO

ctype(3), mblen(3)

NOTES

Under NEWS-OS 4.0, only LC_CTYPE is affected by several library functions such as the macro ctype(3) and mblen(3). As for other categories, there are plans to prepare corresponding functions in the future.

The function set_syscode(3J) available under NEWS-OS 3.x has been modified so that it calls setlocale.  Accordingly, it now looks up the value of the environment variable LC_CTYPE or LANG, not SYS_CODE as it used to.  For example, the call set_syscode(0) is equivalent to setlocale(LC_CTYPE, "") except that set_syscode still returns a value for _sys_code, as defined in <ctype.h>.  The value of _sys_code can be set using setlocale.

NEWS-OSRelease 4.1C