newlocale - Man Page

create, modify, and free a locale object


Standard C library (libc, -lc)


#include <locale.h>

locale_t newlocale(int category_mask, const char *locale,
                   locale_t base);
void freelocale(locale_t locobj);

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

newlocale(), freelocale():

    Since glibc 2.10:
        _XOPEN_SOURCE >= 700
    Before glibc 2.10:


The newlocale() function creates a new locale object, or modifies an existing object, returning a reference to the new or modified object as the function result. Whether the call creates a new object or modifies an existing object is determined by the value of base:

If base is the special locale object LC_GLOBAL_LOCALE (see duplocale(3)), or is not (locale_t) 0 and is not a valid locale object handle, the behavior is undefined.

The category_mask argument is a bit mask that specifies the locale categories that are to be set in a newly created locale object or modified in an existing object. The mask is constructed by a bitwise OR of the constants LC_ADDRESS_MASK, LC_CTYPE_MASK, LC_COLLATE_MASK, LC_IDENTIFICATION_MASK, LC_MEASUREMENT_MASK, LC_MESSAGES_MASK, LC_MONETARY_MASK, LC_NUMERIC_MASK, LC_NAME_MASK, LC_PAPER_MASK, LC_TELEPHONE_MASK, and LC_TIME_MASK. Alternatively, the mask can be specified as LC_ALL_MASK, which is equivalent to ORing all of the preceding constants.

For each category specified in category_mask, the locale data from locale will be used in the object returned by newlocale(). If a new locale object is being created, data for all categories not specified in category_mask is taken from the default ("POSIX") locale.

The following preset values of locale are defined for all categories that can be specified in category_mask:


A minimal locale environment for C language programs.


Equivalent to "POSIX".


An implementation-defined native environment corresponding to the values of the LC_* and LANG environment variables (see locale(7)).


The freelocale() function deallocates the resources associated with locobj, a locale object previously returned by a call to newlocale() or duplocale(3). If locobj is LC_GLOBAL_LOCALE or is not valid locale object handle, the results are undefined.

Once a locale object has been freed, the program should make no further use of it.

Return Value

On success, newlocale() returns a handle that can be used in calls to duplocale(3), freelocale(), and other functions that take a locale_t argument. On error, newlocale() returns (locale_t) 0, and sets errno to indicate the error.



One or more bits in category_mask do not correspond to a valid locale category.


locale is NULL.


locale is not a string pointer referring to a valid locale.


Insufficient memory to create a locale object.




glibc 2.3.


Each locale object created by newlocale() should be deallocated using freelocale().


The program below takes up to two command-line arguments, which each identify locales. The first argument is required, and is used to set the LC_NUMERIC category in a locale object created using newlocale(). The second command-line argument is optional; if it is present, it is used to set the LC_TIME category of the locale object.

Having created and initialized the locale object, the program then applies it using uselocale(3), and then tests the effect of the locale changes by:


Displaying a floating-point number with a fractional part. This output will be affected by the LC_NUMERIC setting. In many European-language locales, the fractional part of the number is separated from the integer part using a comma, rather than a period.


Displaying the date. The format and language of the output will be affected by the LC_TIME setting.

The following shell sessions show some example runs of this program.

Set the LC_NUMERIC category to fr_FR (French):

$ ./a.out fr_FR
Fri Mar  7 00:25:08 2014

Set the LC_NUMERIC category to fr_FR (French), and the LC_TIME category to it_IT (Italian):

$ ./a.out fr_FR it_IT
ven 07 mar 2014 00:26:01 CET

Specify the LC_TIME setting as an empty string, which causes the value to be taken from environment variable settings (which, here, specify mi_NZ, New Zealand Māori):

$ LC_ALL=mi_NZ ./a.out fr_FR ""
Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET

Program source

#define _XOPEN_SOURCE 700
#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                        } while (0)

main(int argc, char *argv[])
    char buf[100];
    time_t t;
    size_t s;
    struct tm *tm;
    locale_t loc, nloc;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s locale1 [locale2]\n", argv[0]);

    /* Create a new locale object, taking the LC_NUMERIC settings
       from the locale specified in argv[1]. */

    loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
    if (loc == (locale_t) 0)

    /* If a second command-line argument was specified, modify the
       locale object to take the LC_TIME settings from the locale
       specified in argv[2]. We assign the result of this newlocale()
       call to 'nloc' rather than 'loc', since in some cases, we might
       want to preserve 'loc' if this call fails. */

    if (argc > 2) {
        nloc = newlocale(LC_TIME_MASK, argv[2], loc);
        if (nloc == (locale_t) 0)
        loc = nloc;

    /* Apply the newly created locale to this thread. */


    /* Test effect of LC_NUMERIC. */

    printf("%8.3f\n", 123456.789);

    /* Test effect of LC_TIME. */

    t = time(NULL);
    tm = localtime(&t);
    if (tm == NULL)

    s = strftime(buf, sizeof(buf), "%c", tm);
    if (s == 0)

    printf("%s\n", buf);

    /* Free the locale object. */

    uselocale(LC_GLOBAL_LOCALE);    /* So 'loc' is no longer in use */


See Also

locale(1), duplocale(3), setlocale(3), uselocale(3), locale(5), locale(7)

Referenced By

duplocale(3), isalpha(3), locale(5), locale(7), nl_langinfo(3), toupper(3), uselocale(3).

The man page freelocale(3) is an alias of newlocale(3).

2023-10-31 Linux man-pages 6.7