setlocale, _wsetlocale

Artículo
04/10/2013

El conjunto o recuperar la configuración regional en tiempo de ejecución.

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

Parámetros

category
Categoría afectados por la configuración regional.
locale
Especificador de la configuración regional.

Valor devuelto

Si se proporciona locale válido y category, devuelve un puntero a la cadena asociada a locale especificado y a category.Si locale o category no es válido, devuelve un puntero NULL y configuraciones regionales actuales del programa no se cambian.

Por ejemplo, la llamada

setlocale( LC_ALL, "en-US" );

establece todas las categorías, devolviendo sólo la cadena

en-US

Puede utilizar el puntero de la cadena devuelta por setlocale en llamadas subsiguientes para restaurar esa parte de la información de la configuración regional del programa, suponiendo que el programa no modifica el puntero o la cadena.Llamadas posteriores a setlocale sobrescriben la cadena, que crea los punteros de la cadena devueltos por llamadas anteriores ya no válidos.Puede utilizar _strdup para guardar una copia de una cadena específica de la configuración regional.

Comentarios

Utilice la función de setlocale para establecer, para cambiar, o para ver alguna o toda 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 y lenguaje) para el que se puede 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 locale establecido en la cadena predeterminada para un lenguaje con varios formatos admitidos en el equipo, se comprueba el código de retorno de setlocale para ver qué lenguaje está vigente.Por ejemplo, utilizando “chino” podría producir un valor devuelto de chinese-simplified o de 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._wsetlocale y setlocale se comportan exactamente igual de otra manera.

Asignaciones de la rutina de Genérico- texto

Rutina de TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tsetlocale	setlocale	setlocale	_wsetlocale

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

LC_ALL
Todas las categorías, como se indica a continuación.
LC_COLLATE
strcoll, _stricoll, wcscoll, _wcsicoll, strxfrm, _strncoll, _strnicoll, _wcsncoll, _wcsnicoll, y funciones de wcsxfrm.
LC_CTYPE
Las funciones carácter- que administran (excepto isdigit, isxdigit, mbstowcs, y mbtowc, que no son afectado).
LC_MONETARY
Información de Monetario- formato devuelta por la función de localeconv.
LC_NUMERIC
Carácter de separador decimal para las rutinas con formato de salida (como printf), para las rutinas de conversión de datos, e información no monetaria de formato devuelta por localeconv. Además del carácter del separador decimal, LC_NUMERIC también establece el separador de miles y la cadena del control de agrupación devueltos por localeconv.
LC_TIME
Las funciones de strftime y de wcsftime.

Esta función valida el parámetro category.Si el parámetro category no es uno de los valores especificados en la tabla anterior, se invoca el controlador no válido de parámetro, tal y como se describe en Validación de parámetros.Si la ejecución puede continuar, la función establece errno a 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 argumento de locale, vea Nombres de configuración regional, idiomas y cadenas de país/región.Si los puntos de locale en una cadena vacía, la configuración regional son el entorno nativo implementación- definido.Un valor de C especifica ANSI mínimo que cumple el entorno para la conversión de C.La configuración regional de C se supone que todos los tipos de datos de char son 1 byte y que su valor siempre es menor que 256.

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

setlocale( LC_ALL, "C" );

El argumento de locale puede tomar un nombre de la configuración regional, una cadena de idioma, una cadena de idioma y un país o código de región, una página de códigos, o una cadena de idioma, un país o un código de región, y una página de códigos.El conjunto de nombres disponibles, de lenguajes, de país o códigos de región, y páginas de códigos de la configuración regional incluye todo el los admitidos por Windows NLS API excepto las páginas de códigos que requieren más de dos bytes por carácter, como UTF-7 y UTF-8.Si proporciona una página de códigos como UTF-7 o UTF-8, setlocale producirá un error, devuelve NULL.Describe el conjunto de nombres de la configuración regional admitidos por setlocale en Nombres de configuración regional, idiomas y cadenas de país/región.Muestran el conjunto de cadenas de idioma de país o región admitidas por setlocale en Cadenas de idioma y Cadenas de país o región.

Un puntero NULL pasado como argumento de locale indica a setlocale que vea en lugar del entorno internacional.Si el argumento de locale es un puntero NULL, la configuración regional actual del programa no cambia.En su lugar, setlocale devuelve un puntero a la cadena asociada a category de la configuración regional actual del subproceso.Si el argumento de category es LC_ALL, la función devuelve una cadena que indica la configuración actual de cada una de las categorías, separados 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));

devuelve

LC_COLLATE=en-US;LC_CTYPE=en-US;LC_MONETARY=fr-FR;LC_NUMERIC=en-US;LC_TIME=en-US

qué es la cadena asociada a la categoría de LC_ALL.

Los ejemplos siguientes pertenecen a la categoría de LC_ALL.Cualquiera de las cadenas “.OCP” y “.ACP” se puede utilizar en lugar de un número de la página de códigos para especificar el uso de las páginas de códigos OEM de usuario- predeterminado y de códigos ANSI del usuario- predeterminado, respectivamente.

setlocale( LC_ALL, "" );
Establece la configuración regional en el valor predeterminado, que es la página de códigos ANSI del usuario- predeterminado obtenida del sistema operativo.
setlocale( LC_ALL, ".OCP" );
Establece explícitamente la configuración regional en la página de códigos OEM actual obtenida del sistema operativo.
setlocale( LC_ALL, ".ACP" );
Establece la configuración regional en la página de códigos ANSI obtenida del sistema operativo.
setlocale( LC_ALL, "<localename>" );
Establece la configuración regional en el nombre de la configuración regional indicado por <localename>.
setlocale( LC_ALL, "<language>_<country>" );
Establece la configuración regional el idioma y el país o región indicada por <language> y <country>, en la página de códigos predeterminada obtenida del sistema operativo host.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );
Establece la configuración regional al idioma, el país o región, y la página de códigos indicada por <language>, <country>, y las cadenas de <code_page>.Puede utilizar diferentes combinaciones de idioma, de país o región, y de página de códigos.Por ejemplo:
```
setlocale( LC_ALL, "French_Canada.1252" );
// Set code page to French Canada ANSI default
setlocale( LC_ALL, "French_Canada.ACP" );
// Set code page to French Canada OEM default
setlocale( LC_ALL, "French_Canada.OCP" );
```
setlocale( LC_ALL, "<language>" );
Establece la configuración regional en lenguaje indicado por <language>, utilizando el país o región predeterminados para el idioma especificado, y la página de códigos ANSI del usuario- predeterminado para ese país/región tal y como se obtiene del sistema operativo host.Por ejemplo, las llamadas siguientes a setlocale son funcionalmente equivalentes:
```
setlocale( LC_ALL, "en-US" );
setlocale( LC_ALL, "English" );
setlocale( LC_ALL, "English_United States.1252" );
```
setlocale( LC_ALL, ".<code_page>" );
Establece la página de códigos en el valor indicado por <code_page>, utilizando el país o región y el idioma predeterminados (definido por el sistema operativo host) para la página de códigos especificada.

La categoría debe ser LC_ALL o LC_CTYPE el efecto un cambio de página de códigos.Por ejemplo, si el país o región y el lenguaje predeterminado del sistema operativo host son “united states” y “inglés,” las dos llamadas siguientes a setlocale son funcionalmente equivalentes:

setlocale( LC_ALL, ".1252" );

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

Para obtener más información vea pragma setlocale en la referencia del preprocesador.

La función _configthreadlocale se utiliza 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.

Requisitos

Rutina	Encabezado necesario
setlocale	<locale.h>
_wsetlocale	<locale.h> o <wchar.h>

Para obtener información adicional de compatibilidad, vea Compatibilidad en la Introducción.

Ejemplo

// crt_setlocale.cpp
// 
// 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 and time in the current
// locale's format.
int get_time(unsigned char* str)
{
    __time64_t ltime;
    struct tm  thetime;

    // Retieve the time
    _time64(&ltime);
    _gmtime64_s(&thetime, &ltime);

    // Format the current time structure into a string
    // using %#x is the long date representation,
    // appropriate to 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 German
// and prints the time.
unsigned __stdcall SecondThreadFunc( void* pArguments )
{
    unsigned char str[BUFF_SIZE];

    // Set the thread local
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, "de-DE"));

    // Retrieve the time string from the helper function
    if (get_time(str) == 0)
    {
        printf("The time in de-DE locale is: '%s'\n", str);
    }

    _endthreadex( 0 );
    return 0;
} 

// The main thread spawns a second thread (above) and then
// sets the locale to English and prints the time.
int main()
{ 
    HANDLE          hThread;
    unsigned        threadID;
    unsigned char   str[BUFF_SIZE];

    // Configure per-thread locale to cause all subsequently created 
    // threads to have their own locale.
    _configthreadlocale(_ENABLE_PER_THREAD_LOCALE);

    // Retrieve the time string from the helper function
    printf("The thread locale is now set to %s.\n",
           setlocale(LC_ALL, "en-US"));

    // Create the second thread.
    hThread = (HANDLE)_beginthreadex( NULL, 0, &SecondThreadFunc,
                                      NULL, 0, &threadID );

    if (get_time(str) == 0)
    {
        // Retrieve the time string from the helper function
        printf("The time 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 );
}