setlocale, _wsetlocale

Artikel
06/09/2015

Legt das Laufzeitgebietsschema fest oder ruft es ab.

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 locale oder category ungültig ist, wird ein NULL-Zeiger zurückgegeben und die aktuellen Gebietsschemaeinstellungen des Programms werden nicht geändert.

Beispiel: 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 locale auf „Chinesisch“ festlegen, kann der Rückgabewert entweder „Chinesisch-vereinfacht“ oder „Chinesisch-traditionell“ 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.

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:

LC_ALL
Alle Kategorien in der folgenden Liste:
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. Neben dem Dezimaltrennzeichen legt LC_NUMERIC auch das Tausendertrennzeichen und die Zeichenfolge für gruppierte Steuerelemente fest, die von localeconv zurückgegeben werden.
LC_TIME
Die Funktionen strftime und wcsftime.

Diese Funktion überprüft den Kategorienparameter. Wenn es sich bei dem Kategorienparameter um keinen der Werte handelt, die in der vorherigen Tabelle angegeben sind, wird der Handler für ungültige Parameter aufgerufen, wie in Parametervalidierung 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 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 Codepages umfasst alle diejenigen, die von der Windows NLS API unterstützt werden, ausgenommen Codepages, die mehr als zwei Bytes pro Zeichen benötigen, wie z. B. UTF-7 und UTF-8. Wenn Sie eine Codepage-Wert wie UTF-7 oder UTF-8 bereitstellen, schlägt setlocale fehl und gibt NULL zurück. Der von setlocale unterstützte Satz von Gebietsschemanamen wird in Gebietsschema-Namen, Sprachen und Zeichenfolgen für Länder und Regionen 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

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. Jede der Zeichenfolgen „.OCP" und „.ACP" kann anstelle einer Codepageseitenzahl verwendet werden, um jeweils die voreingestellte OEM-Benutzercodepage und die voreingestellte ANSI-Benutzercodepage anzugeben.

setlocale( LC_ALL, "" );
Legt das Gebietsschema auf den Standardwert fest, der die vom Betriebssystem abgerufene voreingestellte ANSI-Benutzercodepage ist.
setlocale( LC_ALL, ".OCP" );
Legt das Gebietsschema explizit auf die aktuelle vom Betriebssystem abgerufene voreingestellte OEM-Benutzercodepage fest.
setlocale( LC_ALL, ".ACP" );
Legt das Gebietsschema auf die vom Betriebssystem abgerufene voreingestellte ANSI-Benutzercodepage fest.
setlocale( LC_ALL, "<localename>" );
Legt das Gebietsschema auf den Gebietsschemanamen fest, der durch <localename> angegeben wird.
setlocale( LC_ALL, "<language>_<country>" );
Legt das Gebietsschema auf die Sprache und das Land/die Region fest, die durch <language> und <country> angegeben sind, und zwar zusammen mit der vom Hostbetriebssystem abgerufene Standardcodepage.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );
Legt das Gebietsschema auf die Sprache, das Land/die Region und die Codepage fest, die bzw. das durch die Zeichenfolgen <language>, <country> und <code_page> 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 von <language> angegeben wird, und verwendet das Standardland bzw. die Standardregion für die angegebene Sprache sowie die vom Hostbetriebssystem abgerufene voreingestellte ANSI-Benutzercodepage für das Land/die Region. 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 Wert fest, der durch <code_page> angegeben ist, wobei zugleich das Standardland bzw. die Standardregion und Sprache (gemäß der Definition vom Hostbetriebssystem) für die angegebene Codepage verwendet wird.

Die Kategorie muss entweder LC_ALL oder LC_CTYPE sein, um eine Codepageänderung zu bewirken. Wenn z. B. das Standardland bzw. die Standardregion und die Sprache des Hostbetriebssystems "USA" und "Englisch" sind, sind die folgenden beiden Aufrufe von setlocale funktional äquivalent:

setlocale( LC_ALL, ".1252" );

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

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

Mit der Funktion _configthreadlocale wird gesteuert, ob setlocale das Gebietsschema aller Threads in einem Programm betrifft oder nur das Gebietsschema des aufrufenden Threads.

Anforderungen

Routine	Erforderlicher Header
setlocale	<locale.h>
_wsetlocale	<locale.h> oder <wchar.h>

Zusätzliche Informationen zur Kompatibilität finden Sie unter Kompatibilität in der Einführung.

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

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