The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group


setlocale - set program locale


#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, 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:
Affects the behaviour of regular expressions and the collation functions.
Affects the behaviour of regular expressions, character classification, character conversion functions and wide-character functions.
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.
Affects the behaviour of functions that handle monetary values.
Affects the radix character for the formatted input/output functions and the string conversion functions.
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:

Specifies the minimal environment for C-language translation called POSIX locale. If setlocale() is not invoked, the POSIX locale is the default.
Same as POSIX.
Specifies an implementation-dependent native environment. For XSI-conformant systems, this corresponds to the value of the associated environment variables, LC_* and LANG; see the XBD specification, Locale  and the XBD specification, Environment Variables .
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.


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().


No errors are defined.




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().




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>.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]