setlocale, _wsetlocale

Ustaw lub pobierz ustawienia regionalne czasu wykonywania.

Składnia

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

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

Parametry

category
Kategoria, której dotyczą ustawienia regionalne.

locale
Specyfikator ustawień regionalnych.

Wartość zwracana

Jeśli wartość jest prawidłowa locale i category jest podana, funkcje zwracają wskaźnik do ciągu skojarzonego z określonymi locale wartościami i category. locale Jeśli argument to NULL, funkcje zwracają bieżące ustawienia regionalne.

Jeśli do jednej z funkcji zostanie przekazany nieprawidłowy argument, zwracana wartość to NULL. Zachowanie nieprawidłowych argumentów jest następujące:

Wywołanie:

setlocale( LC_ALL, "en-US" );

ustawia wszystkie kategorie, zwracając tylko ciąg

en-US

Możesz skopiować ciąg zwrócony przez setlocale program, aby przywrócić te części informacji o ustawieniach regionalnych programu. Magazyn lokalny globalny lub wątkowy jest używany dla ciągu zwracanego przez setlocale. Później wywołuje metodę zastępowania setlocale ciągu, która unieważnia wskaźniki ciągu zwracane przez wcześniejsze wywołania.

Uwagi

setlocale Użyj funkcji , aby ustawić, zmienić lub wysłać zapytanie dotyczące niektórych lub wszystkich bieżących ustawień regionalnych programu określonych przez locale i category. locale odnosi się do lokalizacji (kraj/region i język), dla których można dostosować niektóre aspekty programu. Niektóre kategorie zależne od ustawień regionalnych obejmują formatowanie dat i format wyświetlania wartości pieniężnych. Jeśli ustawisz locale domyślny ciąg dla języka, który ma wiele formularzy obsługiwanych na komputerze, sprawdź wartość zwracaną setlocale , aby zobaczyć, który język jest w mocy. Jeśli na przykład ustawiono locale "chinese" wartość zwracaną, może to być "chinese-simplified" wartość lub "chinese-traditional".

_wsetlocalejest wersją szerokoznakową ; setlocalelocale argument i wartość zwracana _wsetlocale są ciągami o szerokim znaku. _wsetlocale i setlocale zachowywać się identycznie inaczej.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

Argument category określa części informacji o ustawieniach regionalnych programu, których dotyczy problem. Makra używane w programie category i jego części są następujące:

Ta funkcja sprawdza poprawność parametru kategorii. Jeśli parametr kategorii nie jest jedną z wartości podanych w poprzedniej tabeli, wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja ustawia wartość errno EINVAL i zwraca wartość NULL.

Argument locale jest wskaźnikiem do ciągu, który określa ustawienia regionalne. Aby uzyskać informacje o formacie argumentu locale , zobacz Nazwy ustawień regionalnych, Języki i Ciągi kraju/regionu. Jeśli locale wskazuje pusty ciąg, ustawienia regionalne są środowiskiem natywnym zdefiniowanym przez implementację. Wartość parametru C określa minimalne środowisko zgodne ze standardem ANSI na potrzeby tłumaczenia języka C. Ustawienia C regionalne zakładają, że wszystkie char typy danych to 1 bajt i że ich wartość jest zawsze mniejsza niż 256.

W momencie uruchamiania programu wykonywany jest odpowiednik następującej instrukcji:

setlocale( LC_ALL, "C" );

Argument locale może przyjmować nazwę ustawień regionalnych, ciąg języka, ciąg języka i kod kraju/regionu, stronę kodową lub ciąg języka, kod kraju/regionu i stronę kodową. Dostępne nazwy ustawień regionalnych, języki, kody kraju/regionu i strony kodu obejmują wszystkie te obsługiwane przez interfejs API równoważenia obciążenia sieciowego systemu Windows. Zestaw nazw ustawień regionalnych obsługiwanych przez setlocale program jest opisany w temacie Nazwy ustawień regionalnych, Języki i Ciągi kraju/regionu. Zestaw ciągów języka i kraju/regionu obsługiwanych przez setlocale program jest wymieniony w ciągach języka i ciągach kraju/regionu. Firma Microsoft zaleca formę nazwy ustawień regionalnych ze względu na wydajność i łatwość konserwacji ciągów ustawień regionalnych, osadzonych w kodzie lub szeregowanych do pamięci. Zmiana ciągów nazw ustawień regionalnych przez aktualizację systemu operacyjnego jest mniej prawdopodobna niż zmiana formy nazwy języka i kraju/regionu.

Wskaźnik o wartości null, który jest przekazywany, gdy locale argument informuje setlocale o zapytaniu zamiast ustawiać środowisko międzynarodowe. locale Jeśli argument jest wskaźnikiem o wartości null, bieżące ustawienie ustawień regionalnych programu nie zostanie zmienione. setlocale Zamiast tego zwraca wskaźnik do ciągu skojarzonego z category bieżącymi ustawieniami regionalnymi wątku. category Jeśli argument to LC_ALL, funkcja zwraca ciąg wskazujący bieżące ustawienie każdej kategorii rozdzielone średnikami. Na przykład, sekwencja wywołań

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

zwraca

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

to ciąg skojarzony z kategorią LC_ALL .

Poniższe przykłady odnoszą się do LC_ALL kategorii. Jeden z ciągów ". OCP" i ". Acp" można użyć zamiast numeru strony kodowej, aby określić użycie domyślnej strony kodowej OEM użytkownika i domyślnej strony kodowej ANSI użytkownika odpowiednio dla tej nazwy ustawień regionalnych.

• setlocale( LC_ALL, "" );

  Ustawia ustawienia regionalne na domyślne, czyli domyślną stronę kodową ANSI użytkownika, uzyskaną z systemu operacyjnego. Nazwa ustawień regionalnych jest ustawiona na wartość zwracaną przez GetUserDefaultLocaleName. Strona kodowa jest ustawiona na wartość zwracaną przez GetACP.

• setlocale( LC_ALL, ".OCP" );

  Ustawia ustawienia regionalne na bieżącą stronę kodu producenta OEM uzyskaną z systemu operacyjnego. Nazwa ustawień regionalnych jest ustawiona na wartość zwracaną przez GetUserDefaultLocaleName. Strona kodowa jest ustawiona LOCALE_IDEFAULTCODEPAGE na wartość domyślnej nazwy ustawień regionalnych użytkownika przez GetLocaleInfoEx.

• setlocale( LC_ALL, ".ACP" );

  Ustawia ustawienia regionalne na bieżącą stronę kodową ANSI, uzyskaną od systemu operacyjnego. Nazwa ustawień regionalnych jest ustawiona na wartość zwracaną przez GetUserDefaultLocaleName. Strona kodowa jest ustawiona LOCALE_IDEFAULTANSICODEPAGE na wartość domyślnej nazwy ustawień regionalnych użytkownika przez GetLocaleInfoEx.

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

  Ustawia ustawienia regionalne na nazwę ustawień regionalnych, która jest wskazywana przez <localename>. Strona kodowa jest ustawiona LOCALE_IDEFAULTANSICODEPAGE na wartość określonej nazwy ustawień regionalnych według .GetLocaleInfoEx

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

  Ustawia ustawienia regionalne na język i kraj/region wskazany przez <language> i <country>, wraz z domyślną stroną kodów uzyskaną z systemu operacyjnego hosta. Strona kodowa jest ustawiona LOCALE_IDEFAULTANSICODEPAGE na wartość określonej nazwy ustawień regionalnych według .GetLocaleInfoEx

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

  Ustawia ustawienia regionalne na język, kraj/region i stronę kodową wskazywaną <language>przez ciągi , <country>i <code_page> . Można użyć różnych kombinacji języka, kraju/regionu i strony kodowej. Na przykład, to wywołanie ustawia ustawienia regionalne na francuski-Kanada ze stroną kodową 1252:

  setlocale( LC_ALL, "French_Canada.1252" );

  To wywołanie ustawia ustawienia regionalne na francuski-Kanada z domyślną stroną kodową ANSI:

  setlocale( LC_ALL, "French_Canada.ACP" );

  To wywołanie ustawia ustawienia regionalne na francuski-Kanada z domyślną stroną kodową OEM:

  setlocale( LC_ALL, "French_Canada.OCP" );

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

  Ustawia ustawienia regionalne na język wskazany przez <language>, i używa domyślnego kraju/regionu dla określonego języka oraz domyślnej strony kodowej ANSI użytkownika dla tego kraju/regionu uzyskanego z systemu operacyjnego hosta. Na przykład następujące wywołania są setlocale funkcjonalnie równoważne:

  setlocale( LC_ALL, "en-US" );

  setlocale( LC_ALL, "English" );

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

  Zaleca się pierwszą formę ze względu na wydajność oraz łatwość konserwacji.

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

  Ustawia stronę kodu na wartość wskazaną przez <code_page>, wraz z domyślnym krajem/regionem i językiem (zdefiniowanym przez system operacyjny hosta) dla określonej strony kodowej.

Kategoria musi mieć LC_ALL wartość lub LC_CTYPE w celu wprowadzenia zmiany strony kodowej. Jeśli na przykład domyślny kraj/region i język systemu operacyjnego hosta to "United States" i "English", następujące dwa wywołania setlocale są funkcjonalnie równoważne:

setlocale( LC_ALL, ".1252" );

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

Aby uzyskać więcej informacji, zobacz dyrektywę setlocale pragma w dokumentacji preprocesora języka C/C++.

Funkcja _configthreadlocale służy do kontrolowania, czy setlocale wpływa na ustawienia regionalne wszystkich wątków w programie, czy tylko ustawienia regionalne wątku wywołującego.

Obsługa protokołu UTF-8

Począwszy od systemu Windows 10 w wersji 1803 (10.0.17134.0), środowisko uruchomieniowe uniwersalnego języka C obsługuje korzystanie ze strony kodowej UTF-8. Zmiana oznacza, że char ciągi przekazywane do funkcji środowiska uruchomieniowego języka C mogą oczekiwać ciągów w kodowaniu UTF-8. Aby włączyć tryb UTF-8, użyj jako ".UTF8" strony kodowej w przypadku korzystania z polecenia setlocale. Na przykład setlocale(LC_ALL, ".UTF8") używa bieżącej domyślnej strony kodowej systemu Windows ANSI (ACP) dla ustawień regionalnych i UTF-8 dla strony kodowej.

Ciąg określający tryb UTF-8 to:

• bez uwzględniania wielkości liter
• łącznik (-) jest opcjonalny
• Musi ona znajdować się w części strony kodowej nazwy ustawień regionalnych, więc musi mieć kropkę wiodącą (.), jak w następujących przykładach: "en_US.UTF8" lub ".utf8"

W poniższych przykładach pokazano, jak określić ciąg UTF-8:

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

Po wywołaniu setlocale(LC_ALL, ".UTF8")metody można przekazać element "😊" do mbtowcs elementu i zostanie on prawidłowo przetłumaczony na wchar_t ciąg. Wcześniej nie było dostępne ustawienie ustawień regionalnych do wykonania tego tłumaczenia.

Tryb UTF-8 jest również włączony dla funkcji, które mają historycznie przetłumaczone char ciągi przy użyciu domyślnej strony kodowej SYSTEMU Windows ANSI (ACP). Na przykład wywołanie _mkdir("😊") podczas korzystania ze strony kodowej UTF-8 spowoduje poprawne utworzenie katalogu z tym emoji jako nazwy folderu, zamiast wymagać zmiany elementu ACP na UTF-8 przed uruchomieniem programu. Podobnie wywołanie _getcwd() w tym folderze zwraca zakodowany ciąg UTF-8. W celu zapewnienia zgodności urządzenie ACP jest nadal używane, jeśli strona kodowa języka C nie jest ustawiona na wartość UTF-8.

Następujące aspekty środowiska uruchomieniowego języka C nie mogą używać protokołu UTF-8, ponieważ są one ustawiane podczas uruchamiania programu i muszą używać domyślnej strony kodowej systemu Windows ANSI (ACP): __argv, _acmdlni _pgmptr.

Wcześniej ta obsługa, mbrtoc16, , c16rtombmbrtoc32i c32rtomb istniała do tłumaczenia między wąskimi ciągami UTF-8, UTF-16 (takie samo kodowanie jak wchar_t na platformach Windows) i UTF-32. Ze względów zgodności te interfejsy API nadal tłumaczą się tylko na protokół UTF-8, a nie na stronę kodową ustawioną za pomocą polecenia setlocale.

Aby użyć tej funkcji w systemie operacyjnym przed systemem Windows 10, należy użyć wdrożenia lokalnego aplikacji lub linku statycznie przy użyciu wersji 1803 (10.0.17134.0) zestawu Windows SDK lub nowszej wersji. W przypadku systemów operacyjnych Windows 10 wcześniejszych niż 1803 (10.0.17134.0) obsługiwane jest tylko łączenie statyczne.

Wymagania

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład

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

Zobacz też

Nazwy ustawień regionalnych, języki i ciągi kraj/region
_configthreadlocale
_create_locale, _wcreate_locale
ustawienia regionalne
localeconv
_mbclen, , mblen_mblen_l
strlen, , wcslen, _mbslen, _mbslen_l, , _mbstrlen_mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
strcoll, funkcje
strftime, , wcsftime, , _strftime_l_wcsftime_l
strxfrm, , wcsxfrm, , _strxfrm_l_wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l