setlocale, _wsetlocale

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

Синтаксис

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возвращаемое значение. Поведение недопустимых аргументов выглядит следующим образом:

Вызов

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.

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

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

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

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

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

setlocale( LC_ALL, "C" );

Аргумент locale может принимать имя языкового стандарта, строковую переменную с названием языка, строковую переменную с названием языка и код страны или региона, кодовую страницу или строковую переменную с названием языка, код страны или региона и кодовую страницу. Доступные имена языков, языки, коды стран и регионов и кодовые страницы включают все те, которые поддерживаются API NLS Windows. Набор имен языкового стандарта, поддерживаемых 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. Это означает, что строки, передаваемые функциям среды выполнения C, char могут ожидать строки в кодировке 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, , mbrtoc32c16rtombи c32rtomb существовали для перевода между узкими строками UTF-8, UTF-16 (такая же кодировка, как wchar_t на платформах Windows) и UTF-32. По соображениям совместимости эти API по-прежнему переводятся только в UTF-8 и не с кодовой страницы.setlocale

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

Требования

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

Пример

// 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.
unsigned __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,
                                      (void*)"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 date in en-US locale is: 'Thursday, January 4, 2024'

The thread locale is now set to de-DE.
The date in de-DE locale is: 'Donnerstag, 4. Januar 2024'

См. также

Имена языков, языки и строки страны или региона
_configthreadlocale
_create_locale, _wcreate_locale
Локаль
localeconv
_mbclen, , mblen_mblen_l
strlen, , wcslen_mbslen_l_mbslen_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