NAME

setlocale - set program locale

SYNOPSIS

#include <locale.h>

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

DESCRIPTION

The setlocale() function selects the appropriate piece of the program's locale, as specified by the category and locale arguments, and may be used to change or query the program's entire locale or portions thereof. The value LC_ALL for category names the program's entire locale; other values for category name only a part of the program's locale:

LC_COLLATE

Affects the behaviour of regular expressions and the collation functions.

LC_CTYPE

Affects the behaviour of regular expressions, character classification, character conversion functions and wide-character functions.

LC_MESSAGES

Affects what strings are expected by commands and utilities as affirmative or negative responses, what strings are given by commands and utilities as affirmative or negative responses, and the content of messages.

LC_MONETARY

Affects the behaviour of functions that handle monetary values.

LC_NUMERIC

Affects the radix character for the formatted input/output functions and the string conversion functions.

LC_TIME

Affects the behaviour of the time conversion functions.

The locale argument is a pointer to a character string containing the required setting of category. The contents of this string are implementation-dependent. In addition, the following preset values of locale are defined for all settings of category:

"POSIX"

Specifies the minimal environment for C-language translation called POSIX locale. If setlocale() is not invoked, the POSIX locale is the default.

"C"

Same as POSIX.

""

Specifies an implementation-dependent native environment. For POSIX-conformant systems, this corresponds to the value of the associated environment variables, LC_* and LANG; see the Locale specification and the Environment Variables specification.

A null pointer

Used to direct setlocale() to query the current internationalised environment and return the name of the locale().

The locale state is common to all threads within a process.

RETURN VALUE

Upon successful completion, setlocale() returns the string associated with the specified category for the new locale. Otherwise, setlocale() 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().

ERRORS

No errors are defined.

EXAMPLES

None.

APPLICATION USAGE

The following code illustrates how a program can initialise the international environment for one language, while selectively modifying the program's locale such that regular expressions and string operations can be applied to text recorded in a different language:

setlocale(LC_ALL, "De");
setlocale(LC_COLLATE, "Fr@dict");

Internationalised programs must call setlocale() to initiate a specific language operation. This can be done by calling setlocale() as follows:

setlocale(LC_ALL, "");

Changing the setting of LC_MESSAGES has no effect on catalogues that have already been opened by calls to catopen().

FUTURE DIRECTIONS

None.

SEE ALSO

exec, isalnum(), isalpha(), iscntrl(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), iswalnum(), iswalpha(), iswcntrl(), iswgraph(), iswlower(), iswprint(), iswpunct(), iswspace(), iswupper(), localeconv(), mblen(), mbstowcs(), mbtowc(), nl_langinfo(), printf(), scanf(), setlocale(), strcoll(), strerror(), strfmon(), strtod(), strxfrm(), tolower(), toupper(), towlower(), towupper(), wcscoll(), wcstod(), wcstombs(), wcsxfrm(), wctomb(), <langinfo.h>, <locale.h>.