12 <locale.h> locale handling

The “locale” is the details of how the program should run given its physical location on the planet.

For example, in one locale, a unit of money might be printed as $123, and in another €123.

Or one locale might use ASCII encoding and another UTF-8 encoding.

By default, the program runs in the “C” locale. It has a basic set of characters with a single-byte encoding. If you try to print UTF-8 characters in the C locale, nothing will print. You have to switch to a proper locale.

12.1 setlocale()

Set the locale

Synopsis

#include <locale.h>

char *setlocale(int category, const char *locale);

Description

Sets the locale for the given category.

Category is one of the following:

And there are three portable things you can pass in for locale; any other string passed in is implementation-defined and non-portable.

The most common call, I’d wager, is this:

// Set all locale settings to the local, native locale

setlocale(LC_ALL, "");

Handily, setlocale() returns the locale that was just set, so you could see what the actual locale is on your system.

Return Value

On success, returns a pointer to the string representing the current locale. You may not modify this string, and it might be changed by subsequent calls to setlocale().

On failure, returns NULL.

Example

Here we get the current locale. Then we set it to the native locale, and print out what that is.

#include <stdio.h>
#include <locale.h>

int main(void)
{
    char *loc;

    // Get the current locale
    loc = setlocale(LC_ALL, NULL);

    printf("Starting locale: %s\n", loc);

    // Set (and get) the locale to native locale
    loc = setlocale(LC_ALL, "");
    
    printf("Native locale: %s\n", loc);
}

Output on my system:

Starting locale: C
Native locale: en_US.UTF-8

Note that my native locale (on a Linux box) might be different from what you see.

Nevertheless, I can explicitly set it on my system without a problem, or to any other locale I have installed:

    loc = setlocale(LC_ALL, "en_US.UTF-8");   // Non-portable

But again, your system might have different locales defined.

See Also

localeconv(), strcoll(), strxfrm(), strftime(), wcsftime(), printf(), scanf(), <ctype.h>

12.2 localeconv()

Get information about the current locale

Synopsis

#include <locale.h>

struct lconv *localeconv(void);

Description

This function just returns a pointer to a struct lconv, but is still a bit of a powerhouse.

The returned structure contains tons of information about the locale. Here are the fields of struct lconv and their meanings.

First, some conventions. In the field names, below, a _p_ means “positive”, and _n_ means “negative”, and int_ means “international”. Though a lot of these are type char or char*, most (or the strings they point to) are actually treated as integers²¹.

Before we go further, know that CHAR_MAX (from <limits.h>) is the maximum value that can be held in a char. And that many of the following char values use that to indicate the value isn’t available in the given locale.

Even though many of these have char type, the value stored within is meant to be accessed as an integer.

All the sep_by_space variants deal with spacing around the currency sign. Valid values are:

The sign_posn variants are determined by the following values:

Return Value

Returns a pointer to the structure containing the locale information.

The program may not modify this structure.

Subsequent calls to localeconv() may overwrite this structure, as might calls to setlocale() with LC_ALL, LC_MONETARY, or LC_NUMERIC.

Example

Here’s a program to print the locale information for the native locale.

#include <stdio.h>
#include <locale.h>
#include <limits.h>  // for CHAR_MAX

void print_grouping(char *mg)
{
    int done = 0;

    while (!done) {
        if (*mg == CHAR_MAX)
            printf("CHAR_MAX ");
        else
            printf("%c ", *mg + '0');
        done = *mg == CHAR_MAX || *mg == 0;
        mg++;
    }
}

int main(void)
{
    setlocale(LC_ALL, "");

    struct lconv *lc = localeconv();

    printf("mon_decimal_point : %s\n", lc->mon_decimal_point);
    printf("mon_thousands_sep : %s\n", lc->mon_thousands_sep);
    printf("mon_grouping      : ");
    print_grouping(lc->mon_grouping);
    printf("\n");
    printf("positive_sign     : %s\n", lc->positive_sign);
    printf("negative_sign     : %s\n", lc->negative_sign);
    printf("currency_symbol   : %s\n", lc->currency_symbol);
    printf("frac_digits       : %c\n", lc->frac_digits);
    printf("p_cs_precedes     : %c\n", lc->p_cs_precedes);
    printf("n_cs_precedes     : %c\n", lc->n_cs_precedes);
    printf("p_sep_by_space    : %c\n", lc->p_sep_by_space);
    printf("n_sep_by_space    : %c\n", lc->n_sep_by_space);
    printf("p_sign_posn       : %c\n", lc->p_sign_posn);
    printf("p_sign_posn       : %c\n", lc->p_sign_posn);
    printf("int_curr_symbol   : %s\n", lc->int_curr_symbol);
    printf("int_frac_digits   : %c\n", lc->int_frac_digits);
    printf("int_p_cs_precedes : %c\n", lc->int_p_cs_precedes);
    printf("int_n_cs_precedes : %c\n", lc->int_n_cs_precedes);
    printf("int_p_sep_by_space: %c\n", lc->int_p_sep_by_space);
    printf("int_n_sep_by_space: %c\n", lc->int_n_sep_by_space);
    printf("int_p_sign_posn   : %c\n", lc->int_p_sign_posn);
    printf("int_n_sign_posn   : %c\n", lc->int_n_sign_posn);
}

Output on my system:

mon_decimal_point : .
mon_thousands_sep : ,
mon_grouping      : 3 3 0 
positive_sign     : 
negative_sign     : -
currency_symbol   : $
frac_digits       : 2
p_cs_precedes     : 1
n_cs_precedes     : 1
p_sep_by_space    : 0
n_sep_by_space    : 0
p_sign_posn       : 1
p_sign_posn       : 1
int_curr_symbol   : USD 
int_frac_digits   : 2
int_p_cs_precedes : 1
int_n_cs_precedes : 1
int_p_sep_by_space: 1
int_n_sep_by_space: 1
int_p_sign_posn   : 1
int_n_sign_posn   : 1

See Also

setlocale()