setlocale(3) [freebsd man page]
SETLOCALE(3) BSD Library Functions Manual SETLOCALE(3) NAME
setlocale -- natural language formatting for C LIBRARY
Standard C Library (libc, -lc) SYNOPSIS
#include <locale.h> char * setlocale(int category, const char *locale); 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 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) and multibyte(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, see catopen(3) 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 num- bers 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. RETURN VALUES
Upon successful completion, setlocale() returns the string associated with the specified category for the requested locale. The setlocale() function returns NULL and fails to change the locale if the given combination of category and locale makes no sense. FILES
$PATH_LOCALE/locale/category /usr/share/locale/locale/category locale file for the locale locale and the category category. ERRORS
No errors are defined. SEE ALSO
colldef(1), mklocale(1), catopen(3), ctype(3), localeconv(3), multibyte(3), strcoll(3), strxfrm(3), euc(5), utf8(5), environ(7) STANDARDS
The setlocale() function conforms to ISO/IEC 9899:1999 (``ISO C99''). HISTORY
The setlocale() function first appeared in 4.4BSD. BSD
November 21, 2003 BSD
Check Out this Related Man Page
setlocale(3C) setlocale(3C) NAME
setlocale - modify and query a program's locale SYNOPSIS
#include <locale.h> char *setlocale(int category, const char *locale); The setlocale() function selects the appropriate piece of the program's locale as specified by the category and locale arguments. The cate- gory argument may have the following values: LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, and LC_ALL. These names are defined in the <locale.h> header. The LC_ALL variable names all of a program's locale categories. The LC_CTYPE variable affects the behavior of character handling functions such as isdigit(3C) and tolower(3C), and multibyte character functions such as mbtowc(3C) and wctomb(3C). The LC_NUMERIC variable affects the decimal point character and thousands separator character for the formatted input/output functions and string conversion functions. The LC_TIME variable affects the date and time format as delivered by ascftime(3C) cftime(3C) getdate(3C) strftime(3C) and strptime(3C) The LC_COLLATE variable affects the sort order produced by collating functions such as strcoll(3C) and strxfrm(3C) The LC_MONETARY variable affects the monetary formatted information returned by localeconv(3C). The LC_MESSAGES variable affects the behavior of messaging functions such as dgettext(3C), gettext(3C), and gettxt(3C). A value of "C" for locale specifies the traditional UNIX system behavior. At program startup, the equivalent of setlocale(LC_ALL, "C") is executed. This has the effect of initializing each category to the locale described by the environment "C". A value of "" for locale specifies that the locale should be taken from environment variables. The order in which the environment variables are checked for the various categories is given below: +---------------+----------------+----------------+---------------+ |Category | 1st Env Var |2nd Env Var |3rd Env Var | +---------------+----------------+----------------+---------------+ |LC_CTYPE: | LC_ALL |LC_CTYPE |LANG | +---------------+----------------+----------------+---------------+ |LC_COLLATE: | LC_ALL |LC_COLLATE |LANG | +---------------+----------------+----------------+---------------+ |LC_TIME: | LC_ALL |LC_TIME |LANG | +---------------+----------------+----------------+---------------+ |LC_NUMERIC: | LC_ALL |LC_NUMERIC |LANG | +---------------+----------------+----------------+---------------+ |LC_MONETARY: | LC_ALL |LC_MONETARY |LANG | +---------------+----------------+----------------+---------------+ |LC_MESSAGES: | LC_ALL |LC_MESSAGES |LANG | +---------------+----------------+----------------+---------------+ If a pointer to a string is given for locale, setlocale() attempts to set the locale for the given category to locale. If setlocale() suc- ceeds, locale is returned. If setlocale() fails, a null pointer is returned and the program's locale is not changed. For category LC_ALL, the behavior is slightly different. If a pointer to a string is given for locale and LC_ALL is given for category, setlocale() attempts to set the locale for all the categories to locale. The locale may be a simple locale, consisting of a single locale, or a composite locale. If the locales for all the categories are the same after all the attempted locale changes, setlocale() will return a pointer to the common simple locale. If there is a mixture of locales among the categories, setlocale() will return a composite locale. Upon successful completion, setlocale() returns the string associated with the specified category for the new locale. Otherwise, setlo- cale() returns a null pointer and the program's locale is not changed. A null pointer for locale causes setlocale() to return a pointer to the string associated with the category for the program's current locale. The program's locale is not changed. The string returned by setlocale() is such that a subsequent call with that string and its associated category will restore that part of the program's locale. The string returned must not be modified by the program, but may be overwritten by a subsequent call to setlocale(). No errors are defined. /usr/lib/locale/locale locale database directory for locale See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |CSI |Enabled | +-----------------------------+-----------------------------+ |Interface Stability |Standard | +-----------------------------+-----------------------------+ |MT-Level |MT-Safe with exceptions | +-----------------------------+-----------------------------+ locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C), isdigit(3C), localeconv(3C), mbtowc(3C), strcoll(3C), strftime(3C), strptime(3C) strxfrm(3C) tolower(3C), wctomb(3C), libc(3LIB), attributes(5), environ(5), locale(5), standards(5) It is unsafe for any thread to change locale (by calling setlocale() with a non-null locale argument) in a multithreaded application while any other thread in the application is using any locale-sensitive routine. To change locale in a multithreaded application, setlocale() should be called prior to using any locale-sensitive routine. Using setlocale() to query the current locale is safe and can be used any- where in a multithreaded application except when some other thread is changing locale. It is the user's responsibility to ensure that mixed locale categories are compatible. For example, setting LC_CTYPE=C and LC_TIME=ja (where ja indicates Japanese) will not work, because Japanese time cannot be represented in the "C" locale's ASCII codeset. 19 Sep 2005 setlocale(3C)