setlocale -- Set Locale

Format

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

Language Level: ANSI, POSIX, XPG4
setlocale sets or queries the specified category of the program's locale. A locale is the complete definition of that part of a program that depends on language and cultural conventions.

The default locale is the POSIX C locale definition, represented as "C" or "POSIX". This locale is standard for all ANSI-conforming and POSIX-conforming compilers. You can accept the default, or you can use setlocale to set the locale to one of the supplied locales.

If you want the locale that is bound to the OEM code page, you should specify only the language and country or territory, as shown in the following example:

You may also use the fully qualified name as shown in the following example:

Windows supports two classes of code pages: ANSI and OEM. If you want the locale that is bound to the ANSI code page, you should specify the fully qualified name that identifies the code page by name as shown in the following example:

The result of setlocale depends on the arguments you specify:

You can set the category argument of setlocale to one of the following values:

Locale Categories for setlocale

Category Purpose
LC_ALL
Specifies all categories associated with the program's locale.
LC_COLLATE
Defines the collation sequence, that is, the relative order of collation elements (characters and multicharacter collation elements) in the program's locale. The collation sequence definition is used by regular expression, pattern matching, and sorting functions. Affects the regular expression functions regcomp and regexec; the string functions strcoll, strxfrm, wcscoll, and wcsxfrm.

Note: Because both LC_CTYPE and LC_COLLATE modify the same storage area, setting LC_CTYPE and LC_COLLATE to different categories causes unpredictable results.

LC_CTYPE
Defines character classification and case conversion for characters in the program's locale. Affects the behavior of character-handling functions defined in the <ctype.h> header file: csid, isalnum, isalpha, isblank, iswblank iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, iswalnum, iswalpha, iswcntrl, iswctype, iswdigit, iswgraph, iswlower, iswprint, iswpunct, iswspace, iswupper, iswxdigit, isxdigit, tolower, toupper, towlower, towupper, wcsid, and wctype.

Affects behavior of the printf and scanf families of functions: fprintf, printf, sprintf, vfprintf, vprintf, vsprintf, fscanf, scanf, and sscanf.

Affects the behavior of wide character input/output functions: fgetwc, fgetws, getwc, getwchar, fputwc, fputws, putwc, putwchar, and ungetwc.

Affects the behavior of multibyte and wide character conversion functions: mblen, mbrlen, mbrtowc, mbsrtowcs, mbstowcs, mbtowc, wcrtomb, wcsrtombs, wcstombs, wcswidth, wctomb, wcwidth, wcstod, wcstol, and wcstoul.

Note: Because both LC_CTYPE and LC_COLLATE modify the same storage area, setting LC_CTYPE and LC_COLLATE to different categories causes unpredictable results.

LC_MESSAGES
Affects the values returned by nl_langinfo, and also defines affirmative and negative response patterns, which affect rpmatch.

May affect the search path for message catalogs.

LC_MESSAGES does not affect the messages for the following functions: perror, strerror, and on OS/2 and Windows only, _strerror, and regerror.

LC_MONETARY
Affects monetary information returned by localeconv and strfmon. It defines the rules and symbols used to format monetary numeric information in the program's locale. The formatting rules and symbols are strings. localeconv returns pointers to these strings with names found in the <locale.h> header file.
LC_NUMERIC
Affects the decimal-point character for the formatted input/output and string conversion functions, the thousands separator character and the thousands grouping, and the nonmonetary formatting information returned by the localeconv function, specifically, printf family of functions.
LC_TIME
Defines time and date format information in the program's locale, affecting the strftime strptime functions, and on OS/2 and Windows only, the wcsftime function.
LC_SYNTAX
On OS/2 and Windows, affects the values that can be retrieved by the getsyntx function.

It does not affect the behavior of functions that are dependent on the encoded values for formatting characters, as it may do on other platforms.

LC_TOD
Affects the behavior of the functions related to time zone and Daylight Savings Time information in the program's locale. ctime, localtime, mktime, setlocale, and strftime call the tzset function to override the LC_TOD category information when TZ is defined and valid.

Return Value
setlocale returns a string that specifies the locale for the category. If you specified "" for locale, the string names the current locale; otherwise, it indicates the new locale that the category was set to.

If you specified LC_ALL for category, the returned string can be either a single locale name or, if the individual categories have different locales, a list of the locale names for each category in the following order:

  1. LC_COLLATE
  2. LC_CTYPE
  3. LC_MONETARY
  4. LC_NUMERIC
  5. LC_TIME
  6. LC_TOD
  7. LC_MESSAGES
  8. LC_SYNTAX

The string can be used on a subsequent call to restore that part of the program's locale. Because the returned string can be overwritten by subsequent calls to setlocale, you should copy the string if you plan to use it later.

If an error occurs, setlocale returns NULL and does not alter the program's locale. Errors can occur if the category or locale is not valid, or if the value of the environment variable for a category does not contain a valid locale.

Examples



Locales and Localization


catopen -- Open Message Catalog
getenv -- Search for Environment Variables
localeconv -- Retrieve Numeric Formatting Convention
nl_langinfo -- Retrieve Locale Information
<locale.h>
Locales supported on OS/2
Locales supported on Windows
LOCPATH Environment Variable