setlocale, _wsetlocale

• 4/2/2020
• 10 minutes to read
• • T
  • s
  • c
  • m
  • m
  • +3

Sets or retrieves the run-time locale.

Syntax

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

Parameters

category
Category affected by locale.

locale
Locale specifier.

Return value

If a valid locale and category are given, returns a pointer to the string associated with the specified locale and category. If the locale or category isn't valid, returns a null pointer, and the current locale settings of the program are unchanged.

For example, the call

setlocale( LC_ALL, "en-US" );

sets all categories, returning only the string

en-US

You can copy the string returned by setlocale to restore that part of the program's locale information. Global or thread local storage is used for the string returned by setlocale. Later calls to setlocale overwrite the string, which invalidates string pointers returned by earlier calls.

Remarks

Use the setlocale function to set, change, or query some or all of the current program locale information specified by locale and category. locale refers to the locality (country/region and language) for which you can customize certain aspects of your program. Some locale-dependent categories include the formatting of dates and the display format for monetary values. If you set locale to the default string for a language that has multiple forms supported on your computer, you should check the setlocale return value to see which language is in effect. For example, if you set locale to "chinese" the return value could be either "chinese-simplified" or "chinese-traditional".

_wsetlocale is a wide-character version of setlocale; the locale argument and return value of _wsetlocale are wide-character strings. _wsetlocale and setlocale behave identically otherwise.

By default, this function's global state is scoped to the application. To change this, see Global state in the CRT.

Generic-Text Routine Mappings

The category argument specifies the parts of a program's locale information that are affected. The macros used for category and the parts of the program they affect are as follows:

This function validates the category parameter. If the category parameter isn't one of the values given in the previous table, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, the function sets errno to EINVAL and returns NULL.

The locale argument is a pointer to a string that specifies the locale. For information about the format of the locale argument, see Locale Names, Languages, and Country/Region Strings. If locale points to an empty string, the locale is the implementation-defined native environment. A value of C specifies the minimal ANSI conforming environment for C translation. The C locale assumes that all char data types are 1 byte and that their value is always less than 256.

At program startup, the equivalent of the following statement is executed:

setlocale( LC_ALL, "C" );

The locale argument can take a locale name, a language string, a language string and country/region code, a code page, or a language string, country/region code, and code page. The set of available locale names, languages, country/region codes, and code pages includes all those supported by the Windows NLS API. The set of locale names supported by setlocale are described in Locale Names, Languages, and Country/Region Strings. The set of language and country/region strings supported by setlocale are listed in Language Strings and Country/Region Strings. We recommend the locale name form for performance and for maintainability of locale strings embedded in code or serialized to storage. The locale name strings are less likely to be changed by an operating system update than the language and country/region name form.

A null pointer that's passed as the locale argument tells setlocale to query instead of to set the international environment. If the locale argument is a null pointer, the program's current locale setting isn't changed. Instead, setlocale returns a pointer to the string that's associated with the category of the thread's current locale. If the category argument is LC_ALL, the function returns a string that indicates the current setting of each category, separated by semicolons. For example, the sequence of calls

// Set all categories and return "en-US"
setlocale(LC_ALL, "en-US");
// Set only the LC_MONETARY category and return "fr-FR"
setlocale(LC_MONETARY, "fr-FR");
printf("%s\n", setlocale(LC_ALL, NULL));

returns

LC_COLLATE=en-US;LC_CTYPE=en-US;LC_MONETARY=fr-FR;LC_NUMERIC=en-US;LC_TIME=en-US

which is the string that's associated with the LC_ALL category.

The following examples pertain to the LC_ALL category. Either of the strings ".OCP" and ".ACP" can be used instead of a code page number to specify use of the user-default OEM code page and user-default ANSI code page for that locale name, respectively.

• setlocale( LC_ALL, "" );

  Sets the locale to the default, which is the user-default ANSI code page obtained from the operating system. The locale name is set to the value returned by GetUserDefaultLocaleName. The code page is set to the value returned by GetACP.

• setlocale( LC_ALL, ".OCP" );

  Sets the locale to the current OEM code page obtained from the operating system. The locale name is set to the value returned by GetUserDefaultLocaleName. The code page is set to the LOCALE_IDEFAULTCODEPAGE value for the user-default locale name by GetLocaleInfoEx.

• setlocale( LC_ALL, ".ACP" );

  Sets the locale to the ANSI code page obtained from the operating system. The locale name is set to the value returned by GetUserDefaultLocaleName. The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the user-default locale name by GetLocaleInfoEx.

• setlocale( LC_ALL, "<localename>" );

  Sets the locale to the locale name that's indicated by <localename>. The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the specified locale name by GetLocaleInfoEx.

• setlocale( LC_ALL, "<language>_<country>" );

  Sets the locale to the language and country/region indicated by <language> and <country>, together with the default code page obtained from the host operating system. The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the specified locale name by GetLocaleInfoEx.

• setlocale( LC_ALL, "<language>_<country>.<code_page>" );

  Sets the locale to the language, country/region, and code page indicated by the <language>, <country>, and <code_page> strings. You can use various combinations of language, country/region, and code page. For example, this call sets the locale to French Canada with code page 1252:

  setlocale( LC_ALL, "French_Canada.1252" );

  This call sets the locale to French Canada with the default ANSI code page:

  setlocale( LC_ALL, "French_Canada.ACP" );

  This call sets the locale to French Canada with the default OEM code page:

  setlocale( LC_ALL, "French_Canada.OCP" );

• setlocale( LC_ALL, "<language>" );

  Sets the locale to the language that's indicated by <language>, and uses the default country/region for the specified language and the user-default ANSI code page for that country/region as obtained from the host operating system. For example, the following calls to setlocale are functionally equivalent:

  setlocale( LC_ALL, "en-US" );

  setlocale( LC_ALL, "English" );

  setlocale( LC_ALL, "English_United States.1252" );

  We recommend the first form for performance and maintainability.

• setlocale( LC_ALL, ".<code_page>" );

  Sets the code page to the value indicated by <code_page>, together with the default country/region and language (as defined by the host operating system) for the specified code page.

The category must be either LC_ALL or LC_CTYPE to effect a change of code page. For example, if the default country/region and language of the host operating system are "United States" and "English," the following two calls to setlocale are functionally equivalent:

setlocale( LC_ALL, ".1252" );

setlocale( LC_ALL, "English_United States.1252");

For more information, see the setlocale pragma directive in the C/C++ Preprocessor Reference.

The function _configthreadlocale is used to control whether setlocale affects the locale of all threads in a program or only the locale of the calling thread.

UTF-8 Support

Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. This means that char strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use "UTF-8" as the code page when using setlocale. For example, setlocale(LC_ALL, ".utf8") will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.

After calling setlocale(LC_ALL, ".UTF8"), you may pass "😊" to mbtowcs and it will be properly translated to a wchar_t string, whereas previously there was not a locale setting available to do this.

UTF-8 mode is also enabled for functions that have historically translated char strings using the default Windows ANSI code page (ACP). For example, calling _mkdir("😊") while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 prior to running your program. Likewise, calling _getcwd() inside of that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.

The following aspects of the C Runtime that are not able to use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): __argv, _acmdln, and _pgmptr.

Previous to this support, mbrtoc16, mbrtoc32, c16rtomb, and c32rtomb existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as wchar_t on Windows platforms) and UTF-32. For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via setlocale.

To use this feature on an OS prior to Windows 10, such as Windows 7, you must use app-local deployment or link statically using version 17134 of the Windows SDK or later. For Windows 10 operating systems prior to 17134, only static linking is supported.

Requirements

For additional compatibility information, see Compatibility.

Example

// crt_setlocale.c
//
// This program demonstrates the use of setlocale when
// using two independent threads.
//

#include <locale.h>
#include <process.h>
#include <windows.h>
#include <stdio.h>
#include <time.h>

#define BUFF_SIZE 100

// Retrieve the date in the current
// locale's format.
int get_date(unsigned char* str)
{
    __time64_t ltime;
    struct tm  thetime;

    // Retrieve the current time
    _time64(&ltime);
    _gmtime64_s(&thetime, &ltime);

    // Format the current time structure into a string
    // "%#x" is the long date representation in the
    // current locale
    if (!strftime((char *)str, BUFF_SIZE, "%#x",
                  (const struct tm *)&thetime))
    {
        printf("strftime failed!\n");
        return -1;
    }
    return 0;
}

// This thread sets its locale to the argument
// and prints the date.
uintptr_t __stdcall SecondThreadFunc( void* pArguments )
{
    unsigned char str[BUFF_SIZE];
    char * locale = (char *)pArguments;

    // Set the thread locale
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, locale));

    // Retrieve the date string from the helper function
    if (get_date(str) == 0)
    {
        printf("The date in %s locale is: '%s'\n", locale, str);
    }

    _endthreadex( 0 );
    return 0;
}

// The main thread sets the locale to English
// and then spawns a second thread (above) and prints the date.
int main()
{
    HANDLE          hThread;
    unsigned        threadID;
    unsigned char   str[BUFF_SIZE];

    // Enable per-thread locale causes all subsequent locale
    // setting changes in this thread to only affect this thread.
    _configthreadlocale(_ENABLE_PER_THREAD_LOCALE);

    // Set the locale of the main thread to US English.
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, "en-US"));

    // Create the second thread with a German locale.
    // Our thread function takes an argument of the locale to use.
    hThread = (HANDLE)_beginthreadex( NULL, 0, &SecondThreadFunc,
                                      "de-DE", 0, &threadID );

    if (get_date(str) == 0)
    {
        // Retrieve the date string from the helper function
        printf("The date in en-US locale is: '%s'\n\n", str);
    }

    // Wait for the created thread to finish.
    WaitForSingleObject( hThread, INFINITE );

    // Destroy the thread object.
    CloseHandle( hThread );
}

The thread locale is now set to en-US.
The time in en-US locale is: 'Wednesday, May 12, 2004'

The thread locale is now set to de-DE.
The time in de-DE locale is: 'Mittwoch, 12. Mai 2004'

See also

Locale Names, Languages, and Country/Region Strings
_configthreadlocale
_create_locale, _wcreate_locale
Locale
localeconv
_mbclen, mblen, _mblen_l
strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
strcoll Functions
strftime, wcsftime, _strftime_l, _wcsftime_l
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l