setlocale, _wsetlocalesetlocale, _wsetlocale

実行時ロケールを設定または取得します。Sets or retrieves the run-time locale.

構文Syntax

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

パラメーターParameters

category
ロケールに影響されるカテゴリ。Category affected by locale.

localelocale
ロケールの指定子。Locale specifier.

戻り値Return value

有効なロケールカテゴリが指定されている場合、は、指定されたロケールおよびカテゴリに関連付けられている文字列へのポインターを返します。If a valid locale and category are given, returns a pointer to the string associated with the specified locale and category. ロケールまたはカテゴリが有効でない場合、は null ポインターを返し、プログラムの現在のロケール設定は変更されません。If the locale or category isn't valid, returns a null pointer, and the current locale settings of the program are unchanged.

たとえば、For example, the call

setlocale( LC_ALL, "en-US" );

を呼び出すと、すべてのカテゴリを設定し、文字列だけを返しますsets all categories, returning only the string

en-US

setlocale によって返された文字列をコピーして、プログラムのロケール情報のその部分を復元できます。You can copy the string returned by setlocale to restore that part of the program's locale information. setlocale によって返された文字列に対しては、グローバルまたはスレッド ローカル ストレージが使用されます。Global or thread local storage is used for the string returned by setlocale. その後 setlocale を呼び出すと文字列が上書きされ、前の呼び出しで返された文字列のポインターは無効になります。Later calls to setlocale overwrite the string, which invalidates string pointers returned by earlier calls.

解説Remarks

関数を使用し setlocale て、 localeおよびcategoryによって指定された現在のプログラムのロケール情報の一部またはすべてを設定、変更、または照会します。Use the setlocale function to set, change, or query some or all of the current program locale information specified by locale and category. ロケールとは、プログラムの特定の側面をカスタマイズできる地域 (国/地域と言語) を指します。locale refers to the locality (country/region and language) for which you can customize certain aspects of your program. ロケールに依存するカテゴリとしては、日付の形式や通貨値の表示形式などがあります。Some locale-dependent categories include the formatting of dates and the display format for monetary values. コンピューターで複数の形式がサポートされている言語の既定の文字列にロケールを設定した場合は、戻り値をチェックして、有効な言語を確認する必要があり setlocale ます。If you set locale to the default string for a language that has multiple forms supported on your computer, you should check the setlocale return value to see which language is in effect. たとえば、 localeを "中国語" に設定した場合、戻り値は "簡体字中国語または繁体字中国語" のいずれかになります。For example, if you set locale to "chinese" the return value could be either "chinese-simplified" or "chinese-traditional".

_wsetlocaleは、のワイド文字バージョンです setlocale 。のロケール引数と戻り値 _wsetlocale はワイド文字列です。_wsetlocale is a wide-character version of setlocale; the locale argument and return value of _wsetlocale are wide-character strings. それ以外では、_wsetlocalesetlocale の動作は同じです。_wsetlocale and setlocale behave identically otherwise.

既定では、この関数のグローバル状態はアプリケーションにスコープが設定されています。By default, this function's global state is scoped to the application. これを変更するには、「 CRT でのグローバル状態」を参照してください。To change this, see Global state in the CRT.

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tsetlocale setlocale setlocale _wsetlocale

Category引数は、影響を受けるプログラムのロケール情報の部分を指定します。The category argument specifies the parts of a program's locale information that are affected. Categoryに使用されるマクロと、影響を与えるプログラムの部分は次のとおりです。The macros used for category and the parts of the program they affect are as follows:

カテゴリフラグcategory flag 影響Affects
LC_ALL 次に示すように、すべてのカテゴリです。All categories, as listed below.
LC_COLLATE strcoll_stricollwcscoll_wcsicollstrxfrm_strncoll_strnicoll_wcsncoll_wcsnicoll、および wcsxfrm の各関数。The strcoll, _stricoll, wcscoll, _wcsicoll, strxfrm, _strncoll, _strnicoll, _wcsncoll, _wcsnicoll, and wcsxfrm functions.
LC_CTYPE 文字処理関数の (影響を受けない isdigitisxdigitmbstowcs、および mbtowc を除く)。The character-handling functions (except isdigit, isxdigit, mbstowcs, and mbtowc, which are unaffected).
LC_MONETARY localeconv 関数が返す通貨形式情報。Monetary-formatting information returned by the localeconv function.
LC_NUMERIC printf などの書式化出力ルーチン、データ変換ルーチン、および localeconv が返す通貨形式以外の形式情報で使用される小数点文字。Decimal-point character for the formatted output routines (such as printf), for the data-conversion routines, and for the non-monetary formatting information returned by localeconv. 小数点文字に加え、LC_NUMERIC は桁区切り記号、および localeconv によって返されるグループ化コントロールの文字列を設定します。In addition to the decimal-point character, LC_NUMERIC sets the thousands separator and the grouping control string returned by localeconv.
LC_TIME strftime および wcsftime 関数。The strftime and wcsftime functions.

この関数は、カテゴリ パラメーターを検証します。This function validates the category parameter. Category パラメーターが前の表に示した値のいずれでもない場合は、「パラメーターの検証」で説明されているように、無効なパラメーターハンドラーが呼び出されます。If the category parameter isn't one of the values given in the previous table, the invalid parameter handler is invoked, as described in Parameter Validation. 実行の継続が許可された場合、この関数は errnoEINVAL に設定し、NULL を返します。If execution is allowed to continue, the function sets errno to EINVAL and returns NULL.

Locale引数は、ロケールを指定する文字列へのポインターです。The locale argument is a pointer to a string that specifies the locale. Locale引数の形式の詳細については、「ロケール名、言語、および国/地域識別文字列」を参照してください。For information about the format of the locale argument, see Locale Names, Languages, and Country/Region Strings. ロケールが空の文字列をポイントしている場合は、実装定義のネイティブ環境になります。If locale points to an empty string, the locale is the implementation-defined native environment. C の値は、C 翻訳のための ANSI に準拠した最小環境を指定します。A value of C specifies the minimal ANSI conforming environment for C translation. C ロケールは、すべての char データ型が 1 バイトであり、それらの値は常に 256 未満であると推定します。The C locale assumes that all char data types are 1 byte and that their value is always less than 256.

プログラムの開始時に、次のステートメントの等価性の確認が実行されます。At program startup, the equivalent of the following statement is executed:

setlocale( LC_ALL, "C" );

Locale引数は、ロケール名、言語文字列、言語文字列と国/地域コード、コードページ、言語文字列、国/地域コード、およびコードページを受け取ることができます。The locale argument can take a locale name, a language string, a language string and country/region code, a code page, or a language string, country/region code, and code page. 使用できるロケール名、言語、国/地域コード、およびコードページのセットには、Windows NLS API でサポートされているものがすべて含まれています。The set of available locale names, languages, country/region codes, and code pages includes all those supported by the Windows NLS API. setlocale でサポートされているロケール名のセットについては、「ロケール名、言語、および国/地域識別文字列」に記載されています。The set of locale names supported by setlocale are described in Locale Names, Languages, and Country/Region Strings. setlocale でサポートされる言語識別文字列と国/地域識別文字列は、「言語識別文字列」および「国/地域識別文字列」に記載されています。The set of language and country/region strings supported by setlocale are listed in Language Strings and Country/Region Strings. パフォーマンス上の理由と、コードに埋め込まれた、またはストレージに対してシリアル化されたロケール文字列の保守容易性の理由により、ロケール名形式を使用することをお勧めします。We recommend the locale name form for performance and for maintainability of locale strings embedded in code or serialized to storage. オペレーティング システムの更新によってロケール名の文字列が変更される可能性は、言語および国/地域名の形式よりも低くなっています。The locale name strings are less likely to be changed by an operating system update than the language and country/region name form.

Locale引数として渡される null ポインターは、 setlocale 国際環境を設定するのではなく、クエリを実行するように指示します。A null pointer that's passed as the locale argument tells setlocale to query instead of to set the international environment. Locale引数が null ポインターの場合、プログラムの現在のロケール設定は変更されません。If the locale argument is a null pointer, the program's current locale setting isn't changed. 代わりに、は、 setlocale スレッドの現在のロケールのカテゴリに関連付けられている文字列へのポインターを返します。Instead, setlocale returns a pointer to the string that's associated with the category of the thread's current locale. Category引数がの場合 LC_ALL 、関数は、各カテゴリの現在の設定をセミコロンで区切って示す文字列を返します。If the category argument is LC_ALL, the function returns a string that indicates the current setting of each category, separated by semicolons. たとえば、呼び出しのシーケンス For example, the sequence of calls

// 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 カテゴリに対応する文字列です。which is the string that's associated with the LC_ALL category.

次の例は LC_ALL のカテゴリに関連するものです。The following examples pertain to the LC_ALL category. 文字列 "のいずれかです。OCP "and"。コードページ番号の代わりに、ACP "を使用して、ユーザーの既定の OEM コードページとユーザー既定の ANSI コードページの使用をそれぞれ指定することができます。Either of the strings ".OCP" and ".ACP" can be used instead of a code page number to specify use of the user-default OEM code page and user-default ANSI code page for that locale name, respectively.

  • setlocale( LC_ALL, "" );

    ロケールを既定に設定します。これはオペレーティング システムから取得したユーザー既定の ANSI コード ページです。Sets the locale to the default, which is the user-default ANSI code page obtained from the operating system. ロケール名は、 Getuserdefaultlocalenameによって返される値に設定されます。The locale name is set to the value returned by GetUserDefaultLocaleName. コードページは、 Getacpによって返される値に設定されます。The code page is set to the value returned by GetACP.

  • setlocale( LC_ALL, ".OCP" );

    ロケールを、オペレーティングシステムから取得した現在の OEM コードページに設定します。Sets the locale to the current OEM code page obtained from the operating system. ロケール名は、 Getuserdefaultlocalenameによって返される値に設定されます。The locale name is set to the value returned by GetUserDefaultLocaleName. コードページは、 GetLocaleInfoExによってユーザーの既定のロケール名のLOCALE_IDEFAULTCODEPAGE値に設定されます。The code page is set to the LOCALE_IDEFAULTCODEPAGE value for the user-default locale name by GetLocaleInfoEx.

  • setlocale( LC_ALL, ".ACP" );

    ロケールに、オペレーティング システムから取得した ANSI コード ページを設定します。Sets the locale to the ANSI code page obtained from the operating system. ロケール名は、 Getuserdefaultlocalenameによって返される値に設定されます。The locale name is set to the value returned by GetUserDefaultLocaleName. コードページは、 GetLocaleInfoExによってユーザーの既定のロケール名のLOCALE_IDEFAULTANSICODEPAGE値に設定されます。The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the user-default locale name by GetLocaleInfoEx.

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

    ロケールをによって示されるロケール名に設定 <localename> します。Sets the locale to the locale name that's indicated by <localename>. コードページは、 GetLocaleInfoExによって指定されたロケール名のLOCALE_IDEFAULTANSICODEPAGE値に設定されます。The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the specified locale name by GetLocaleInfoEx.

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

    ロケールを、 <language> <country> ホストオペレーティングシステムから取得した既定のコードページと共に、およびによって示される言語と国/地域に設定します。Sets the locale to the language and country/region indicated by <language> and <country>, together with the default code page obtained from the host operating system. コードページは、 GetLocaleInfoExによって指定されたロケール名のLOCALE_IDEFAULTANSICODEPAGE値に設定されます。The code page is set to the LOCALE_IDEFAULTANSICODEPAGE value for the specified locale name by GetLocaleInfoEx.

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

    ロケールを、、、およびの各文字列で示される言語、国/地域、およびコードページに設定し <language> <country> <code_page> ます。Sets the locale to the language, country/region, and code page indicated by the <language>, <country>, and <code_page> strings. 言語、国/地域、およびコード ページはさまざまに組み合わせて使用できます。You can use various combinations of language, country/region, and code page. たとえば、次の呼び出しは、ロケールに、カナダ フランス語、およびコード ページ 1252 を設定します。For example, this call sets the locale to French Canada with code page 1252:

    setlocale( LC_ALL, "French_Canada.1252" );

    次の呼び出しは、ロケールに、カナダ フランス語、および既定の ANSI コード ページを設定します。This call sets the locale to French Canada with the default ANSI code page:

    setlocale( LC_ALL, "French_Canada.ACP" );

    次の呼び出しは、ロケールに、カナダ フランス語、および既定の OEM コード ページを設定します。This call sets the locale to French Canada with the default OEM code page:

    setlocale( LC_ALL, "French_Canada.OCP" );

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

    ロケールをによって示される言語に設定 <language> し、ホストオペレーティングシステムから取得した、指定した言語の既定の国/地域と、その国/地域のユーザー既定の ANSI コードページを使用します。Sets the locale to the language that's indicated by <language>, and uses the default country/region for the specified language and the user-default ANSI code page for that country/region as obtained from the host operating system. たとえば、次の setlocale の呼び出しは同等です。For example, the following calls to setlocale are functionally equivalent:

    setlocale( LC_ALL, "en-US" );

    setlocale( LC_ALL, "English" );

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

    パフォーマンスと保守性の理由から、最初の形式を使用することをお勧めします。We recommend the first form for performance and maintainability.

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

    コード ページに、<code_page> で表される値、および指定したコード ページの既定の国/地域と言語 (ホスト オペレーティング システムによって定義) を設定します。Sets the code page to the value indicated by <code_page>, together with the default country/region and language (as defined by the host operating system) for the specified code page.

カテゴリは、コード ページの変更に影響する LC_ALL または LC_CTYPE である必要があります。The category must be either LC_ALL or LC_CTYPE to effect a change of code page. たとえば、ホスト オペレーティング システムの既定の国/地域と言語が "United States" と "English" の場合、次の setlocale の 2 種類の呼び出しは機能的に同じです。For example, if the default country/region and language of the host operating system are "United States" and "English," the following two calls to setlocale are functionally equivalent:

setlocale( LC_ALL, ".1252" );

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

詳細については、「 setlocale C/c + + プリプロセッサリファレンス」のプラグマディレクティブを参照してください。For more information, see the setlocale pragma directive in the C/C++ Preprocessor Reference.

setlocale がプログラムのすべてのスレッドのロケールに影響するか、または呼び出しスレッドのロケールだけに影響するかを制御するには、関数 _configthreadlocale を使用します。The function _configthreadlocale is used to control whether setlocale affects the locale of all threads in a program or only the locale of the calling thread.

UTF-8 のサポートUTF-8 Support

Windows 10 ビルド 17134 (4 月2018更新プログラム) 以降では、ユニバーサル C ランタイムは UTF-8 コードページの使用をサポートしています。Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. これは、 char C ランタイム関数に渡される文字列では、utf-8 エンコーディングで文字列が想定されることを意味します。This means that char strings passed to C runtime functions will expect strings in the UTF-8 encoding. UTF-8 モードを有効にするには、を使用するときにコードページとして "UTF-8" を使用し setlocale ます。To enable UTF-8 mode, use "UTF-8" as the code page when using setlocale. たとえば、 setlocale(LC_ALL, ".utf8") は、現在の既定の WINDOWS ANSI コードページ (ACP) をロケールに、utf-8 をコードページに使用します。For example, setlocale(LC_ALL, ".utf8") will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.

を呼び出す setlocale(LC_ALL, ".UTF8") と、" 😊 " がに渡され、 mbtowcs 文字列に適切に変換され wchar_t ます。これに対して、以前はロケールの設定は使用できませんでした。After calling setlocale(LC_ALL, ".UTF8"), you may pass "😊" to mbtowcs and it will be properly translated to a wchar_t string, whereas previously there was not a locale setting available to do this.

UTF-8 モードは char 、既定の WINDOWS ANSI コードページ (ACP) を使用して、以前に翻訳された文字列を含む関数に対しても有効です。UTF-8 mode is also enabled for functions that have historically translated char strings using the default Windows ANSI code page (ACP). たとえば、 _mkdir("😊") utf-8 コードページを使用してを呼び出すと、プログラムを実行する前に ACP を utf-8 に変更する必要がなく、フォルダー名としてその絵文字を持つディレクトリが正しく生成されます。For example, calling _mkdir("😊") while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 prior to running your program. 同様に、 _getcwd() そのフォルダー内でを呼び出すと、utf-8 でエンコードされた文字列が返されます。Likewise, calling _getcwd() inside of that folder will return a UTF-8 encoded string. 互換性のために、C ロケールのコードページが UTF-8 に設定されていない場合でも、ACP は引き続き使用されます。For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.

UTF-8 を使用できない C ランタイムの次の側面は、プログラムの起動中に設定されており、既定の Windows ANSI コードページ (ACP) を使用する必要があるためです。 __argv _acmdln _pgmptrThe following aspects of the C Runtime that are not able to use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): __argv, _acmdln, and _pgmptr.

以前のバージョンでは、、、 c16rtombc32rtomb および mbrtoc16 mbrtoc32 は、utf-8のナロー文字列、utf-16 (Windows プラットフォームと同じエンコード)、 wchar_t および 32 utf-8 を変換するために存在していました。Previous to this support, mbrtoc16, mbrtoc32, c16rtomb, and c32rtomb existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as wchar_t on Windows platforms) and UTF-32. 互換性上の理由から、これらの Api は、によって設定されたコードページではなく、UTF-8 との間でのみ変換を行い setlocale ます。For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via setlocale.

Windows 7 などの Windows 10 より前の OS でこの機能を使用するには、アプリローカル展開を使用するか、Windows SDK 以降のバージョン17134を使用して静的にリンクする必要があります。To use this feature on an OS prior to Windows 10, such as Windows 7, you must use app-local deployment or link statically using version 17134 of the Windows SDK or later. 17134より前の Windows 10 オペレーティングシステムでは、静的リンクのみがサポートされています。For Windows 10 operating systems prior to 17134, only static linking is supported.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
setlocale <locale.h>
_wsetlocale <locale.h> または <wchar.h><locale.h> or <wchar.h>

互換性の詳細については、「互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

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

関連項目See also

ロケール名、言語、および国/地域識別文字列Locale Names, Languages, and Country/Region Strings
_configthreadlocale_configthreadlocale
_create_locale、_wcreate_locale_create_locale, _wcreate_locale
Locale
localeconvlocaleconv
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l
strlen、wcslen、_mbslen、_mbslen_l、_mbstrlen、_mbstrlen_lstrlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l
mbstowcs、_mbstowcs_lmbstowcs, _mbstowcs_l
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
_setmbcp_setmbcp
strcoll 系関数strcoll Functions
strftime、wcsftime、_strftime_l、_wcsftime_lstrftime, wcsftime, _strftime_l, _wcsftime_l
strxfrm、wcsxfrm、_strxfrm_l、_wcsxfrm_lstrxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l
wcstombs、_wcstombs_lwcstombs, _wcstombs_l
wctomb、_wctomb_lwctomb, _wctomb_l