setlocale, _wsetlocale

ランタイム ロケールを設定または取得します。

構文

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

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

パラメーター

category
ロケールに影響されるカテゴリ。

locale
ロケールの指定子。

戻り値

有効な locale と category が指定されている場合、関数は、指定された locale および categoryに関連付けられた文字列へのポインターを返します。 locale引数がNULLされている場合、関数は現在のロケールを返します。

いずれかの関数に無効な引数が渡された場合、戻り値は NULL。 無効な引数の動作は次のとおりです。

呼び出し:

setlocale( LC_ALL, "en-US" );

を呼び出すと、すべてのカテゴリを設定し、文字列だけを返します

en-US

setlocale によって返された文字列をコピーして、プログラムのロケール情報のその部分を復元できます。 setlocale によって返された文字列に対しては、グローバルまたはスレッド ローカル ストレージが使用されます。 その後 setlocale を呼び出すと文字列が上書きされ、前の呼び出しで返された文字列のポインターは無効になります。

解説

setlocale および locale で指定されている現在のプログラムのロケール情報の一部またはすべてを設定、変更、または照会するには、category 関数を使用します。 locale とは、地域性、つまり国や地域、言語に関する情報であり、この情報に基づいてプログラムのさまざまな側面をカスタマイズできます。 ロケールに依存するカテゴリとしては、日付の形式や通貨値の表示形式などがあります。 locale を、コンピューターでサポートされているさまざまな形式を持つ言語の既定の文字列に設定した場合は、setlocale 戻り値をチェックして、有効な言語を確認する必要があます。 たとえば、 locale を "chinese" に設定した場合、戻り値は "chinese-simplified" または "chinese-traditional"のいずれかになります。

ワイド文字を扱う場合は、_wsetlocale ではなく setlocaleを使用します。 locale の場合、 _wsetlocale 引数にはワイド文字列を指定します。また戻り値もワイド文字列です。 それ以外では、_wsetlocale と setlocale の動作は同じです。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

汎用テキスト ルーチンのマップ

category 引数は、影響を受けるプログラムのロケール情報の部分を指定します。 category に使用するマクロ、および影響されるプログラムの一部は次のとおりです。

この関数は、カテゴリ パラメーターを検証します。 category パラメーターが前の表で指定した値の 1 つでない場合は、「パラメーターの検証で説明されているように、無効なパラメーター ハンドラーが呼び出されます。 実行の継続が許可された場合、この関数は errno を EINVAL に設定し、NULL を返します。

The locale 引数は、ロケールを指定する文字列へのポインターです。 locale引数の形式については、「名前、言語、および国/地域の文字列を参照してください。 locale が空の文字列をポイントしている場合は、実装定義のネイティブ環境になります。 C の値は、C 翻訳のための ANSI に準拠した最小環境を指定します。 C ロケールは、すべての char データ型が 1 バイトであり、それらの値は常に 256 未満であると推定します。

プログラムの開始時に、次のステートメントの等価性の確認が実行されます。

setlocale( LC_ALL, "C" );

locale 引数には、ロケール名、言語識別文字列、言語識別文字列と国/地域コード、コード ページ、または言語識別文字列、国/地域コード、コード ページを指定できます。 使用可能なロケール名、言語、国/地域コード、およびコード ページには、Windows NLS API でサポートされているすべてのロケール名が含まれます。 setlocaleでサポートされるロケール名のセットについては、「ロケール名、言語、および国/地域の文字列で説明されています。 setlocaleでサポートされる言語および国/地域の文字列のセットは、言語文字列および Country/Region 文字列に一覧表示されます。 パフォーマンス上の理由と、コードに埋め込まれた、またはストレージに対してシリアル化されたロケール文字列の保守容易性の理由により、ロケール名形式を使用することをお勧めします。 オペレーティング システムの更新によってロケール名の文字列が変更される可能性は、言語および国/地域名の形式よりも低くなっています。

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

returns

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 コード ページです。 ロケール名は、GetUserDefaultLocaleName によって返される値に設定されます。 コード ページは、GetACP によって返される値に設定されます。

• setlocale( LC_ALL, ".OCP" );

  オペレーティング システムから取得した現在の OEM コード ページをロケールに設定します。 ロケール名は、GetUserDefaultLocaleName によって返される値に設定されます。 コード ページは、GetLocaleInfoEx によってユーザーの既定のロケール名の LOCALE_IDEFAULTCODEPAGE 値に設定されます。

• setlocale( LC_ALL, ".ACP" );

  ロケールに、オペレーティング システムから取得した ANSI コード ページを設定します。 ロケール名は、GetUserDefaultLocaleName によって返される値に設定されます。 コード ページは、GetLocaleInfoEx によってユーザーの既定のロケール名の LOCALE_IDEFAULTANSICODEPAGE 値に設定されます。

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

  <localename> で示されたロケール名をロケールに設定します。 コード ページは、GetLocaleInfoEx によって指定されたロケール名の LOCALE_IDEFAULTANSICODEPAGE 値に設定されます。

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

  <language> と <country> で示された言語および国/地域と、ホスト オペレーティング システムから取得した既定のコード ページをロケールに設定します。 コード ページは、GetLocaleInfoEx によって指定されたロケール名の LOCALE_IDEFAULTANSICODEPAGE 値に設定されます。

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

  <language>、<country>、<code_page> 文字列によって示された言語、国/地域、コード ページをロケールに設定します。 言語、国/地域、およびコード ページはさまざまに組み合わせて使用できます。 たとえば、次の呼び出しは、ロケールに、カナダ フランス語、およびコード ページ 1252 を設定します。

  setlocale( LC_ALL, "French_Canada.1252" );

  次の呼び出しは、ロケールに、カナダ フランス語、および既定の ANSI コード ページを設定します。

  setlocale( LC_ALL, "French_Canada.ACP" );

  次の呼び出しは、ロケールに、カナダ フランス語、および既定の OEM コード ページを設定します。

  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 である必要があります。 たとえば、ホスト オペレーティング システムの既定の国/地域と言語が "United States" と "English" の場合、次の setlocale の 2 つの呼び出しは機能的に同じです。

setlocale( LC_ALL, ".1252" );

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

詳細については、「C/C++ プリプロセッサ リファレンス」の setlocale pragma ディレクティブをご覧ください。

setlocale がプログラムのすべてのスレッドのロケールに影響するか、または呼び出しスレッドのロケールだけに影響するかを制御するには、_configthreadlocale 関数を使用します。

UTF-8 のサポート

Windows 10 バージョン 1803 (10.0.17134.0) 以降では、ユニバーサル C ランタイムで UTF-8 コード ページの使用がサポートされます。 この変更は、C ランタイム関数に渡 char 文字列が UTF-8 エンコードの文字列を予期できることを意味します。 UTF-8 モードを有効にするには、setlocale を使用するときに、コード ページとして ".UTF8" を使用します。 たとえば、 setlocale(LC_ALL, ".UTF8") はロケールに現在の既定の Windows ANSI コード ページ (ACP) を使用し、コード ページには UTF-8 を使用します。

UTF-8 モードを指定する文字列は次のように指定します。

• 大文字と小文字は区別されない
• ハイフン (-) は省略可能です
• ロケール名のコード ページ部分にある必要があります。そのため、"en_US.UTF8" または ".utf8" ように先頭にピリオド (.) がある必要があります

次の例は、UTF-8 文字列を指定する方法を示しています。

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

setlocale(LC_ALL, ".UTF8")を呼び出した後、mbtowcsに "😊" を渡すと、wchar_t文字列に正しく変換されます。 以前は、この翻訳を行うために使用できるロケール設定はありませんでした。

UTF-8 モードは、既定の Windows ANSI コード ページ (ACP) を使用してこれまで変換されていた char 文字列を持つ関数に対しても有効になります。 たとえば、UTF-8 コード ページを使用して _mkdir("😊") を呼び出すと、プログラムを実行する前に ACP を UTF-8 に変更する必要がなく、フォルダー名としてその絵文字を持つディレクトリが正しく生成されます。 同様に、そのフォルダー内の _getcwd() を呼び出すと、UTF-8 でエンコードされた文字列が返されます。 互換性のために、C ロケール コード ページが UTF-8 に設定されていない場合、ACP は引き続き使用されます。

C ランタイムの次の側面は、プログラムの起動時に設定され、既定の Windows ANSI コード ページ (ACP) を使用する必要があるため、UTF-8 を使用できません: __argv、 _acmdln、および _pgmptr。

このサポートの前には、UTF-8 のナロー文字列、UTF-16 (Windows プラットフォームでは wchar_t と同じエンコーディング)、UTF-32 の間で変換を行うための mbrtoc16、mbrtoc32、c16rtomb、c32rtomb が存在していました。 互換性のために、これらの API では、setlocale によって設定されたコード ページではなく、UTF-8 との間でのみ引き続き変換を行います。

Windows 10 より前の OS でこの機能を使用するには、Windows SDK のバージョン 1803 (10.0.17134.0) 以降を使用して、アプリローカル配置または静的リンクを使用する必要があります。 1803 (10.0.17134.0) より前の Windows 10 オペレーティング システムでは、静的リンクのみがサポートされています。

要件

互換性の詳細については、「 Compatibility」を参照してください。

例

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

関連項目

ロケール名、言語、国/地域の文字列
_configthreadlocale
_create_locale, _wcreate_locale
ロケール
localeconv
_mbclen、 mblen、 _mblen_l
strlen、 wcslen、 _mbslen、 _mbslen_l、 _mbstrlen、 _mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
strcoll 関数
strftime、 wcsftime、 _strftime_l、 _wcsftime_l
strxfrm、 wcsxfrm、 _strxfrm_l、 _wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l