setlocale(S)

setlocale -- set or read international environment

Syntax

cc . . . -lc

#include  <locale.h>

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

Description

The function setlocale sets all or part of the current program's locale (definitions of language and conventions). Once invoked, setlocale() immediately updates the information used by the routines that support locale-specific capabilities (for example character and string handling routines, collation, and so on).

The setlocale() function accepts two arguments. The category argument describes the category of international information to set. The following categories (defined in <locale.h>) are recognised:

LC_ALL: Set all categories in the international environment.
LC_COLLATE: Set only the category that contains collating information.
LC_CTYPE: Set only the category that contains character classification and case conversion information.
LC_NUMERIC: Set only the category that contains numeric formatting information.
LC_MESSAGES: Set only the category that contains message language information.
LC_MONETARY: Set only the category that contains currency formatting information.
LC_TIME: Set only the category that contains date and time formatting information.

The locale argument should be a character string that corresponds to the name of a particular international environment. There are three special locale strings, as follows:

"C" Defines the minimal environment needed for the C programming language.

"" (Null string) Specifies that the locale is set to be the implementation-defined native environment which may be affected by the /etc/defaults/lang file, the LANG environment variable, or any of the LC_ environment variables. (See environ(M)).

(char *) 0 (Null pointer) Used to query the current locale for a specific category.

Other strings use the same format as the user environment variables (see environ(M)).

setlocale() may be used to query the current locale. This is done by calling setlocale() with a null pointer (that is, (char *)0) as the locale argument. setlocale() returns the current locale associated with this category and the program's locale is not changed.

If setlocale() is unable to successfully set the locale for any category, the active locale is unchanged. If the failing call was for the category LC_ALL, all subcategories which could be set are changed; only those which could not be set remain as before.

Return value

If successful, setlocale() returns the locale name string associated with the locale just set. On error, setlocale() returns a null pointer.

When a null pointer is given as the locale, setlocale() returns the locale name string of the current locale. If the individual categories differ at all, and the specified category is LC_ALL, then an expanded locale name string is returned containing the information for each category.

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

When a locale is partially defined and does not have a corresponding entry in the file /etc/default/lang, the following error message is displayed:

   libc: setlocale: xxxx: no LANG= line in /etc/default/lang

where xxxx is one of the environment variables found in environ(M). For example, LC_CTYPE.

When a locale is inaccurately defined, the following error message is displayed:

   libc: setlocale: xxxx: cannot open locale file

where xxxx is one of the environment variables found in environ(M). For example, LC_CTYPE.

Notes

The return values from setlocale() are pointers to static data, the content of which is overwritten with each call.

Standards conformance

setlocale() is conformant with:

ANSI X3.159-1989 Programming Language -- C ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .