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 locale und category gültig sind, wird ein Zeiger auf die Zeichenfolge zurückgegeben, die den angegebenen Werten für locale und category zugeordnet ist.

Wenn der locale ungültige Parameterhandler aufgerufen wird oder category nicht gültig ist, wird der ungültige Parameterhandler aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, legt die Funktion errno auf EINVAL fest und gibt NULL zurück.

Der Anruf

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 z. B. auf "chinese" den Rückgabewert festlegenlocale, kann es sich um einen "chinese-simplified" oder "chinese-traditional"einen .

_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. Wie Sie dies ändern, erfahren Sie unter Globaler Status in der CRT.

Zuordnung generischer Textroutinen

TCHAR.H Routine _UNICODE&_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:

Kategoriekennzeichnung 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 Dezimaltrennzeichen für die formatierten Ausgaberoutinen (wie printf), für die Datenkonvertierungsroutinen und für die nicht monetären Formatierungsinformationen, die von localeconv zurückgegeben werden. Legt zusätzlich zum Dezimalzeichen das Tausendertrennzeichen und die gruppierende Steuerelementzeichenfolge fest, LC_NUMERIC die von localeconv.
LC_TIME Die Funktionen strftime und wcsftime.

Diese Funktion überprüft den Kategorienparameter. Wenn der Kategorieparameter nicht einer der Werte ist, die in der vorherigen Tabelle angegeben sind, wird der ungültige Parameterhandler aufgerufen, wie in der 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 über das Format des locale-Arguments finden Sie unter Gebietsschema-Namen, Sprachen und Zeichenfolgen für Länder und Regionen. 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. Der Satz verfügbarer Gebietsschemanamen, Sprachen, Länder-/Regionscodes und Codeseiten enthält alle vom Windows NLS-API unterstützten. Der Satz von Gebietsschemanamen, die von setlocale unterstützt werden, wird in Gebietsschemanamen, Sprachen und Länder-/Region-Zeichenfolgen beschrieben. Der von setlocale unterstützte Satz von Sprach- und Länder-/Regionszeichenfolgen ist in Sprachzeichenfolgen und Länder-/Regionszeichenfolgen 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 Codeseitennummer verwendet werden, um die Verwendung der standardmäßigen OEM-Codeseite des Benutzers und der standardmäßigen ANSI-Codeseite 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 GetUserDefaultLocaleName. Die Codeseite wird auf den von GetACP.

  • setlocale( LC_ALL, ".OCP" );

    Legt das Gebietsschema auf die aktuelle OEM-Codeseite fest, die vom Betriebssystem abgerufen wird. Der Gebietsschemaname wird auf den von GetUserDefaultLocaleName. Die Codeseite wird auf den Wert für den LOCALE_IDEFAULTCODEPAGE vom Benutzer standardmäßigen Gebietsschemanamen festgelegt.GetLocaleInfoEx

  • setlocale( LC_ALL, ".ACP" );

    Legt das Gebietsschema auf die vom Betriebssystem abgerufene voreingestellte ANSI-Benutzercodepage fest. Der Gebietsschemaname wird auf den von GetUserDefaultLocaleName. Die Codeseite wird auf den Wert für den LOCALE_IDEFAULTANSICODEPAGE vom Benutzer standardmäßigen Gebietsschemanamen festgelegt.GetLocaleInfoEx

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

    Legt das Gebietsschema auf den Gebietsschemanamen fest, der von <localename>. Die Codeseite wird auf den Wert für den LOCALE_IDEFAULTANSICODEPAGE angegebenen Gebietsschemanamen festgelegt.GetLocaleInfoEx

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

    Legt das Gebietsschema auf die Sprache und region fest, die durch <language> und <country>, zusammen mit der Standardcodeseite, die vom Hostbetriebssystem abgerufen wurde. Die Codeseite wird auf den Wert für den LOCALE_IDEFAULTANSICODEPAGE angegebenen Gebietsschemanamen festgelegt.GetLocaleInfoEx

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

    Legt das Gebietsschema auf die Sprache, das Land/die Region und die Codeseite fest, die durch die <language>, <country>und <code_page> Zeichenfolgen angegeben ist. 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 ist, und verwendet das Standardland/die Standardregion für die angegebene Sprache und die Benutzerstandard-ANSI-Codeseite für dieses Land/diese Region, wie vom Hostbetriebssystem abgerufen. 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 Codeseite auf den wert fest, der durch <code_page>, zusammen mit dem standardland/region und der Sprache (wie vom Hostbetriebssystem definiert) für die angegebene Codeseite angegeben wird.

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

setlocale( LC_ALL, ".1252" );

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

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

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

UTF-8-Support

Ab Windows 10 Version 1803 (10.0.17134.0) unterstützt die universelle C-Runtime die Verwendung einer UTF-8-Codeseite. Dies bedeutet, dass Zeichenfolgen, die an C-Laufzeitfunktionen übergeben werden, char Zeichenfolgen in der UTF-8-Codierung erwarten. Verwenden Sie ".UTF8" zum Aktivieren des UTF-8-Modus bei Verwendung setlocaleder Codeseite. Verwenden Sie beispielsweise setlocale(LC_ALL, ".UTF8") die aktuelle Standard-Windows ANSI-Codeseite (ACP) für das Gebietsschema und UTF-8 für die Codeseite.

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

  • Groß-/Kleinschreibung muss nicht beachtet werden.
  • der Bindestrich (-) ist optional
  • Er muss sich im Codeseitenteil des Gebietsschemanamens befinden, muss also wie in den folgenden Beispielen einen vorangestellten Punkt (.) aufweisen: "en_US.UTF8"".utf8"

Die folgenden Beispiele zeigen, wie Sie die UTF-8-Zeichenfolge angeben:

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

Nach dem Aufrufen setlocale(LC_ALL, ".UTF8")können Sie "😊" mbtowcs übergeben und ordnungsgemäß in eine wchar_t Zeichenfolge übersetzt werden, während zuvor keine Gebietsschemaeinstellung verfügbar war, um dies zu tun.

UTF-8-Modus ist auch für Funktionen aktiviert, die historisch übersetzte char Zeichenfolgen mit der Standard-Windows ANSI-Codeseite (ACP) haben. Wenn Sie beispielsweise eine UTF-8-Codeseite verwenden, _mkdir("😊") wird ein Verzeichnis mit diesem Emoji als Ordnername korrekt erzeugt, anstatt dass der ACP vor dem Ausführen des Programms in UTF-8 geändert werden muss. Ebenso gibt das Aufrufen _getcwd() in diesem Ordner eine UTF-8-codierte Zeichenfolge zurück. Zur Kompatibilität wird der ACP weiterhin verwendet, wenn die C-Gebietsschemacodeseite 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 sind und die Standard-Windows ANSI-Codeseite (ACP) verwenden müssen: __argv, _acmdlnund _pgmptr.

Vor dieser Unterstützung, mbrtoc16, mbrtoc32c16rtombund c32rtomb vorhanden, um zwischen UTF-8 schmalen Zeichenfolgen, UTF-16 (dieselbe Codierung wie wchar_t auf Windows Plattformen) und UTF-32 zu übersetzen. Aus Kompatibilitätsgründen übersetzen diese APIs weiterhin nur in UTF-8 und nicht aus dem Codeseitensatz über setlocale.

Um dieses Feature vor Windows 10 zu verwenden, müssen Sie die app-lokale Bereitstellung oder den Link statisch mit Version 1803 (10.0.17134.0) des Windows SDK oder höher verknüpfen. Für Windows 10 Betriebssysteme 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'

Siehe auch

Gebietsschemanamen, Sprachen und Länder/Region-Zeichenfolgen
_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