setlocale, _wsetlocale

Legt das Laufzeitgebietsschema fest oder ruft es ab.

Syntax

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

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

Parameter

category
Vom Gebietsschema betroffene Kategorie.

locale
Gebietsschemaspezifizierer.

Rückgabewert

Wenn ein gültiges locale und category angegeben ist, geben die Funktionen einen Zeiger auf die Zeichenfolge zurück, die dem angegebenen locale und categoryzugeordnet ist. Wenn das locale Argument lautet NULL, geben die Funktionen das aktuelle Gebietsschema zurück.

Wenn ein ungültiges Argument an eine Funktion übergeben wird, lautet NULLder Rückgabewert . Das Verhalten für ungültige Argumente lautet wie folgt:

Funktion	Ungültiger Parameter	Ungültiger Handler wird aufgerufen, wie unter Parameterüberprüfung beschrieben	Legt errno
setlocale	category	ja	ja
setlocale	locale	nein	nein
_wsetlocale	category	ja	ja
_wsetlocale	locale	nein	nein

Der Aufruf

setlocale( LC_ALL, "en-US" );

legt alle Kategorien fest und gibt nur folgende Zeichenfolge zurück

en-US

Sie können die von setlocale zurückgegebene Zeichenfolge kopieren, um diesen Teil der Gebietsschemainformation des Programms wiederherzustellen. Lokaler globaler Speicher oder lokaler Threadspeicher wird für die von setlocale zurückgegebene Zeichenfolge verwendet. Spätere Aufrufe von setlocale überschreiben die Zeichenfolge, sodass die von früheren Aufrufen zurückgegebenen Zeichenfolgenzeiger nicht mehr gültig sind.

Hinweise

Verwenden Sie die Funktion setlocale, um einige oder alle Gebietsschemainformationen des aktuellen Programms festzulegen, zu ändern oder abzufragen, die von locale und category angegeben sind. locale verweist auf den Ort (Land/Region und Sprache), für den Sie bestimmte Aspekte des Programms anpassen können. Vom Gebietsschema abhängig sind u. a. Datumsformat und Währungsformat. Wenn Sie locale auf die Standardzeichenfolge für eine Sprache festlegen, zu der auf dem Computer mehrere Formen unterstützt werden, sollten Sie den setlocale-Rückgabewert überprüfen, um festzustellen, welche Sprache wirksam ist. Wenn Sie beispielsweise auf "chinese" den Rückgabewert festlegenlocale, könnte entweder "chinese-simplified" oder "chinese-traditional"sein.

_wsetlocale ist eine Breitzeichenversion von setlocale. Das Argument locale und der Rückgabewert von _wsetlocale sind Zeichenfolgen mit Breitzeichen. _wsetlocale und setlocale verhalten sich andernfalls identisch.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Informationen zum Ändern dieses Verhaltens finden Sie unter Globaler Zustand im CRT.

Generische Textroutinenzuordnungen

TCHAR.H Routine	_UNICODE und _MBCS nicht definiert	_MBCS Definiert	_UNICODE Definiert
_tsetlocale	setlocale	setlocale	_wsetlocale

Das category-Argument gibt die Teile der Gebietsschemainformationen eines Programms an, die betroffen sind. Die für category verwendeten Makros und die betroffenen Teile des Programms sind die folgenden:

category -Flag	Betrifft
LC_ALL	Alle unten aufgeführten Kategorien.
LC_COLLATE	Die Funktionen strcoll, _stricoll, wcscoll, _wcsicoll, strxfrm, _strncoll, _strnicoll, _wcsncoll, _wcsnicoll und wcsxfrm.
LC_CTYPE	Die Funktionen zur Zeichenbehandlung (außer isdigit, isxdigit, mbstowcs und mbtowc, die nicht betroffen sind).
LC_MONETARY	Durch die localeconv-Funktion zurückgegebene Informationen zur Währungsformatierung.
LC_NUMERIC	Dezimalzeichen für die formatierten Ausgaberoutinen (z printf. B. ), für die Datenkonvertierungsroutinen und für die nichtmonetären Formatierungsinformationen, die von zurückgegeben werden localeconv. Legt zusätzlich zum Dezimalzeichen das Tausendertrennzeichen und die gruppierende Steuerelementzeichenfolge fest, LC_NUMERIC die von zurückgegeben wird localeconv.
LC_TIME	Die Funktionen strftime und wcsftime.

Diese Funktion überprüft den Kategorienparameter. Wenn der Category-Parameter nicht einer der in der vorherigen Tabelle angegebenen Werte ist, wird der Handler für ungültige Parameter aufgerufen, wie unter Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, legt die Funktion errno auf EINVAL fest und gibt NULL zurück.

Das locale-Argument ist ein Zeiger auf eine Zeichenfolge, die das Gebietsschema angibt. Informationen zum Format des locale Arguments finden Sie unter Gebietsschemanamen, Sprachen und Länder-/Region-Zeichenfolgen. Wenn locale auf eine leere Zeichenfolge zeigt, ist das Gebietsschema die durch die Implementierung definierte systemeigene Umgebung. Ein Wert von C gibt die Umgebung mit minimaler ANSI-Konformität für die C-Übersetzung an. Das C-Gebietsschema setzt als gegeben voraus, dass alle char-Datentypen 1 Byte groß sind und ihr Wert immer kleiner als 256 ist.

Zum Programmstart wird die Entsprechung der folgenden Anweisung ausgeführt:

setlocale( LC_ALL, "C" );

Das locale-Argument kann einen Gebietsschemanamen annehmen, eine Sprachenzeichenfolge, eine Sprachenzeichenfolge und eine Landeskennzahl, eine Codepage oder eine Sprachenzeichenfolge, eine Landeskennzahl eine und Codepage. Die verfügbaren Gebietsschemanamen, Sprachen, Länder-/Regionscodes und Codepages enthalten alle von der Windows NLS-API unterstützten Gebietsschemanamen. Der Satz der von setlocale unterstützten Gebietsschemanamen wird in Gebietsschemanamen, Sprachen und Länder-/Region-Zeichenfolgen beschrieben. Die von unterstützten setlocale Sprach- und Länder-/Regionszeichenfolgen werden unter Sprachzeichenfolgen und Länder-/Region-Zeichenfolgen aufgeführt. Wie empfehlen die Gebietsschema-Namensform aus Gründen der Leistung und leichteren Verwaltung von Gebietsschema-Zeichenfolgen, die in Code eingebettet sind oder für den Speicher serialisiert sind. Es ist weniger wahrscheinlich, dass Gebietsschema-Zeichenfolgen durch eine Betriebssystemaktualisierung geändert werden, als dies bei der Namensform für Sprache und Land/Region der Fall ist.

Eine als das locale-Argument übergebener NULL-Zeiger teilt setlocale mit, die internationale Umgebung abzufragen, anstatt sie festzulegen. Wenn das locale Argument ein NULL-Zeiger ist, wird die aktuelle Gebietsschemaeinstellung des Programms nicht geändert. Stattdessen gibt setlocale ein Zeiger zur Zeichenfolge zurück, die der category des aktuellen Gebietsschemas des Threads zugeordnet ist. Wenn das category-Argument LC_ALL ist, gibt die Funktion eine Zeichenfolge zurück, die durch Semikolons getrennt die aktuelle Einstellung der einzelnen Kategorien angibt. Beispiel: Die Reihenfolge der Aufrufe

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

gibt Folgendes zurück:

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

zurück, welches die Zeichenfolge ist, die der Kategorie LC_ALL zugeordnet ist.

Die folgenden Beispiele gehören zur LC_ALL-Kategorie. Eine der Zeichenfolgen ". OCP" und ". ACP" kann anstelle einer Codepagenummer verwendet werden, um die Verwendung der benutzerseitig standardmäßigen OEM-Codepage und der BENUTZERstandard-ANSI-Codepage für diesen Gebietsschemanamen anzugeben.

• setlocale( LC_ALL, "" );

  Legt das Gebietsschema auf den Standardwert fest, der die vom Betriebssystem abgerufene voreingestellte ANSI-Benutzercodepage ist. Der Gebietsschemaname wird auf den von GetUserDefaultLocaleNamezurückgegebenen Wert festgelegt. Die Codepage ist auf den von GetACPzurückgegebenen Wert festgelegt.

• setlocale( LC_ALL, ".OCP" );

  Legt das Gebietsschema auf die aktuelle OEM-Codepage fest, die vom Betriebssystem abgerufen wurde. Der Gebietsschemaname wird auf den von GetUserDefaultLocaleNamezurückgegebenen Wert festgelegt. Die Codepage wird auf den LOCALE_IDEFAULTCODEPAGE Wert für den Benutzerstandardgebietsnamen von GetLocaleInfoExfestgelegt.

• setlocale( LC_ALL, ".ACP" );

  Legt das Gebietsschema auf die vom Betriebssystem abgerufene voreingestellte ANSI-Benutzercodepage fest. Der Gebietsschemaname wird auf den von GetUserDefaultLocaleNamezurückgegebenen Wert festgelegt. Die Codepage wird auf den LOCALE_IDEFAULTANSICODEPAGE Wert für den Benutzerstandardgebietsnamen von GetLocaleInfoExfestgelegt.

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

  Legt das Gebietsschema auf den Gebietsschemanamen fest, der durch angegeben wird <localename>. Die Codepage wird auf den LOCALE_IDEFAULTANSICODEPAGE Wert für den angegebenen Gebietsschemanamen durch GetLocaleInfoExfestgelegt.

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

  Legt das Gebietsschema auf die Sprache und das Land/die Region fest, die von <language> und <country>angegeben sind, zusammen mit der vom Hostbetriebssystem abgerufenen Standardcodepage. Die Codepage wird auf den LOCALE_IDEFAULTANSICODEPAGE Wert für den angegebenen Gebietsschemanamen durch GetLocaleInfoExfestgelegt.

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

  Legt das Gebietsschema auf die Sprache, das Land/die Region und die Codepage fest, die durch die <language>Zeichenfolgen , <country>und <code_page> angegeben sind. Sie können verschiedene Kombinationen von Sprache, Land/Region und Codepage verwenden. Bei diesem Aufruf wird beispielsweise das Gebetsschema auf Französisch (Kanada) festgelegt, mit der Codepage 1252:

  setlocale( LC_ALL, "French_Canada.1252" );

  Bei diesem Aufruf wird das Gebietsschema auf Französisch (Kanada) mit der voreingestellten ANSI-Codepage festgelegt:

  setlocale( LC_ALL, "French_Canada.ACP" );

  Bei diesem Aufruf wird das Gebietsschema auf Französisch (Kanada) mit der voreingestellten OEM-Codepage festgelegt:

  setlocale( LC_ALL, "French_Canada.OCP" );

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

  Legt das Gebietsschema auf die Sprache fest, die durch <language>angegeben wird, und verwendet das Standardland/die Standardregion für die angegebene Sprache und die benutzerbasierte ANSI-Codepage für dieses Land/diese Region, die vom Hostbetriebssystem abgerufen wurden. Beispiel: Die folgenden Aufrufe von setlocale sind funktional äquivalent:

  setlocale( LC_ALL, "en-US" );

  setlocale( LC_ALL, "English" );

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

  Aus Leistungsgründen und wegen der Wartbarkeit wird die erste Form empfohlen.

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

  Legt die Codepage auf den von <code_page>angegebenen Wert fest, zusammen mit dem Standardland/der Standardsprache (wie vom Hostbetriebssystem definiert) für die angegebene Codepage.

Die Kategorie muss entweder LC_ALL oder LC_CTYPE sein, um eine Codepageänderung zu bewirken. Wenn beispielsweise das Land/die Region und die Standardsprache des Hostbetriebssystems "United States" und "English" sind, sind die folgenden beiden Aufrufe setlocale von funktional gleichwertig:

setlocale( LC_ALL, ".1252" );

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

Weitere Informationen finden Sie in der setlocale Pragma-Direktive in der C/C++-Präprozessorreferenz.

Die Funktion _configthreadlocale wird verwendet, um zu steuern, ob setlocale sich auf das Gebietsschema aller Threads in einem Programm oder nur auf das Gebietsschema des aufrufenden Threads auswirkt.

Unterstützung für UTF-8

Ab Windows 10 Version 1803 (10.0.17134.0) unterstützt die Universelle C-Runtime die Verwendung einer UTF-8-Codepage. Die Änderung bedeutet, dass Zeichenfolgen, die char an C-Laufzeitfunktionen übergeben werden, Zeichenfolgen in der UTF-8-Codierung erwarten können. Um den UTF-8-Modus zu aktivieren, verwenden Sie ".UTF8" als Codepage, wenn Sie verwenden setlocale. Verwendet beispielsweise setlocale(LC_ALL, ".UTF8") die aktuelle Windows ANSI-Standardcodepage (ACP) für das Gebietsschema und UTF-8 für die Codepage.

Die Zeichenfolge zum Angeben des UTF-8-Modus lautet:

• Groß-/Kleinschreibung muss nicht beachtet werden.
• der Bindestrich (-) ist optional
• Es muss sich im Codepageteil des Gebietsschemanamens befinden, daher muss eine Vorperiode (.) vorhanden sein, wie in den folgenden Beispielen: "en_US.UTF8" oder ".utf8"

Die folgenden Beispiele zeigen, wie die UTF-8-Zeichenfolge angegeben wird:

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

Nachdem Sie aufgerufen setlocale(LC_ALL, ".UTF8")haben, können Sie "😊" an mbtowcs übergeben, und es wird ordnungsgemäß in eine wchar_t Zeichenfolge übersetzt. Zuvor war für diese Übersetzung keine Gebietsschemaeinstellung verfügbar.

Der UTF-8-Modus ist auch für Funktionen aktiviert, die über historisch übersetzte char Zeichenfolgen verfügen, die die Standardmäßige Windows ANSI-Codepage (ACP) verwenden. Wenn Sie beispielsweise eine UTF-8-Codepage aufrufen _mkdir("😊") , wird ordnungsgemäß ein Verzeichnis mit diesem Emoji als Ordnername erzeugt, anstatt vor dem Ausführen des Programms das ACP-Format in UTF-8 zu ändern. Ebenso gibt das Aufrufen _getcwd() in diesem Ordner eine UTF-8-codierte Zeichenfolge zurück. Aus Gründen der Kompatibilität wird acp weiterhin verwendet, wenn die C-Gebietsschemacodepage nicht auf UTF-8 festgelegt ist.

Die folgenden Aspekte der C-Runtime können UTF-8 nicht verwenden, da sie während des Programmstarts festgelegt werden und die Standardmäßige Windows ANSI-Codepage (ACP) verwenden müssen: __argv, und _acmdln_pgmptr.

Vor dieser Unterstützung wurden mbrtoc16, mbrtoc32, c16rtombund c32rtomb für die Übersetzung zwischen utf-8 schmalen Zeichenfolgen, UTF-16 (gleiche Codierung wie wchar_t auf Windows-Plattformen) und UTF-32 verwendet. Aus Kompatibilitätsgründen übersetzen diese APIs immer noch nur in und aus UTF-8 und nicht die Codepage, die über festgelegt wurde setlocale.

Um dieses Feature auf einem Betriebssystem vor Windows 10 verwenden zu können, müssen Sie die lokale App-Bereitstellung verwenden oder statisch mit Version 1803 (10.0.17134.0) des Windows SDK oder höher verknüpfen. Bei Windows 10 Betriebssystemen vor 1803 (10.0.17134.0) wird nur statische Verknüpfungen unterstützt.

Anforderungen

-Routine zurückgegebener Wert	Erforderlicher Header
setlocale	<locale.h>
_wsetlocale	<locale.h> oder <wchar.h>

Weitere Informationen zur Kompatibilität finden Sie unter Compatibility.

Beispiel

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

Weitere Informationen

Gebietsschemanamen, Sprachen und Länder-/Regionszeichenfolgen
_configthreadlocale
_create_locale, _wcreate_locale
Gebietsschema
localeconv
_mbclen, mblen, _mblen_l
strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
strcoll Funktionen
strftime, wcsftime, _strftime_l, _wcsftime_l
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l