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:
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:
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.
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:
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.
![]()
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