C Reference ยท ctype.h, math.h and others
C locale.h: setlocale() and localeconv()
Reference for locale.h: how setlocale() changes number formats, character classes and text encoding, what localeconv() reports, and the pitfalls of switching locales.
A locale is a set of cultural conventions: the decimal separator (1.5 or 1,5), digit grouping, currency symbols, the sort order of text, which characters count as letters, and the character encoding. <locale.h> lets a program choose its locale with setlocale() and read the number and money conventions with localeconv().
Every C program starts in the minimal "C" locale, which behaves the same everywhere: a dot as decimal point, ASCII character classes, byte-wise comparison. Locale-dependent library functions, such as printf for floating-point numbers, strtod, isalpha, strcoll, strftime and the wide-character conversions, only change behavior when you call setlocale.
#include <locale.h> setlocale(LC_ALL, ""); /* use the user's environment settings */ const char *name = setlocale(LC_ALL, NULL); /* query the current locale */
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
#include <locale.h> char *setlocale(int category, const char *locale); struct lconv *localeconv(void);
| Name | Description |
|---|---|
category |
LC_ALL, LC_COLLATE (string comparison), LC_CTYPE (character classes and conversion), LC_MONETARY, LC_NUMERIC (decimal point), LC_TIME (strftime). |
locale |
A locale name such as "en_US.UTF-8"; "C" or "POSIX" for the minimal locale; "" for the environment's default; NULL to query only. |
Returns: setlocale returns a pointer to a string naming the locale now in effect for the category (valid until the next call), or NULL if the request could not be satisfied, in which case nothing changes. localeconv returns a pointer to a struct lconv.
struct lconv includes decimal_point, thousands_sep, grouping, currency_symbol, int_curr_symbol, mon_decimal_point, positive_sign, negative_sign, frac_digits and more. Members that do not apply are "" (strings) or CHAR_MAX (numbers, 127 here).
Errors / undefined behavior: modifying the returned lconv or the string from setlocale is undefined. The pointers are invalidated by the next setlocale call, so copy them if you need them longer. Calling setlocale while other threads use locale-dependent functions is undefined.
Usage notes
- Initialize once, early. The standard idiom is
setlocale(LC_ALL, "")at the top ofmainfor programs that show output to users. Without it you stay in the"C"locale, even if the user's environment says otherwise. - The decimal point bites in parsing and file formats. After
setlocale(LC_NUMERIC, "de_DE.UTF-8"),printf("%f")writes1,5andstrtod("1.5")stops at the dot. Data files and network protocols must stay locale-independent: setLC_NUMERICback to"C"for them, or use theClocale for that part of the program. - Locale names are platform-specific.
"en_US.UTF-8"is typical on Linux,"English_United States.1252"on Windows. Missing locales returnNULL, so test the result and fall back; locales must be installed on the machine (locale -alists them on Linux). LC_CTYPEand UTF-8. To makembstowcs,wprintfandtowupperwork with non-ASCII text, switch to a UTF-8 locale. In the"C"locale they only handle ASCII. See wchar.h.LC_ALLversus the others.LC_ALLsets every category together. QueryingLC_ALLreturns a single name when all categories agree, otherwise a longer composite string.- Not thread-safe. The locale is global state in standard C. POSIX has per-thread locales (
uselocale,newlocale,freelocale), and POSIXprintfhas%'dgrouping. Neither is standard C. - Cost. A switch is expensive (it may load locale data); do it once. Locale-dependent functions such as
isalphaare fast again afterwards. - Standard version: C89. Nothing important changed in C23.