setlocale, _wsetlocale

Establezca o recupere la configuración regional en tiempo de ejecución.

Sintaxis

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

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

Parámetros

category
Categoría afectada por la configuración regional.

locale
Especificador de la configuración regional.

Valor devuelto

Si se especifica un valor válido locale y category , las funciones devuelven un puntero a la cadena asociada con el especificado locale y category. Si el locale argumento es NULL, las funciones devuelven la configuración regional actual.

Si se pasa un argumento no válido a cualquiera de las funciones, el valor devuelto es NULL. El comportamiento de los argumentos no válidos es el siguiente:

La llamada:

setlocale( LC_ALL, "en-US" );

establece todas las categorías y devuelve solo la cadena

en-US

Puede copiar la cadena devuelta por setlocale para restaurar esa parte de la información de configuración regional del programa. Para la cadena devuelta por setlocale se usa almacenamiento local de subprocesos o global. Las llamadas posteriores a setlocale sobrescriben la cadena, lo que invalida los punteros de cadena devueltos por llamadas anteriores.

Comentarios

Use la función de setlocale para establecer, cambiar o consultar, en parte o en su totalidad, la información de configuración regional del programa actual especificada por locale y category. locale hace referencia al lugar (país o región, e idioma) para el que se pueden personalizar algunos aspectos del programa. Entre las categorías dependientes de la configuración regional se encuentran el formato de fechas y el formato de presentación de valores de moneda. Si se establece locale en la cadena predeterminada para un idioma que tiene varios formatos admitidos en el equipo, debe observar el valor devuelto de setlocale para ver qué idioma se está usando. Por ejemplo, si establece locale en "chinese" el valor devuelto podría ser "chinese-simplified" o "chinese-traditional".

_wsetlocale es una versión con caracteres anchos de setlocale; el argumento de locale y el valor devuelto de _wsetlocale son cadenas de caracteres anchos. Por lo demás,_wsetlocale y setlocale se comportan de forma idéntica.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

El argumento de category especifica las partes de la información de configuración regional del programa afectadas. Las macros utilizadas para category y las partes del programa a las que afectan son las siguientes:

Esta función valida el parámetro de categoría. Si el parámetro category no es uno de los valores especificados en la tabla anterior, se invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, la función establece errno en EINVAL y devuelve NULL.

El argumento de locale es un puntero a una cadena que especifica la configuración regional. Para obtener información sobre el formato del locale argumento, vea Nombres de configuración regional, idiomas y cadenas de país o región. Si locale señala a una cadena vacía, la configuración regional es el entorno nativo definido por la implementación. Un valor de C especifica el entorno compatible con ANSI mínimo para la conversión de C. La configuración regional de C supone que todos los tipos de datos char son de 1 byte y que su valor es siempre menor que 256.

Durante el inicio del programa, se ejecuta el equivalente de la instrucción siguiente:

setlocale( LC_ALL, "C" );

El argumento de locale puede tomar un nombre de configuración regional, una cadena de idioma, una cadena de idioma y un código de país o región, una página de códigos, o una cadena de idioma, un código de país o región y una página de códigos. Los nombres de configuración regional disponibles, los idiomas, los códigos de país o región y las páginas de códigos incluyen todos los admitidos por la API NLS de Windows. El conjunto de nombres de configuración regional admitidos por setlocale se describe en Nombres de configuración regional, Idiomas y Cadenas de país o región. El conjunto de cadenas de idioma y país o región compatibles setlocale con se enumeran en Cadenas de idioma y Cadenas de país o región. Se recomienda emplear el formato del nombre de la configuración regional para mejorar el rendimiento y simplificar el mantenimiento de las cadenas de configuración regional insertadas en código o serializadas en el almacenamiento. Es menos probable que una actualización del sistema operativo cambie las cadenas de nombre de configuración regional que el formato de nombre de idioma y de país o región.

Un puntero null que se pasa como argumento de locale indica a setlocale que consulte el entorno internacional en lugar de establecerlo. Si el argumento de locale es un puntero nulo, la configuración regional actual del programa no cambia. En lugar de ello, setlocale devuelve un puntero a la cadena asociada al parámetro category de la configuración regional actual del subproceso. Si el argumento category es LC_ALL, la función devuelve una cadena que indica la configuración actual de cada categoría, separadas por punto y coma. Por ejemplo, la secuencia de llamadas

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

que es la cadena asociada a la categoría de LC_ALL.

Los ejemplos siguientes corresponden a la categoría de LC_ALL. Se puede usar la cadena ".OCP" o la cadena ".ACP" en lugar de un número de página de códigos para especificar que se usen la página de códigos OEM predeterminada del usuario y la página de códigos ANSI predeterminada del usuario para ese nombre de configuración regional, respectivamente.

• setlocale( LC_ALL, "" );

  Establece la configuración regional en el valor predeterminado, que es la página de códigos ANSI predeterminada del usuario obtenida del sistema operativo. El nombre de la configuración regional se establece en el valor que devuelve GetUserDefaultLocaleName. La página de códigos se establece en el valor que devuelve GetACP.

• setlocale( LC_ALL, ".OCP" );

  Establece la configuración regional en la página de códigos OEM actual que se obtiene del sistema operativo. El nombre de la configuración regional se establece en el valor que devuelve GetUserDefaultLocaleName. La página de códigos se establece en el valor LOCALE_IDEFAULTCODEPAGE del nombre de configuración regional predeterminado del usuario por GetLocaleInfoEx.

• setlocale( LC_ALL, ".ACP" );

  Establece la configuración regional en la página de códigos ANSI obtenida del sistema operativo. El nombre de la configuración regional se establece en el valor que devuelve GetUserDefaultLocaleName. La página de códigos se establece en el valor LOCALE_IDEFAULTANSICODEPAGE del nombre de configuración regional predeterminado del usuario por GetLocaleInfoEx.

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

  Establece la configuración regional en el nombre de configuración regional que se indica mediante <localename>. La página de códigos se establece en el valor LOCALE_IDEFAULTANSICODEPAGE para el nombre de configuración regional especificado por GetLocaleInfoEx.

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

  Establece la configuración regional en el idioma y el país o región que indican <language> y <country>, junto con la página de códigos predeterminada obtenida del sistema operativo host. La página de códigos se establece en el valor LOCALE_IDEFAULTANSICODEPAGE para el nombre de configuración regional especificado por GetLocaleInfoEx.

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

  Establece la configuración regional en el idioma, país o región y página de códigos indicados por las cadenas <language>, <country> y <code_page>. Puede utilizar distintas combinaciones de idioma, país o región y página de códigos. Por ejemplo, esta llamada establece la configuración regional en francés de Canadá con la página de códigos 1252:

  setlocale( LC_ALL, "French_Canada.1252" );

  Esta llamada establece la configuración regional en francés de Canadá con la página de códigos ANSI predeterminada:

  setlocale( LC_ALL, "French_Canada.ACP" );

  Esta llamada establece la configuración regional en francés de Canadá con la página de códigos OEM predeterminada:

  setlocale( LC_ALL, "French_Canada.OCP" );

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

  Establece la configuración regional en el idioma que se indica mediante <language>, y utiliza el país o región predeterminados para el idioma especificado, además de la página de códigos ANSI predeterminada del usuario para ese país o región, tal y como se obtiene del sistema operativo del host. Por ejemplo, las siguientes llamadas a setlocale son equivalentes:

  setlocale( LC_ALL, "en-US" );

  setlocale( LC_ALL, "English" );

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

  Se recomienda usar el primer formato para mejorar el rendimiento y el mantenimiento.

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

  Establece la página de códigos en el valor indicado por <code_page>, junto con el país o región y el idioma predeterminados (definidos por el sistema operativo host) para la página de códigos especificada.

La categoría debe ser LC_ALL o LC_CTYPE para que cambie la página de códigos. Por ejemplo, si el país o región y el idioma predeterminados del sistema operativo del host son "United States" y "English", las dos llamadas siguientes a setlocale son equivalentes desde el punto de vista funcional:

setlocale( LC_ALL, ".1252" );

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

Para obtener más información, vea la directiva pragma setlocale en la Referencia del preprocesador de C/C++.

La función _configthreadlocale se usa para controlar si setlocale afecta a la configuración regional de todos los subprocesos de un programa o solo a la configuración regional del subproceso de llamada.

Compatibilidad con UTF-8

A partir de Windows 10 versión 1803 (10.0.17134.0), el tiempo de ejecución de C universal admite el uso de páginas con codificación UTF-8. El cambio significa que char las cadenas que se pasan a las funciones en tiempo de ejecución de C pueden esperar cadenas en la codificación UTF-8. Para habilitar el modo UTF-8, use ".UTF8" como página de códigos al usar setlocale. Por ejemplo, setlocale(LC_ALL, ".UTF8") usa la página de códigos ANSI de Windows (ACP) predeterminada actual para la configuración regional y UTF-8 para la página de códigos.

La cadena para especificar el modo UTF-8 es:

• No distingue mayúsculas de minúsculas.
• el guión (-) es opcional
• Debe estar en la parte de la página de códigos del nombre de la configuración regional, por lo que debe tener un punto inicial (.) como se muestra en estos ejemplos: "en_US.UTF8" o ".utf8"

En los ejemplos siguientes se muestra cómo especificar el la cadena UTF-8:

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

Después de llamar setlocale(LC_ALL, ".UTF8")a , puede pasar "😊" a mbtowcs y se traducirá correctamente a una wchar_t cadena. Anteriormente, no había una configuración regional disponible para realizar esta traducción.

El modo UTF-8 también está habilitado para funciones que tienen cadenas char traducidas históricamente mediante la página de códigos ANSI de Windows (ACP) predeterminada. Por ejemplo, al llamar a _mkdir("😊") mientras se usa una página de códigos UTF-8, se generará correctamente un directorio con ese emoji como nombre de carpeta, en lugar de requerir que el ACP se cambie a UTF-8 antes de ejecutar el programa. Del mismo modo, llamar a _getcwd() en esa carpeta devuelve una cadena codificada UTF-8. Por motivos de compatibilidad, el ACP se sigue usando si la página de códigos de configuración regional de C no está establecida en UTF-8.

Los aspectos del tiempo de ejecución de C que se indican a continuación no pueden usar UTF-8 porque se establecen durante el inicio del programa y deben usar la página de códigos ANSI predeterminada de Windows (ACP): __argv, _acmdln y _pgmptr.

Antes de esta compatibilidad, mbrtoc16, mbrtoc32, c16rtomb y c32rtomb existían para traducir entre cadenas estrechas UTF-8, UTF-16 (misma codificación que wchar_t en plataformas Windows) y UTF-32. Por motivos de compatibilidad, estas API se siguen traduciendo solo se traducen a UTF-8 y desde esta codificación, y no a la página de códigos establecida a través de setlocale.

Para usar esta característica en un sistema operativo antes de Windows 10, debe usar la implementación local de la aplicación o vincular estáticamente mediante la versión 1803 (10.0.17134.0) de Windows SDK o posterior. Para sistemas operativos Windows 10 anteriores a la versión 1803 (10.0.17134.0), solo se admite la vinculación estática.

Requisitos

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

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

Vea también

Nombres de configuración regional, idiomas y cadenas de país o región
_configthreadlocale
_create_locale, _wcreate_locale
Configuración regional
localeconv
_mbclen, , mblen, _mblen_l
strlen, wcslen, _mbslen, _mbslen_l, , _mbstrlen, _mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
Funciones strcoll
strftime, wcsftime, , _strftime_l, _wcsftime_l
strxfrm, wcsxfrm, , _strxfrm_l, _wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l