### 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:

- "En_GB" (English, Great Britain, code page 850)
- "Fr_CA" (French, Canada, code page 850)

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

- "En_GB.IBM-850" (English, Great Britain, code page 850 or code page 437)
- "Fr_CA.IBM-850" (French, Canada, code page 850)

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:

- "En_GB.IBM-1252" (English, Great Britain, code page 1252)
- "Fr_CA.IBM-1252" (French, Canada, code page 1252)

The result of setlocale depends on the arguments you specify:

- To set a category to a specific locale, specify both the category and locale names. For example:

  `setlocale(LC_CTYPE, "POSIX");`

  sets the LC_CTYPE category according to the "POSIX" locale. The category names and their purpose are described in the table below.

  If you specify a null string ("") for locale, setlocale checks locale-related environment variables in the program's environment to find a locale name or names to use for category. If category is not LC_ALL, setlocale gets the locale name from:

  1. LC_ALL, if it is defined and not null;
  2. The environment variable with the same name as category, if it is defined and not null;
  3. LANG, if it is defined and not null;
  4. If none of these variables is defined to a valid locale name, setlocale uses the "C" locale.

  If category is LC_ALL and locale is a null string, setlocale checks the environment variables in the same order listed above. However, it checks the variable for each category and sets the category to the locale specified, which could be different for each category. (By contrast, if you specified LC_ALL and a specific locale name, all categories would be set to the same locale that you specify.) The string returned lists all the locales for all the categories.

- To query the locale for a category, specify a null pointer for locale. setlocale then returns a string indicating the locale setting for that category, without changing it. For example:

  `char *s = setlocale(LC_CTYPE, NULL);`

  returns the current locale for the LC_CTYPE category.

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