setlocale _wsetlocale

發行項
03/26/2013

設定或擷取執行階段的地區設定。

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

參數

category
地區設定所影響的分類。
locale
地區設定規範。

傳回值

如果指定的 locale 和 category ，對字串的指標與指定的 locale 和 category的傳回。如果 locale 或 category 無效，則傳回 null 指標，則不會變更程式的目前地區設定。

例如，呼叫

setlocale( LC_ALL, "en-US" );

將所有分類，只傳回字串

en-US

您在後續的呼叫都可以使用 setlocale 所傳回的字串指標還原程式的地區設定資訊的部分，假設，您的程式無法修改指標或字串。對 setlocale 的後續呼叫覆寫字串，將先前有效之前不再傳回的字串指標。您可以使用 _strdup 儲存特定地區設定的字串複本。

備註

使用 setlocale 函式設定、變更，或查詢 locale 和 category所指定的部分或所有目前的地區設定資訊。 locale 會參考位置 (國家/地區和語言中) 可以自訂您的程式中的某些方面。有些與地區設定相關的類別含有日期格式和貨幣值的顯示格式。如果您對預設字串的集合 locale 與電腦上支援的多個表單，您的語言的應該檢查 setlocale 傳回碼看哪種語言生效。例如，使用「中文」可能會導致傳回值 chinese-simplified 或 chinese-traditional。

_wsetlocale 是 setlocale的寬字元版本; locale 引數和傳回值 _wsetlocale 是寬字元字串。 _wsetlocale 和 setlocale 其餘行為相同。

泛用文字常式對應

TCHAR.H 常式	未定義 _UNICODE & _MBCS	已定義 _MBCS	已定義 _UNICODE
_tsetlocale	setlocale	setlocale	_wsetlocale

category 引數指定受影響程式的地區設定資訊的一部分。用於 category 的巨集和它們會影響是程式的部分如下:

LC_ALL
所有分類，如下所列。
LC_COLLATE
strcoll、 _stricoll、 wcscoll、 _wcsicoll、 strxfrm、 _strncoll、 _strnicoll、 _wcsncoll、 _wcsnicoll和 wcsxfrm 函式。
LC_CTYPE
字元處理函式 (除了 isdigit、 isxdigit、 mbstowcs和 mbtowc，不會受到影響)。
LC_MONETARY
localeconv 函式傳回的貨幣格式資訊。
LC_NUMERIC
小數點的字元格式化輸出的常式 (例如 printf)，則資料轉換常式的和對於 localeconv傳回的非貨幣的格式化資訊。除了十進位點字元以外， LC_NUMERIC 也設定 localeconv和群組控制項字串傳回的千位分隔符號。
LC_TIME
strftime 和 wcsftime 函式。

這個函式驗證分類參數。如果分類參數不在上述資料表中指定的其中一個值，不正確的參數叫用處理常式，如參數驗證中所述。如果執行允許繼續，對 EINVAL 的函式會傳回 errno 和 NULL。

locale 引數是指向指定地區設定的字串。如需 locale 引數格式的詳細資訊，請參閱地區設定名稱、語言和國家/地區字串。如果為空字串或 locale 指向，地區設定是由實作環境決定原生環境。 C 的值為 C 轉譯指定最小的 ANSI 一致的環境。 C 地區設定，並假設所有 char 資料型別是 1 個位元組，而其值永遠小於 256。

在程式啟動時，下列陳述式的同等執行:

setlocale( LC_ALL, "C" );

locale 引數可能會將地區設定名稱、語言字串、語言字串和國家/地區碼、字碼頁或語言字串、國家/地區碼和字碼頁。可用的地區設定名稱、語言、國家/地區碼和字碼頁包含除了需要超過每個字元的兩個位元組，例如 UTF-7 及 UTF-8 的字碼頁的視窗 NLS 應用程式開發介面支援的項目。如果您提供像 UTF-7 或 UTF-8 的字碼頁，則 setlocale 將會失敗，則傳回 null。一組 setlocale 支援的地區設定名稱在地區設定名稱、語言和國家/地區字串中說明。一組語言和 setlocale 支援的國家/地區字串在語言字串和國家/地區字串中。

做為 locale 引數傳遞 NULL 指標呼叫 setlocale 查詢而非設定國際環境。如果 locale 引數為 null 指標，則不會變更程式的目前地區設定。相反地， setlocale 將指標傳回字串與執行緒的目前地區設定的 category 。如果 category 引數是 LC_ALL，函式會傳回表示每一個目前設定的字串分類，並以分號隔開。例如，呼叫的順序

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

傳回

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

哪些是字串與 LC_ALL 類別。

下列範例與 LC_ALL 類別。字串「.OCP」和「.ACP」其中一個可以在字碼頁頁碼位置用於指定對使用者預設 OEM 字碼頁和使用者預設 ANSI 字碼頁的用途，分別。

setlocale( LC_ALL, "" );
設定地區設定為預設值，是從作業系統取得使用者的預設 ANSI 字碼頁。
setlocale( LC_ALL, ".OCP" );
明確設定地區設定為從作業系統取得的目前 OEM 字碼頁。
setlocale( LC_ALL, ".ACP" );
設定地區設定為從作業系統取得的 ANSI 字碼頁。
setlocale( LC_ALL, "<localename>" );
設定地區設定為 <localename>表示的地區設定名稱。
setlocale( LC_ALL, "<language>_<country>" );
設定地區設定為 <language> 和 <country>表示的語言和國家/地區，使用主機作業系統取得的預設字碼頁。
setlocale( LC_ALL, "<language>_<country>.<code_page>" );
設定地區設定為 <language>、 <country>和 <code_page> 字串表示的語言、國家/地區和字碼頁。您可以使用語言、國家/地區和字碼頁的各種組合。例如：
```
setlocale( LC_ALL, "French_Canada.1252" );
// Set code page to French Canada ANSI default
setlocale( LC_ALL, "French_Canada.ACP" );
// Set code page to French Canada OEM default
setlocale( LC_ALL, "French_Canada.OCP" );
```
setlocale( LC_ALL, "<language>" );
設定地區設定為 <language>表示的語言，使用預設國家/地區的國家/地區指定和使用者預設 ANSI 字碼頁語言 (如從主機作業系統取得。例如，對 setlocale 的呼叫下列功能相同:
```
setlocale( LC_ALL, "en-US" );
setlocale( LC_ALL, "English" );
setlocale( LC_ALL, "English_United States.1252" );
```
setlocale( LC_ALL, ".<code_page>" );
設定字碼頁對 <code_page>表示的值，使用預設國家/地區和語言 (如全球主機作業系統) 中指定的字碼頁。

類別必須是影響字碼頁變更的 LC_ALL 或 LC_CTYPE 。例如，在中，如果主機作業系統的預設國家/地區和語言是「US」和「eng」，對 setlocale 的下列兩個呼叫的功能相同:

setlocale( LC_ALL, ".1252" );

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

如需詳細資訊請參閱在 前置處理器參考》中的setlocale pragma 。

_configthreadlocale 函式可用來控制 setlocale 是否會影響所有執行緒地區設定在程式的或呼叫執行緒的地區設定。

需求

程序	必要的標頭檔
setlocale	<locale.h>
_wsetlocale	<locale.h> 或 <wchar.h>

如需其他相容性資訊，請參閱入門介紹中的相容性 (Compatibility) 。

範例

// crt_setlocale.cpp
// 
// 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 and time in the current
// locale's format.
int get_time(unsigned char* str)
{
    __time64_t ltime;
    struct tm  thetime;

    // Retieve the time
    _time64(&ltime);
    _gmtime64_s(&thetime, &ltime);

    // Format the current time structure into a string
    // using %#x is the long date representation,
    // appropriate to 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 German
// and prints the time.
unsigned __stdcall SecondThreadFunc( void* pArguments )
{
    unsigned char str[BUFF_SIZE];

    // Set the thread local
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, "de-DE"));

    // Retrieve the time string from the helper function
    if (get_time(str) == 0)
    {
        printf("The time in de-DE locale is: '%s'\n", str);
    }

    _endthreadex( 0 );
    return 0;
} 

// The main thread spawns a second thread (above) and then
// sets the locale to English and prints the time.
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);

    // Retrieve the time string from the helper function
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, "en-US"));

    // Create the second thread.
    hThread = (HANDLE)_beginthreadex( NULL, 0, &SecondThreadFunc,
                                      NULL, 0, &threadID );

    if (get_time(str) == 0)
    {
        // Retrieve the time string from the helper function
        printf("The time 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 );
}