setlocale, _wsetlocale

Článek
06/09/2015

Nastaví nebo načte národní prostředí runtime.

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

Parametry

category
Kategorie ovlivněná národním prostředím
locale
Specifikátor národního prostředí

Vrácená hodnota

Pokud jsou zadány platné argumenty locale a category, vrátí ukazatel na řetězec přidružený k zadanému argumentu locale a category.Pokud není platný argument locale nebo category, vrátí ukazatel s hodnotou null a aktuální nastavení národního prostředí programu se nezmění.

Například volání

setlocale( LC_ALL, "en-US" );

nastaví všechny kategorie, aby vracely pouze řetězec

en-US

Chcete-li obnovit tuto část informací o národním prostředí programu, můžete zkopírovat řetězec vrácený funkcí setlocale.Pro řetězec vrácený funkcí setlocale se používá globální úložiště nebo místní úložiště vláken.Pozdější volání funkce setlocale řetězec přepíšou, což způsobí neplatnost ukazatelů na řetězec vrácených dřívějšími voláními.

Poznámky

Funkce setlocale slouží k nastavení některých nebo všech informací o národním prostředí aktuálního programu zadaných pomocí parametrů locale a category, k jejich změně nebo dotazu na ně.locale odkazuje na místo (země/oblast a jazyk), kterému můžete přizpůsobit některé aspekty programu.Ke kategoriím závislým na národním prostředí patří formátování dat nebo zobrazovací formát pro peněžní hodnoty.Nastavíte-li locale na výchozí řetězec pro jazyk, u kterého počítač podporuje více forem, je vhodné zkontrolovat návratovou hodnotu setlocale a zjistit tak aktuálně platný jazyk.Když například nastavíte parametr locale na „čínština“, vrácená hodnota může být buď „čínština (zjednodušená)“, nebo „čínština (tradiční)“.

_wsetlocale je širokoznaková verze funkce setlocale, argument locale a návratová hodnota funkce _wsetlocale jsou širokoznakové řetězce.Funkce _wsetlocale a setlocale se jinak chovají stejně.

Mapování rutin obecného textu

Rutina TCHAR.H	_UNICODE a _MBCS nejsou definovány	_MBCS definováno	_UNICODE definováno
_tsetlocale	setlocale	setlocale	_wsetlocale

Argument category určuje ovlivněné části informací o národním prostředí programu.Makra použitá pro argument category a části programu, které ovlivňují, jsou následující:

LC_ALL
Všechny kategorie z následujícího seznamu.
LC_COLLATE
Funkce strcoll, _stricoll, wcscoll, _wcsicoll, strxfrm, _strncoll, _strnicoll, _wcsncoll, _wcsnicoll a wcsxfrm
LC_CTYPE
Funkce pro zpracování znaků (s výjimkou isdigit, isxdigit, mbstowcs a mbtowc, které nejsou ovlivněny)
LC_MONETARY
Informace o formátování měny vracené funkcí localeconv
LC_NUMERIC
Znak desetinné čárky pro rutiny pro formátování výstupu (jako například printf), pro rutiny pro převod datumů a pro informace nefinančního formátování vracené funkcí localeconv.Kromě znaku desetinné čárky argument LC_NUMERIC nastaví také oddělovač tisíců a řetězec řídící seskupování vracený funkcí localeconv.
LC_TIME
Funkce strftime a wcsftime

Tato funkce ověřuje parametr kategorie.Pokud parametr kategorie není jedna z hodnot uvedených v předchozí tabulce, je vyvolána obslužná rutina neplatného parametru, jak je popsáno v části Ověření parametru.Pokud provádění může pokračovat, funkce nastaví proměnnou errno na EINVAL a vrátí NULL.

Argument locale je ukazatel na řetězec, který určuje národní prostředí.Informace o formátu argumentu locale naleznete v tématu Řetězce s názvy národních prostředí, jazyků a zemí/oblastí.Pokud argument locale odkazuje na prázdný řetězec, je národní prostředí definováno implementací nativního prostředí.Hodnota C určuje minimální prostředí vyhovující standardu ANSI pro překlad C.Národní prostředí C předpokládá, že všechny datové typy char mají 1 bajt a jejich hodnota je vždy menší než 256.

Při spuštění programu se spustí ekvivalent následujícího příkazu:

setlocale( LC_ALL, "C" );

Argument locale přijímá název národního prostředí, řetězec jazyka, řetězec jazyka a kód země nebo oblasti, znakovou stránku nebo řetězec jazyka, kód země/oblasti a znakovou stránku.Sada dostupných názvů národního prostředí, jazyků, kódů země/oblasti a znakových stránek obsahuje všechny prvky, které jsou podporovány v rozhraní API Windows NLS, kromě znakových stránek, které vyžadují více než dva bajty na znak, například UTF-7 a UTF-8.Pokud zadáte znakovou stránku jako UTF-7 nebo UTF-8, funkce setlocale selže a vrátí hodnotu NULL.Sada názvů národních prostředí podporovaných funkcí setlocale je popsána v části Řetězce s názvy národních prostředí, jazyků a zemí/oblastí.Sada řetězců jazyka a země/oblasti, které jsou podporovány funkcí setlocale, je uvedena v tématech Řetězce jazyků a Řetězce zemí/oblastí.Doporučujeme, abyste s ohledem na výkon a údržbu řetězců národního prostředí formu národního prostředí integrovali do kódu nebo serializovali do úložiště.U řetězců názvu národního prostředí je méně pravděpodobné, že aktualizací operačního systému dojde k jejich změně, než v případě formy pro název jazyka a země či oblasti.

Ukazatel s hodnotou null, který je předán jako argument locale, určuje, že funkce setlocale odešle dotaz namísto nastavení mezinárodního prostředí.Pokud je argument locale ukazatel s hodnotou null, aktuální nastavení národního prostředí programu se nemění.Místo toho vrací funkce setlocale ukazatel na řetězec, který je přidružen k argumentu category aktuálního národního prostředí daného vlákna.Pokud je argument categoryLC_ALL, vrátí funkce řetězec označující aktuální nastavení všech kategorií, které jsou odděleny středníky.Například sekvence volání

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

vrací

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

což je řetězec, který je přidružen ke kategorii LC_ALL.

Následující příklady se týkají kategorie LC_ALL.Každý z řetězců .OCP a .AKT lze použít místo čísla znakové stránky a určit tak výchozí znakovou stránku OEM nebo případně výchozí znakovou stránku ANSI pro uživatele.

setlocale( LC_ALL, "" );
Nastaví národní prostředí na výchozí hodnotu, což je výchozí znaková stránka ANSI pro uživatele získaná z operačního systému.
setlocale( LC_ALL, ".OCP" );
Explicitně nastaví národní prostředí na aktuální znakovou stránku OEM získanou z operačního systému.
setlocale( LC_ALL, ".ACP" );
Nastaví národní prostředí na znakovou stránku ANSI získanou z operačního systému.
setlocale( LC_ALL, "<localename>" );
Nastaví národní prostředí na název národního prostředí uvedený v <localename>.
setlocale( LC_ALL, "<language>_<country>" );
Nastaví národní prostředí na jazyk a zemi/oblast uvedené v <language> a <country> pomocí výchozí znakové stránky získané z hostitelského operačního systému.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );
Nastaví národní prostředí, zemi/oblast a znakovou stránku určené řetězci <language>, <country> a <code_page>.Můžete použít různé kombinace jazyka, země/oblasti a znakové stránky.Například toto volání nastaví národní prostředí na hodnotu francouzština, Kanada se znakovou stránkou 1252:

setlocale( LC_ALL, "French_Canada.1252" );

Toto volání nastaví národní prostředí na hodnotu francouzština, Kanada s výchozí znakovou stránkou ANSI:

setlocale( LC_ALL, "French_Canada.ACP" );

Toto volání nastaví národní prostředí na hodnotu francouzština, Kanada s výchozí znakovou stránkou OEM:

setlocale( LC_ALL, "French_Canada.OCP" );
setlocale( LC_ALL, "<language>" );
Nastaví národní prostředí na jazyk uvedený v <language> a použije výchozí zemi/oblast pro zadaný jazyk a výchozí znakovou stránku ANSI uživatele pro zemi/oblast získanou z hostitelského operačního systému.Například následující volání setlocale jsou funkčně ekvivalentní:

setlocale( LC_ALL, "en-US" );

setlocale( LC_ALL, "English" );

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

S ohledem na výkon a údržbu doporučujeme použít první z uvedených forem.
setlocale( LC_ALL, ".<code_page>" );
Nastaví znakovou stránku na hodnotu určenou v <code_page> pomocí výchozí země/oblasti a jazyka (jak jsou uvedeny v hostujícím operačním systému) pro zadanou znakovou stránku.

Má-li se provést změna znakové stránky, musí být kategorie buď LC_ALL, nebo LC_CTYPE.Pokud jsou například výchozí země/oblast a jazyk hostitelského operačního systému „USA“ a „angličtina“, jsou následující dvě volání setlocale funkčně ekvivalentní:

setlocale( LC_ALL, ".1252" );

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

Další informace naleznete v direktivě pragma setlocale v tématu C/C++ – referenční dokumentace preprocesoru.

Funkce _configthreadlocale se používá k řízení, zda má funkce setlocale ovlivňovat národní prostředí všech vláken v rámci programu nebo pouze národní prostředí volajícího vlákna.

Požadavky

Rutina	Požadovaný hlavičkový soubor
setlocale	<locale.h>
_wsetlocale	<locale.h> nebo <wchar.h>

Další informace o kompatibilitě naleznete v úvodu tématu Kompatibilita.

Příklad

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