setlocale, _wsetlocale

Artykuł
06/09/2015

Ustawia lub pobiera ustawienia regionalne czasu wykonywania.

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 podane są prawidłowe locale i category, zwraca wskaźnik do ciągu skojarzonego z określonymi locale i category.Jeśli locale lub category są nieprawidłowe, zwraca pusty wskaźnik, a bieżące ustawienia regionalne programu nie są zmieniane.

Na przykład, wywołanie

setlocale( LC_ALL, "en-US" );

ustawia wszystkie kategorie, zwracając tylko ciąg

en-US

Można skopiować ciąg zwracany przez setlocale, aby przywrócić tę część informacji o ustawieniach regionalnych programu.Pamięć globalna lub lokalna wątku jest używana dla ciągu zwracanego przez setlocale.Późniejsze wywołania setlocale zastępują ten ciąg, co unieważnia wskaźniki ciągu zwracane przez poprzednie wywołania.

Uwagi

Użyj funkcji setlocale, aby ustawić, zmienić lub sprawdzić niektóre lub wszystkie z informacji o bieżących ustawieniach regionalnych programu, określonych przez locale i category.locale odnosi się do lokalizacji (kraj/region i język), dla której 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 na domyślny ciąg dla języka, który ma wiele form obsługiwanych na komputerze, należy sprawdzić wartość zwracaną przez setlocale, aby zobaczyć, który język jest aktualnie wykorzystywany.Na przykład, jeśli ustawisz locale na „chiński”, zwracana wartość może być „chiński uproszczony” lub „chiński tradycyjny”.

_wsetlocale jest dwubajtową wersją setlocale; argument locale i zwracana przez _wsetlocale wartość są ciągami znaków dwubajtowych._wsetlocale i setlocale zachowują się identycznie w innych przypadkach.

Mapowania procedur zwykłego tekstu

Procedura TCHAR.H	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowano
_tsetlocale	setlocale	setlocale	_wsetlocale

Argument category określa, które części informacji o ustawieniach regionalnych programu są kontrolowane.Makra używane do category i części programu, na które wpływają, to te poniżej:

LC_ALL
Wszystkie kategorie z poniższej listy.
LC_COLLATE
Funkcje strcoll, _stricoll, wcscoll, _wcsicoll, strxfrm, _strncoll, _strnicoll, _wcsncoll, _wcsnicoll i wcsxfrm.
LC_CTYPE
Funkcje obsługi znaków (z wyjątkiem isdigit, isxdigit, mbstowcs i mbtowc, które są bez zmian).
LC_MONETARY
Informacje o formatowaniu walutowym zwracane przez funkcję localeconv.
LC_NUMERIC
Znak dziesiętny dla sformatowanych procedur danych wyjściowych (takich jak printf), dla procedur konwersji danych i dla niepieniężnych informacji formatowania zwracanych przez localeconv.Oprócz znaku dziesiętnego, LC_NUMERIC ustawia również separator tysięcy i ciąg sterujący grupowaniem zwracany przez localeconv.
LC_TIME
Funkcje strftime i wcsftime.

Ta funkcja sprawdza poprawność parametru kategorii.Jeśli parametr kategorii nie jest jedną z wartości podanych w poprzedniej tabeli, wywoływany jest program obsługi nieprawidłowego parametru, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, funkcja ustawia errno na EINVAL i zwraca NULL.

Argument locale jest wskaźnikiem do ciągu, który określa ustawienia regionalne.Aby uzyskać informacje na temat formatu argumentu locale, zobacz Nazwy lokalne, języki i ciągi kraj/region.Jeśli locale wskazuje na pusty ciąg, ustawienia regionalne są natywnym środowiskiem, zdefiniowanym w implementacji.Wartość C określa minimalne środowisko dla translacji C, odpowiadające ANSI.Ustawienia regionalne C zakładają, że wszystkie typy danych char są jednobajtowe i 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 przyjąć 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ą.Zestaw dostępnych nazw ustawień regionalnych, języków, kodów krajów/regionów i stron kodowych zawiera wszystkie te opcje, które są obsługiwane przez API Windows NLS, z wyjątkiem stron kodowych, które wymagają więcej niż dwóch bajtów na znak, takich jak UTF-7 lub UTF-8.Jeżeli podasz wartość strony kodowej taką, jak UTF-7 lub UTF-8, setlocale zakończy się niepowodzeniem, zwracając wartość NULL.Zestaw nazw ustawień regionalnych obsługiwanych przez setlocale jest opisany w Nazwy lokalne, języki i ciągi kraj/region.Zestaw ciągów języka i kraju/regionu, obsługiwany przez setlocale jest wymieniony w Ciągi języka i Ciągi kraj/region.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.

Pusty wskaźnik przekazywany jako argument locale mówi setlocale, aby sprawdzić środowisko międzynarodowe zamiast je ustawiać.Jeśli argument locale jest pustym wskaźnikiem, bieżące ustawienia regionalne programu nie ulegną zmianie.Zamiast tego, setlocale zwraca wskaźnik do ciągu skojarzonego z category z bieżących ustawień regionalnych dla wątku.Jeśli argumentem category jest LC_ALL, funkcja zwraca ciąg, wskazujący bieżące ustawienie każdej kategorii, rozdzielonych ś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

który jest ciągiem znaków skojarzonym z kategorią LC_ALL.

Następujące przykłady odnoszą się do kategorii LC_ALL.Zamiast numeru strony kodowej można użyć jednego z ciągów „.OCP” lub „.ACP”, aby określić odpowiednio domyślną stronę kodową OEM użytkownika i domyślną stronę kodową ANSI użytkownika.

setlocale( LC_ALL, "" );
Ustawia ustawienia regionalne na domyślne, czyli domyślną stronę kodową ANSI użytkownika, uzyskaną z systemu operacyjnego.
setlocale( LC_ALL, ".OCP" );
Jawnie ustawia ustawienia regionalne na bieżącą stronę kodową OEM, uzyskaną od systemu operacyjnego.
setlocale( LC_ALL, ".ACP" );
Ustawia ustawienia regionalne na bieżącą stronę kodową ANSI, uzyskaną od systemu operacyjnego.
setlocale( LC_ALL, "<localename>" );
Ustawia ustawienia regionalne na nazwę ustawień, wskazaną przez <localename>.
setlocale( LC_ALL, "<language>_<country>" );
Ustawia ustawienia regionalne na język i kraj/region, wskazane przez <language> i <country>, wraz z domyślną stroną kodową uzyskaną od systemu operacyjnego hosta.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );
Ustawia ustawienia regionalne na język, kraj/region i stronę kodową wskazane przez ciągi <language>, <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, uzyskanych od systemu operacyjnego hosta.Na przykład, następujące wywołania setlocale są 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ę kodową 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.

Aby strona kodowa została zmieniona, kategoria musi być albo LC_ALL albo LC_CTYPE.Na przykład, jeśli 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 setlocale dyrektywa pragmy w Odwołania preprocesora języka C/C++.

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

Wymagania

Procedura	Wymagany nagłówek
setlocale	<locale.h>
_wsetlocale	<locale.h> lub <wchar.h>

Dodatkowe informacje o zgodności — zobacz: Zgodność we Wprowadzeniu.

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.
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];

    // Configure per-thread locale to cause all subsequently created 
    // threads to have their own locale.
    _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 );
}