`setlocale`, `_wsetlocale`

Статья
04/20/2023

Устанавливает или извлекает языковой стандарт времени выполнения.

Синтаксис

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

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

Параметры

category
Категория, на которую влияет языковой стандарт.

locale
Указатель языкового стандарта.

Возвращаемое значение

Если задано допустимое locale значение и category , функции возвращают указатель на строку, связанную с указанными locale и category. locale Если аргумент имеет значение NULL, функции возвращают текущий языковой стандарт.

Если в любой из функций передается недопустимый аргумент, возвращается NULLзначение . Поведение недопустимых аргументов выглядит следующим образом:

Функция	недопустимый параметр.	Вызов недопустимого обработчика, как описано в разделе Проверка параметров	Задает `errno`
`setlocale`	`category`	да	да
`setlocale`	`locale`	нет	нет
`_wsetlocale`	`category`	да	да
`_wsetlocale`	`locale`	нет	нет

Вызов

setlocale( LC_ALL, "en-US" );

задает все категории, возвращая только строку

en-US

Можно скопировать строку, возвращенную setlocale, для восстановления этой части данных о языковом стандарте программы. Глобальное или локальное хранилище потока используется для строки, возвращаемой setlocale. Последующие вызовы setlocale перезаписывают эту строку, что аннулирует указатели строк, возвращенные предыдущими вызовами.

Используйте функцию setlocale для задания, изменения или получения некоторой или всей информации о языковом стандарте текущей программы, определяемой locale и category. locale ссылается на расположение (страну или регион и язык), для которого можно настраивать определенные аспекты программы. К некоторым категориям, зависящим от языкового стандарта, относится формат дат и отображения денежных значений. Если для locale задается строка по умолчанию для языка с несколькими формами, которые поддерживаются на вашем компьютере, необходимо проверять возвращаемое значение setlocale, чтобы узнать, какой язык применяется. Например, если для параметра задано locale"chinese" возвращаемое значение, может быть или "chinese-traditional""chinese-simplified" .

_wsetlocale — это версия с расширенными символами для setlocale; аргумент locale и возвращаемое значение _wsetlocale являются строками с расширенными символами. Поведение_wsetlocale и setlocale идентично в противном случае.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см. статью Глобальное состояние в CRT.

Сопоставления подпрограмм универсального текста

`TCHAR.H` Обычной	`_UNICODE` и `_MBCS` не определены	`_MBCS` Определенные	`_UNICODE` Определенные
`_tsetlocale`	`setlocale`	`setlocale`	`_wsetlocale`

Аргумент category указывает части информации о языковом стандарте программы, которые подвергаются влиянию. Макросы, используемые для category и части программы, на которые они оказывают, указаны ниже.

Флаг`category`	Область применения
`LC_ALL`	Все категории, перечисленные ниже.
`LC_COLLATE`	Функции `strcoll`, `_stricoll`, `wcscoll`, `_wcsicoll`, `strxfrm`, `_strncoll`, `_strnicoll`, `_wcsncoll`, `_wcsnicoll` и `wcsxfrm`.
`LC_CTYPE`	Функции обработки символов (за исключением `isdigit`, `isxdigit`, `mbstowcs` и `mbtowc`, которые не затрагиваются).
`LC_MONETARY`	Информация о форматировании денежных значений, возвращаемая функцией `localeconv`.
`LC_NUMERIC`	Символ десятичной запятой для форматированных выходных процедур (например `printf`, ), для подпрограмм преобразования данных и для сведений о форматировании, возвращаемых методом `localeconv`. В дополнение к десятичному символу, задает разделитель разрядов и строку управления группировкой, `LC_NUMERIC` возвращаемую `localeconv`.
`LC_TIME`	Функции `strftime` и `wcsftime`.

Эта функция проверяет параметр категории. Если параметр category не является одним из значений, приведенных в предыдущей таблице, вызывается обработчик недопустимых параметров, как описано в разделе Проверка параметров. Если выполнение может быть продолжено, эта функция задает для errno значение EINVAL и возвращает NULL.

Аргумент locale является указателем на строку, которая задает языковой стандарт. Сведения о формате аргумента см. в locale разделах Названия языкового стандарта, Языки и Строки стран и регионов. Если locale указывает на пустую строку, языковой стандарт соответствует исходной среде, определенной реализацией. Значение C задает минимальную подходящую ANSI среду для переноса C. Языковой стандарт C предполагает, что все типы данных char соответствуют 1 байту, а их значение всегда меньше 256.

При запуске программы выполняется эквивалент следующего оператора:

setlocale( LC_ALL, "C" );

Аргумент locale может принимать имя языкового стандарта, строковую переменную с названием языка, строковую переменную с названием языка и код страны или региона, кодовую страницу или строковую переменную с названием языка, код страны или региона и кодовую страницу. Доступные имена языковых стандартов, языки, коды стран или регионов и кодовая страница включают все те, которые поддерживаются API windows NLS. Набор имен языковых стандартов, поддерживаемых setlocale , описан в разделах Названия языкового стандарта, Языки и Строки стран и регионов. Набор строк языка и страны или региона, поддерживаемых setlocale , перечислены в языковых строках и строках страны или региона. Рекомендуется использовать форму имени языкового стандарта для обеспечения производительности и удобства поддержки строк языкового стандарта, внедренных в код или сериализованных в хранилище. Строковые значения имен языкового стандарта реже подвергаются изменению обновлением операционной системы, чем язык и форма названия страны или региона.

Указатель null, который передается в качестве аргумента locale, указывает setlocale выполнить запрос, а не задать международную среду. locale Если аргумент является пустым указателем, текущий языковой стандарт программы не изменяется. Вместо этого setlocale возвращает указатель на строку, связанную с category текущего языкового стандарта этого потока. Если аргумент category имеет значение LC_ALL, функция возвращает строку, которая указывает текущий параметр каждой категории с разделением точкой с запятой. Например, последовательность вызовов

// 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));

возвращает

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

и это строка, связанная с категорией LC_ALL.

Следующие примеры относятся к категории LC_ALL. Любая из строк . OCP" и ". ACP" можно использовать вместо номера кодовой страницы, чтобы указать использование пользовательской кодовой страницы OEM и пользовательской кодовой страницы ANSI по умолчанию для этого имени языкового стандарта соответственно.

setlocale( LC_ALL, "" );

Задает языковой стандарт по умолчанию, т.е. заданную по умолчанию для пользователя кодовую страницу ANSI, полученную от операционной системы. Для имени языкового стандарта задается значение, возвращаемое GetUserDefaultLocaleName. Кодовая страница имеет значение, возвращаемое GetACP.
setlocale( LC_ALL, ".OCP" );

Задает языковой стандарт для текущей кодовой страницы OEM, полученной из операционной системы. Для имени языкового стандарта задается значение, возвращаемое GetUserDefaultLocaleName. Кодовая страница имеет LOCALE_IDEFAULTCODEPAGE значение для имени пользовательского языкового стандарта по умолчанию.GetLocaleInfoEx
setlocale( LC_ALL, ".ACP" );

Задает языковой стандарт согласно текущей кодовой странице ANSI, полученной от операционной системы. Для имени языкового стандарта задается значение, возвращаемое GetUserDefaultLocaleName. Кодовая страница имеет LOCALE_IDEFAULTANSICODEPAGE значение для имени пользовательского языкового стандарта по умолчанию.GetLocaleInfoEx
setlocale( LC_ALL, "<localename>" );

Задает для языкового стандарта имя языкового стандарта, указываемое параметром <localename>. Кодовая страница имеет LOCALE_IDEFAULTANSICODEPAGE значение для указанного имени языкового стандарта с помощью GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>" );

Задает язык и страну или регион, указанные <language> в и <country>, а также кодовую страницу по умолчанию, полученную из операционной системы узла. Кодовая страница имеет LOCALE_IDEFAULTANSICODEPAGE значение для указанного имени языкового стандарта с помощью GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );

Задает язык, страну или регион и кодовую страницу, указанные <language>строками , <country>и <code_page> . Можно использовать различные сочетания языка, страны или региона и кодовой страницы. Например, этот вызов устанавливает языковой стандарт "французский (Канада)" с кодовой страницей 1252.

setlocale( LC_ALL, "French_Canada.1252" );

Этот вызов устанавливает языковой стандарт "французский (Канада)" с кодовой страницей по умолчанию ANSI.

setlocale( LC_ALL, "French_Canada.ACP" );

Этот вызов устанавливает языковой стандарт "французский (Канада)" с кодовой страницей по умолчанию OEM.

setlocale( LC_ALL, "French_Canada.OCP" );
setlocale( LC_ALL, "<language>" );

Задает язык, указанный в параметре <language>, и использует страну или регион по умолчанию для указанного языка и кодовую страницу ANSI по умолчанию для этой страны или региона, полученную из операционной системы узла. Например, следующие вызовы setlocale функционально эквивалентны:

setlocale( LC_ALL, "en-US" );

setlocale( LC_ALL, "English" );

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

Рекомендуется использовать первую форму для обеспечения производительности и простоты обслуживания.
setlocale( LC_ALL, ".<code_page>" );

Задает для кодовой страницы значение, указанное в параметре <code_page>, а также страну или регион по умолчанию и язык (в соответствии с определением операционной системы узла) для указанной кодовой страницы.

Эта категория должна быть LC_ALL или LC_CTYPE для реализации изменения кодовой страницы. Например, если страной или регионом по умолчанию и языком операционной системы узла являются "United States" и "English", следующие два вызова setlocale функционально эквивалентны:

setlocale( LC_ALL, ".1252" );

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

Дополнительные сведения см. в директиве setlocale pragma в справочнике по препроцессору C/C++.

Функция _configthreadlocale используется для управления тем, влияет ли setlocale языковой стандарт всех потоков в программе или только языковой стандарт вызывающего потока.

Поддержка UTF-8.

Начиная с Windows 10 версии 1803 (10.0.17134.0), универсальная среда выполнения C поддерживает использование кодовой страницы UTF-8. Это изменение означает, что строки, char передаваемые в функции среды выполнения C, могут ожидать строк в кодировке UTF-8. Чтобы включить режим UTF-8, используйте ".UTF8" в качестве кодовой страницы при использовании setlocale. Например, setlocale(LC_ALL, ".UTF8") использует текущую кодовую страницу WINDOWS ANSI (ACP) по умолчанию для языкового стандарта и UTF-8 для кодовой страницы.

Строка для указания режима UTF-8:

Не учитывает регистр.
дефис (-) является необязательным
Он должен находиться в кодовой странице имени языкового стандарта, поэтому должен иметь начальную точку (.), как показано в следующих примерах: "en_US.UTF8" или ".utf8"

В следующих примерах показано, как указать строку UTF-8:

".UTF8"
".UTF-8"
".utf8"
".utf-8"
"en_us.utf8"
"ja_JP.Utf-8"

После вызова setlocale(LC_ALL, ".UTF8")можно передать "😊" в mbtowcs , и он будет правильно преобразован в wchar_t строку. Ранее для этого перевода не было параметров языкового стандарта.

Режим UTF-8 также включен для функций, которые имеют исторически переведенные char строки с помощью кодовой страницы Windows ANSI (ACP) по умолчанию. Например, при вызове _mkdir("😊") кодовой страницы UTF-8 будет правильно создаваться каталог с этим эмодзи в качестве имени папки, а не требовать, чтобы ACP был изменен на UTF-8 перед запуском программы. Аналогичным образом, вызов _getcwd() в этой папке возвращает строку в кодировке UTF-8. Для обеспечения совместимости ACP по-прежнему используется, если для кодовой страницы C не задано значение UTF-8.

Следующие аспекты среды выполнения C не могут использовать UTF-8, так как они задаются во время запуска программы и должны использовать кодовую страницу WINDOWS ANSI по умолчанию (ACP): __argv, _acmdlnи _pgmptr.

Ранее эта поддержкаmbrtoc16, , mbrtoc32,c16rtomb и c32rtomb существовала для перевода между узкими строками UTF-8, UTF-16 (такая же кодировка, как wchar_t на платформах Windows) и UTF-32. Для обеспечения совместимости эти API по-прежнему преобразуют только в UTF-8 и из них, а не кодовую страницу, заданную через setlocale.

Чтобы использовать эту функцию в ОС до Windows 10, необходимо использовать локальное развертывание приложения или связаться статически с помощью windows SDK версии 1803 (10.0.17134.0). Для Windows 10 операционных систем до версии 1803 (10.0.17134.0) поддерживается только статическая компоновка.

Требования

Подпрограмма	Обязательный заголовок
`setlocale`	`<locale.h>`
`_wsetlocale`	`<locale.h>` или `<wchar.h>`

Дополнительные сведения о совместимости см. в разделе Compatibility.

Пример

// 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'

См. также раздел

Имена языкового стандарта, языки и строки страны или региона
_configthreadlocale
_create_locale, _wcreate_locale
Локаль
localeconv
_mbclen, mblen, _mblen_l
strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
Функции strcoll
strftime, wcsftime, _strftime_l, _wcsftime_l
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l

`setlocale`, `_wsetlocale`

Синтаксис

Параметры

Возвращаемое значение

Комментарии

Сопоставления подпрограмм универсального текста

Поддержка UTF-8.

Требования

Пример

См. также раздел

Дополнительные ресурсы

Дополнительные ресурсы

setlocale, _wsetlocale

Синтаксис

Параметры

Возвращаемое значение

Комментарии

Сопоставления подпрограмм универсального текста

Поддержка UTF-8.

Требования

Пример

См. также раздел

Дополнительные ресурсы

Дополнительные ресурсы

`setlocale`, `_wsetlocale`