Skip to content
Tutorials Center
My learning

Topics

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.

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

C Querying and switching locales

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.

C Categories and the thousands flag

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

C
#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 of main for 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") writes 1,5 and strtod("1.5") stops at the dot. Data files and network protocols must stay locale-independent: set LC_NUMERIC back to "C" for them, or use the C locale 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 return NULL, so test the result and fall back; locales must be installed on the machine (locale -a lists them on Linux).
  • LC_CTYPE and UTF-8. To make mbstowcs, wprintf and towupper work with non-ASCII text, switch to a UTF-8 locale. In the "C" locale they only handle ASCII. See wchar.h.
  • LC_ALL versus the others. LC_ALL sets every category together. Querying LC_ALL returns 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 POSIX printf has %'d grouping. Neither is standard C.
  • Cost. A switch is expensive (it may load locale data); do it once. Locale-dependent functions such as isalpha are fast again afterwards.
  • Standard version: C89. Nothing important changed in C23.