`setlocale`, `_wsetlocale`

아티클
01/04/2024

런타임 로캘을 설정하거나 검색합니다.

구문

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

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

매개 변수

category
로캘의 영향을 받는 범주입니다.

locale
로캘 지정자입니다.

반환 값

유효 locale 하고 category 지정된 경우 함수는 지정된 locale 문자열과 연결된 문자열에 대한 포인터를 반환합니다 category. 인수인 localeNULL경우 함수는 현재 로캘을 반환합니다.

잘못된 인수가 두 함수에 전달되면 반환 값은 .입니다 NULL. 잘못된 인수에 대한 동작은 다음과 같습니다.

함수	잘못된 매개 변수	매개 변수 유효성 검사에 설명된 대로 호출된 처리기가 잘못되었습니다.	설정 `errno`
`setlocale`	`category`	예	예
`setlocale`	`locale`	no	아니요
`_wsetlocale`	`category`	예	예
`_wsetlocale`	`locale`	no	아니요

다음을 호출해도

setlocale( LC_ALL, "en-US" );

문자열만 반환하는 모든 범주를 설정합니다.

en-US

프로그램 로캘 정보의 일부를 복원할 수 있도록 setlocale에서 반환된 문자열을 복사할 수 있습니다. 글로벌 또는 스레드 로컬 스토리지는 setlocale에서 반환된 문자열에 사용됩니다. setlocale에 대한 이후 호출이 문자열을 덮어쓰므로, 이전 호출에서 반환된 문자열 포인터가 무효화됩니다.

설명

setlocale 함수를 사용하여 locale 및 category에 의해 지정된 현재 프로그램 로캘 정보의 일부 또는 전체를 설정, 변경 또는 쿼리합니다. locale은 프로그램의 특정 측면을 사용자 지정할 수 있는 집약성(국가/지역 및 언어)을 나타냅니다. 일부 로캘 종속 범주에는 날짜 형식 지정 및 통화 값의 형식 표시가 포함됩니다. locale을 컴퓨터에서 지원되는 폼이 여러 개 있는 언어의 기본 문자열로 설정하는 경우 setlocale 반환 코드를 검사하여 적용되는 언어를 확인해야 합니다. 예를 들어 반환 값으로 "chinese" 설정 locale 하면 반환 값 중 하나 "chinese-simplified" 또는 "chinese-traditional".일 수 있습니다.

_wsetlocale 은 setlocale의 와이드 문자 버전이고, locale 인수와 _wsetlocale 의 반환 값은 와이드 문자 문자열입니다. 그렇지 않으면_wsetlocale 과 setlocale 이 동일하게 작동합니다.

기본적으로 이 함수의 전역 상태는 애플리케이션으로 범위가 지정됩니다. 이 동작을 변경하려면 CRT의 전역 상태를 참조하세요.

일반 텍스트 루틴 매핑

`TCHAR.H` 루틴	`_UNICODE` 정의 `_MBCS` 되지 않음	`_MBCS` 정의	`_UNICODE` 정의
`_tsetlocale`	`setlocale`	`setlocale`	`_wsetlocale`

category 인수는 영향을 받는 프로그램 로캘 정보의 일부를 지정합니다. 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` 함수입니다.

이 함수는 범주 매개 변수의 유효성을 검사합니다. 범주 매개 변수가 이전 테이블에 제공된 값 중 하나가 아니면 매개 변수 유효성 검사에 설명된 대로 잘못된 매개 변수 처리기가 호출됩니다. 계속해서 실행하도록 허용된 경우 함수가errno를 EINVAL로 설정하고 NULL을 반환합니다.

locale 인수는 로캘을 지정하는 문자열에 대한 포인터입니다. 인수 형식 locale 에 대한 자세한 내용은 로캘 이름, 언어 및 국가/지역 문자열을 참조 하세요. locale 이 빈 문자열 가리키면 로캘은 구현 시 정의된 네이티브 환경입니다. C의 값은 C 번역에 대한 최소 ANSI 표준에 맞는 환경을 지정합니다. C로캘은 char 데이터 형식이 1바이트이고 해당 값이 항상 256보다 작은 것으로 가정합니다.

프로그램을 시작할 때 다음 문을 실행합니다.

setlocale( LC_ALL, "C" );

locale 인수는 로캘 이름, 언어 문자열, 언어 문자열 및 국가/지역 코드, 코드 페이지, 언어 문자열, 국가/지역 코드 및 코드 페이지를 가져올 수 있습니다. 사용 가능한 로캘 이름, 언어, 국가/지역 코드 및 코드 페이지에는 Windows NLS API에서 지원하는 모든 로캘이 포함됩니다. 지원되는 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));

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. 코드 페이지는 사용자 기본 로캘 이름 값으로 설정 LOCALE_IDEFAULTCODEPAGE 됩니다 GetLocaleInfoEx.
setlocale( LC_ALL, ".ACP" );

로캘을 운영 체제에서 얻은 ANSI 코드 페이지로 설정합니다. 로캘 이름은 .에서 반환된 값으로 설정됩니다 GetUserDefaultLocaleName. 코드 페이지는 사용자 기본 로캘 이름 값으로 설정 LOCALE_IDEFAULTANSICODEPAGE 됩니다 GetLocaleInfoEx.
setlocale( LC_ALL, "<localename>" );

로캘을 로캘 이름으로 <localename>설정합니다. 코드 페이지는 지정된 로캘 이름의 값으로 LOCALE_IDEFAULTANSICODEPAGE 설정됩니다 GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>" );

로캘을 호스트 운영 체제에서 가져온 기본 코드 페이지와 함께 표시 <language> 한 언어 및 <country>국가/지역으로 설정합니다. 코드 페이지는 지정된 로캘 이름의 값으로 LOCALE_IDEFAULTANSICODEPAGE 설정됩니다 GetLocaleInfoEx.
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 은 기능적으로 동일합니다.

setlocale( LC_ALL, ".1252" );

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

자세한 내용은 setlocale C/C++ 전처리기 참조의 pragma 지시문을 참조하세요.

이 함수 _configthreadlocale 는 프로그램에서 모든 스레드의 로캘에 영향을 주는지 또는 호출 스레드의 로캘에만 영향을 주는지 여부를 setlocale 제어하는 데 사용됩니다.

UTF-8 지원

Windows 10 버전 1803(10.0.17134.0)부터 유니버설 C 런타임은 UTF-8 코드 페이지 사용을 지원합니다. 이 변경은 C 런타임 함수에 전달된 문자열이 UTF-8 인코딩에서 문자열을 예상할 수 있음을 char 의미합니다. UTF-8 모드를 사용하도록 설정하려면 를 사용할 때 코드 페이지로 사용합니다 ".UTF8"setlocale. 예를 들어 로 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 모드는 기본 ACP(Windows ANSI 코드 페이지)를 사용하여 역사적으로 번역된 char 문자열이 있는 함수에도 사용할 수 있습니다. 예를 들어 UTF-8 코드 페이지를 사용하는 동안 호출 _mkdir("😊") 하면 프로그램을 실행하기 전에 ACP를 UTF-8로 변경하도록 요구하는 대신 해당 이모지의 디렉터리가 폴더 이름으로 올바르게 생성됩니다. 마찬가지로 해당 폴더에서 호출 _getcwd() 하면 UTF-8로 인코딩된 문자열이 반환됩니다. 호환성을 위해 C 로캘 코드 페이지가 UTF-8로 설정되지 않은 경우에도 ACP가 사용됩니다.

C 런타임의 다음 측면은 프로그램 시작 중에 설정되고 기본 ACP__argv_acmdln_pgmptr(Windows ANSI 코드 페이지)를 사용해야 하므로 UTF-8을 사용할 수 없습니다.

이 지원 이전에는 mbrtoc32c16rtombmbrtoc16UTF-8 좁은 문자열, UTF-16(Windows 플랫폼과 c32rtomb 동일한 인코딩) 및 UTF-32 간에 변환하기 wchar_t 위해 존재했습니다. 호환성을 위해 이러한 API는 여전히 UTF-8로 변환되고 코드 페이지를 통해 setlocale설정되지 않습니다.

Windows 10 이전의 OS에서 이 기능을 사용하려면 앱 로컬 배포를 사용하거나 Windows SDK 이상 버전 1803(10.0.17134.0)을 사용하여 정적으로 연결해야 합니다. 1803 이전 Windows 10 운영 체제(10.0.17134.0)의 경우 정적 연결만 지원됩니다.

요구 사항

루틴에서 반환된 값	필수 헤더
`setlocale`	`<locale.h>`
`_wsetlocale`	`<locale.h>` 또는 `<wchar.h>`

호환성에 대한 자세한 내용은 호환성을 참조하세요.

예시

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

`setlocale`, `_wsetlocale`

구문

매개 변수

반환 값

설명

일반 텍스트 루틴 매핑

UTF-8 지원

요구 사항

예시

참고 항목

피드백

피드백

추가 리소스

setlocale, _wsetlocale

구문

매개 변수

반환 값

설명

일반 텍스트 루틴 매핑

UTF-8 지원

요구 사항

예시

참고 항목

피드백

피드백

추가 리소스

`setlocale`, `_wsetlocale`