`setlocale`, `_wsetlocale`

Artigo
01/04/2024

Defina ou recupere a localidade de tempo de execução.

Sintaxe

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

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

Parâmetros

category
Categoria afetada pela localidade.

locale
Especificador de localidade.

Valor retornado

Se um válido locale e forem fornecidos, as funções retornarão um ponteiro para a cadeia de caracteres associada ao especificado locale e categorycategory. Se o locale argumento for NULL, as funções retornarão a localidade atual.

Se um argumento inválido for passado para qualquer função, o valor de retorno será NULL. O comportamento para argumentos inválidos é o seguinte:

Função	Parâmetro inválido	Manipulador inválido invocado conforme descrito em Validação de parâmetro	Define `errno`
`setlocale`	`category`	sim	sim
`setlocale`	`locale`	não	não
`_wsetlocale`	`category`	sim	sim
`_wsetlocale`	`locale`	não	não

A chamada:

setlocale( LC_ALL, "en-US" );

define todas as categorias, retornando apenas a cadeia de caracteres

en-US

Você pode copiar a cadeia de caracteres retornada por setlocale para restaurar essa parte das informações de localidade do programa. O armazenamento de thread local ou global é usado para a cadeia de caracteres retornada por setlocale. As chamadas posteriores para setlocale substituirão a cadeia de caracteres, o que invalida os ponteiros de cadeia de caracteres retornados pelas chamadas anteriores.

Comentários

Use a função setlocale para definir, modificar ou consultar algumas ou todas as informações de localidade do programa atual especificadas por locale e category. locale refere-se à localidade (país/região e idioma) para a qual você pode personalizar alguns aspectos do programa. Algumas categorias de localidade dependentes incluem a formatação de datas e o formato de exibição de valores monetários. Se você definir locale como a cadeia de caracteres padrão para um idioma que tenha várias formas com suporte em seu computador, verifique o valor de retorno de setlocale para ver que idioma é aplicado. Por exemplo, se você definir locale como "chinese" o valor retornado poderá ser "chinese-simplified" ou "chinese-traditional".

_wsetlocale é uma versão caracteres largos de setlocale; o argumento locale e o valor de retorno de _wsetlocale são cadeias de caracteres largos. Caso contrário, _wsetlocale e setlocale se comportam de forma idêntica.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

Rotina `TCHAR.H`	`_UNICODE` e `_MBCS` não definidos	`_MBCS` definido	`_UNICODE` definido
`_tsetlocale`	`setlocale`	`setlocale`	`_wsetlocale`

O argumento category especifica as partes das informações de localidade de um programa que são afetadas. As macros usadas para category e as partes de programa que afetam são:

Sinalizador `category`	Afeta
`LC_ALL`	Todas as categorias, conforme listado abaixo.
`LC_COLLATE`	As funções `strcoll`, `_stricoll`, `wcscoll`, `_wcsicoll`, `strxfrm`, `_strncoll`, `_strnicoll`, `_wcsncoll`, `_wcsnicoll` e `wcsxfrm`.
`LC_CTYPE`	As funções de manipulação de caracteres (exceto `isdigit`, `isxdigit`, `mbstowcs` e `mbtowc`, que não são afetadas).
`LC_MONETARY`	Informações de formatação monetária retornadas pela função `localeconv`.
`LC_NUMERIC`	Caractere de ponto decimal para as rotinas de saída formatadas (como `printf`), para as rotinas de conversão de dados e para as informações de formatação não monetárias retornadas pelo `localeconv`. Além do caractere de ponto decimal, `LC_NUMERIC` define o separador de milhares e a cadeia de caracteres de controle de agrupamento retornada por `localeconv`.
`LC_TIME`	As funções `strftime` e `wcsftime`.

Essa função valida o parâmetro category. Se o parâmetro category não for um dos valores fornecidos na tabela anterior, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função definirá errno como EINVAL e retornará NULL.

O argumento locale é um ponteiro para uma cadeia de caracteres que especifica a localidade. Para obter informações sobre o formato do argumento, consulte Nomes de localidade, Idiomas e Cadeias de caracteres de locale país/região. Se locale apontar para uma cadeia de caracteres vazia, a localidade será o ambiente nativo definido pela implementação. Um valor de C especifica o ambiente em conformidade mínima com ANSI para a conversão em C. A localidade C pressupõe que todos os tipos de dados char tenham 1 byte e seu valor seja sempre menor que 256.

Na inicialização do programa, o equivalente da instrução a seguir é executado:

setlocale( LC_ALL, "C" );

O argumento locale pode ter um nome de localidade, uma cadeia de caracteres de idioma, uma cadeia de caracteres de idioma e código de país/região, uma página de código ou uma cadeia de caracteres de idioma, código de país/região e página de código. Os nomes de localidade, idiomas, códigos de país/região e páginas de código disponíveis incluem todos os suportados pela API NLS do Windows. O conjunto de nomes de localidade suportados por setlocale é descrito em Nomes de localidade, Idiomas e Cadeias de caracteres de país/região. O conjunto de cadeias de caracteres de idioma e país/região suportadas por setlocale são listadas em Cadeias de caracteres de idioma e Cadeias de caracteres de país/região. Recomendamos o formato do nome da localidade para o desempenho e a capacidade de manutenção de cadeias de caracteres de localidade inseridas no código ou serializadas para armazenamento. As cadeias de caracteres de nome da localidade são menos prováveis de ser alteradas por uma atualização do sistema operacional do que o formato de idioma e país/região.

Um ponteiro nulo que é passado quando o argumento locale diz para setlocale consultar em vez de para definir o ambiente internacional. Se o argumento locale for um ponteiro nulo, a configuração de localidade atual do programa não será alterada. Em vez disso, setlocale retorna um ponteiro para a cadeia de caracteres associada a category de localidade do thread atual. Se o argumento category for LC_ALL, a função retornará uma cadeia de caracteres que indica a configuração atual de cada categoria, separada por ponto-e-vírgula. Por exemplo, a sequência de chamadas

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

qual é a cadeia de caracteres associada à categoria LC_ALL.

Os exemplos a seguir pertencem à categoria LC_ALL. Qualquer uma das cadeias de caracteres “.OCP” e “.ACP” pode ser usada em vez de um número de página de código para especificar o uso da página de código OEM do usuário padrão e da página de código ANSI padrão do usuário para o nome da localidade, respectivamente.

setlocale( LC_ALL, "" );

Define a localidade para o padrão, que é a página de código ANSI padrão do usuário obtida do sistema operacional. O nome da localidade é definido como o valor retornado por GetUserDefaultLocaleName. A página de código é definida como o valor retornado por GetACP.
setlocale( LC_ALL, ".OCP" );

Define a localidade para a página de código OEM obtida do sistema operacional. O nome da localidade é definido como o valor retornado por GetUserDefaultLocaleName. A página de código é definida como o valor LOCALE_IDEFAULTCODEPAGE do nome da localidade padrão do usuário por GetLocaleInfoEx.
setlocale( LC_ALL, ".ACP" );

Define a localidade para a página de código ANSI obtida do sistema operacional. O nome da localidade é definido como o valor retornado por GetUserDefaultLocaleName. A página de código é definida como o valor LOCALE_IDEFAULTANSICODEPAGE do nome da localidade padrão do usuário por GetLocaleInfoEx.
setlocale( LC_ALL, "<localename>" );

Define a localidade para o nome da localidade que é indicado por <localename>. A página de código é definida como o valor LOCALE_IDEFAULTANSICODEPAGE do nome da localidade especificado por GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>" );

Define a localidade para o idioma e o país/região indicados por <language> e <country>, juntamente com a página de código padrão obtida do sistema operacional do host. A página de código é definida como o valor LOCALE_IDEFAULTANSICODEPAGE do nome da localidade especificado por GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );

Define a localidade para o idioma, o país/região e a página de código indicados pelas cadeias de caracteres <language>, <country> e <code_page>. Você pode usar várias combinações de idioma, país/região e página de código. Por exemplo, esta chamada define a localidade para francês canadense com a página de código 1252:

setlocale( LC_ALL, "French_Canada.1252" );

Esta chamada define a localidade para francês canadense com a página de código ANSI padrão:

setlocale( LC_ALL, "French_Canada.ACP" );

Esta chamada define a localidade para francês canadense com a página de código OEM padrão:

setlocale( LC_ALL, "French_Canada.OCP" );
setlocale( LC_ALL, "<language>" );

Define a localidade para o idioma que é indicado por <language> e usa o país/região padrão para o idioma especificado e a página de código ANSI padrão do usuário para esse país/região conforme obtidos do sistema operacional do host. Por exemplo, as seguintes chamadas para setlocale são funcionalmente equivalentes:

setlocale( LC_ALL, "en-US" );

setlocale( LC_ALL, "English" );

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

Recomendamos o primeiro formato para o desempenho e a capacidade de manutenção.
setlocale( LC_ALL, ".<code_page>" );

Define a página de código para o valor indicado por <code_page>, juntamente com o país/região e o idioma padrão (conforme definidos pelo sistema operacional do host) para a página de código especificada.

A categoria deve ser LC_ALL ou LC_CTYPE para efetivar uma alteração de página de código. Por exemplo, se o país/região e o idioma padrão do sistema operacional do host forem 'United States' e 'English', as duas chamadas a seguir para setlocale serão funcionalmente equivalentes:

setlocale( LC_ALL, ".1252" );

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

Para obter mais informações, confira a diretiva de pragma setlocale na Referência de pré-processador C/C++.

A função _configthreadlocale é usada para controlar se setlocale afeta a localidade de todos os threads em um programa ou somente a localidade do thread da chamada.

Suporte para UTF-8

A partir da versão 1803 do Windows 10 (10.0.17134.0), o Universal C Runtime dá suporte ao uso de uma página de código UTF-8. A alteração significa que char as cadeias de caracteres passadas para funções de tempo de execução C podem esperar cadeias de caracteres na codificação UTF-8. Para habilitar o modo UTF-8, use ".UTF8" como a página de código ao usar setlocale. Por exemplo, setlocale(LC_ALL, ".UTF8") usa a página de código (ACP) padrão atual do Windows para a localidade e UTF-8 para a página de código.

A cadeia de caracteres para especificar o modo UTF-8 é:

não diferenciam maiúsculas de minúsculas
o hífen (-) é opcional
Ele deve estar na parte da página de código do nome da localidade, portanto, deve ter um ponto à esquerda (.) como nestes exemplos: "en_US.UTF8" ou ".utf8"

Os exemplos a seguir mostram como especificar a cadeia de caracteres UTF-8:

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

Depois de chamar setlocale(LC_ALL, ".UTF8"), você pode passar ""😊 para e ele será traduzido corretamente para mbtowcs uma cadeia de wchar_t caracteres. Anteriormente, não havia uma configuração de localidade disponível para fazer essa tradução.

O modo UTF-8 também está habilitado para funções que têm cadeias de caracteres char historicamente convertidas usando a ACP (página de código ANSI) padrão do Windows. Por exemplo, chamar _mkdir("😊") ao usar uma página de código UTF-8 produzirá corretamente um diretório com esse emoji como o nome da pasta, em vez de exigir que a ACP seja alterada para UTF-8 antes de executar seu programa. Da mesma forma, chamar _getcwd() nessa pasta retorna uma cadeia de caracteres codificada em UTF-8. Para compatibilidade, o ACP ainda será usado se a página de código de localidade C não estiver definida como UTF-8.

Os seguintes aspectos do C Runtime não podem usar a UTF-8 porque são definidos durante a inicialização do programa e devem usar a ACP (página de código ANSI) padrão do Windows: __argv, _acmdln, and _pgmptr.

Anterior a esse suporte, mbrtoc16, mbrtoc32c16rtomb e c32rtomb existiam para traduzir entre cadeias de caracteres estreitas UTF-8, UTF-16 (mesma codificação que wchar_t em plataformas Windows) e UTF-32. Por motivos de compatibilidade, essas APIs ainda são convertidas apenas de e para UTF-8 e não para a página de código definida via setlocale.

Para usar esse recurso em um sistema operacional anterior ao Windows 10, você deve utilizar a implantação local do aplicativo ou o link estaticamente usando a versão 1803 (10.0.17134.0) do SDK do Windows ou posteriores. Para sistemas operacionais do Windows 10 anteriores à versão 1803 (10.0.17134.0), há suporte apenas para a vinculação estática.

Requisitos

Rotina	Cabeçalho necessário
`setlocale`	`<locale.h>`
`_wsetlocale`	`<locale.h>` ou `<wchar.h>`

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

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

Confira também

Nomes de localidade, idiomas e cadeias de caracteres de país/região
_configthreadlocale
_create_locale, _wcreate_locale
Localidade
localeconv
_mbclen, mblen, _mblen_l
strlen, , , , wcslen, _mbslen_mbslen_l_mbstrlen_mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
Funções strcoll
strftime, , , wcsftime_strftime_l_wcsftime_l
strxfrm, , , wcsxfrm_strxfrm_l_wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l

setlocale, _wsetlocale

Sintaxe

Parâmetros

Valor retornado

Comentários

Mapeamentos de rotina de texto genérico

Suporte para UTF-8

Requisitos

Exemplo

Confira também

Comentários

Comentários

Recursos adicionais

`setlocale`, `_wsetlocale`