setlocale, _wsetlocale

Festlegen oder Abrufen des Laufzeitgebietsschemas.

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ültiger locale und category angegebener Wert angegeben wird, geben die Funktionen einen Zeiger auf die Zeichenfolge zurück, die der angegebenen und categoryzugeordneten locale Zeichenfolge zugeordnet ist. Wenn das locale Argument lautet NULL, geben die Funktionen das aktuelle Gebietsschema zurück.

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

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

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

Mapping generischer Textroutinen

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:

Diese Funktion überprüft den Kategorienparameter. Wenn der Kategorieparameter keiner der In der vorherigen Tabelle angegebenen Werte 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.

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 Zeichenfolgen für Land/Region. 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 Codeseiten enthalten alle gebietsschemanamen, die von der Windows NLS-API unterstützt werden. Der Satz der unterstützten Gebietsschemanamen setlocale wird in Gebietsschemanamen, Sprachen und Zeichenfolgen für Land/Region beschrieben. Die von ihnen unterstützten setlocale Sprachen- und Länder-/Regionszeichenfolgen werden in sprachenspezifischen Zeichenfolgen und Zeichenfolgen für Land/Region 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 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 Codeseitenzahl verwendet werden, um die Verwendung der standardmäßigen OEM-Codeseite 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 Gebietsschemanamen des Benutzers 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 Gebietsschemanamen des Benutzers festgelegt.GetLocaleInfoEx

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

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

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

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

• 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>, <country>und <code_page> Zeichenfolgen angegeben wird. 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 angegeben <language>ist, und verwendet das Standardland/die Standardregion für die angegebene Sprache und die benutzerbasierte 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/der Standardland/Region (wie vom Hostbetriebssystem definiert) für die angegebene Codepage 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" lautet, sind die folgenden beiden Aufrufe setlocale 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 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. Verwenden Sie ".UTF8" zum Aktivieren des UTF-8-Modus bei Verwendung setlocaleals Codepage. Verwendet z setlocale(LC_ALL, ".UTF8") . B. die aktuelle Windows ANSI-Codepage (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 Codepageteil des Gebietsschemanamens befinden, muss also wie in den folgenden Beispielen einen vorangestellten Punkt (.) aufweisen: "en_US.UTF8"".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"

Nach dem Aufrufen setlocale(LC_ALL, ".UTF8")können Sie "😊" mbtowcs übergeben und ordnungsgemäß in eine wchar_t Zeichenfolge übersetzt werden. Zuvor gab es keine Gebietsschemaeinstellung, die für diese Übersetzung verfügbar war.

Der UTF-8-Modus ist auch für Funktionen aktiviert, die historisch übersetzte char Zeichenfolgen mit der Standardmäßigen Windows ANSI-Codeseite (ACP) aufweisen. Wenn Sie z. B. eine UTF-8-Codeseite verwenden, _mkdir("😊") wird beispielsweise ein Verzeichnis mit diesem Emoji als Ordnername erstellt, 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. Aus Kompatibilitätsgründen wird der ACP weiterhin verwendet, wenn die C-Gebietsschema-Codeseite 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 Standardmäßige Windows ANSI-Codeseite (ACP) verwenden müssen: __argv, , _acmdlnund _pgmptr.

Vor dieser Unterstützungmbrtoc16, , , mbrtoc32c16rtombund c32rtomb es existierte, um zwischen UTF-8 schmalen Zeichenfolgen zu übersetzen, UTF-16 (die gleiche Codierung wie wchar_t auf Windows-Plattformen) und UTF-32. Aus Kompatibilitätsgründen übersetzen diese APIs immer noch nur in UTF-8 und nicht in die Codepage, die über setlocale.

Um dieses Feature auf einem Betriebssystem 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 verwenden. Für Windows 10-Betriebssysteme vor 1803 (10.0.17134.0) wird nur statische Verknüpfungen unterstützt.

Anforderungen

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

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

Siehe auch

Gebietsschemanamen, Sprachen und Zeichenfolgen für Land/Region
_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