`setlocale`, `_wsetlocale`

Articolo
01/10/2024

Impostare o recuperare le impostazioni locali di runtime.

Sintassi

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

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

Parametri

category
Categoria influenzata dalle impostazioni locali.

locale
Identificatore delle impostazioni locali.

Valore restituito

Se viene specificato un valore valido locale e category , le funzioni restituiscono un puntatore alla stringa associata all'oggetto specificato locale e category. Se l'argomento locale è NULL, le funzioni restituiscono le impostazioni locali correnti.

Se a una delle due funzioni viene passato un argomento non valido, il valore restituito è NULL. Il comportamento per gli argomenti non validi è il seguente:

Funzione	Parametro non valido	Gestore non valido richiamato come descritto in Convalida dei parametri	Imposta `errno`
`setlocale`	`category`	yes	sì
`setlocale`	`locale`	no	no
`_wsetlocale`	`category`	yes	sì
`_wsetlocale`	`locale`	no	no

La chiamata:

setlocale( LC_ALL, "en-US" );

imposta tutte le categorie, restituendo solo la stringa

en-US

È possibile copiare la stringa restituita da setlocale per ripristinare la parte delle impostazioni locali del programma. Per la stringa restituita da setlocale viene utilizzata l'archiviazione globale o locale dei thread. Le chiamate successive a setlocale sovrascrivono la stringa, operazione che rende non più validi i puntatori di stringa restituiti dalle chiamate precedenti.

Osservazioni:

Utilizzare la funzione setlocale per impostare, modificare o eseguire query su alcune o tutte le informazioni sulle impostazioni locali del programma corrente specificate da locale e category. locale fa riferimento alla località (paese e lingua) per cui è possibile personalizzare alcuni aspetti del programma. Alcune categorie dipendenti dalle impostazioni locali includono la formattazione delle date e il formato di visualizzazione dei valori monetari. Se si imposta locale sulla stringa predefinita per una lingua con più forme supportate nel computer, controllare il valore restituito di setlocale per sapere quale lingua è attiva. Ad esempio, se si imposta locale"chinese" sul valore restituito può essere "chinese-simplified" o "chinese-traditional".

_wsetlocale è una versione a caratteri wide di setlocale. L'argomento locale e il valore restituito da _wsetlocale è dato da stringhe a caratteri wide. In caso contrario,_wsetlocale e setlocale si comportano in modo identico.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

`TCHAR.H` Routine	`_UNICODE` e `_MBCS` non definito	`_MBCS` Definito	`_UNICODE` Definito
`_tsetlocale`	`setlocale`	`setlocale`	`_wsetlocale`

L'argomento category specifica le parti interessate delle informazioni sulle impostazioni locali di un programma. Le macro utilizzate per category e le parti del programma interessate sono le seguenti:

Flag di`category`	Impatto
`LC_ALL`	Tutte le categorie, come indicato di seguito.
`LC_COLLATE`	Le funzioni `strcoll`, `_stricoll`, `wcscoll`, `_wcsicoll`, `strxfrm`, `_strncoll`, `_strnicoll`, `_wcsncoll`, `_wcsnicoll` e `wcsxfrm`.
`LC_CTYPE`	Le funzioni di gestione dei caratteri, ad eccezione di `isdigit`, `isxdigit`, `mbstowcs` e `mbtowc` che non sono interessate.
`LC_MONETARY`	Informazioni di formattazione monetaria restituite dalla funzione `localeconv`.
`LC_NUMERIC`	Carattere in virgola decimale per le routine di output formattate (ad esempio `printf`), per le routine di conversione dei dati e per le informazioni di formattazione nonmonetary restituite da `localeconv`. Oltre al carattere decimale, `LC_NUMERIC` imposta il separatore delle migliaia e la stringa di controllo di raggruppamento restituita da `localeconv`.
`LC_TIME`	Funzioni `strftime` e `wcsftime`.

Questa funzione convalida il parametro di categoria. Se il parametro category non è uno dei valori specificati nella tabella precedente, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione imposta errno su EINVAL e restituisce NULL.

L'argomento locale è un puntatore a una stringa che specifica le impostazioni locali. Per informazioni sul formato dell'argomento locale , vedere Nomi delle impostazioni locali, Lingue e Stringhe paese/area geografica. Se locale punta a una stringa vuota, le impostazioni locali corrispondono all'ambiente nativo definito in fase di implementazione. Un valore di C specifica l'ambiente conforme ad ANSI per la conversione C. Le impostazioni locali di C presuppongono che tutti i tipi di dati char siano di 1 byte e che il relativo valore sia sempre minore di 256.

All'avvio del programma, viene eseguito l'equivalente dell'istruzione seguente:

setlocale( LC_ALL, "C" );

L'argomento locale può accettare un nome delle impostazioni locali, una stringa di lingua, una stringa di lingua e un codice paese, una tabella codici o una stringa di lingua, un codice paese e una tabella codici. I nomi delle impostazioni locali, le lingue, i codici paese/area geografica disponibili e le tabelle codici includono tutti quelli supportati dall'API NLS di Windows. Il set di nomi delle impostazioni locali supportati da setlocale è descritto in Nomi delle impostazioni locali, Lingue e Stringhe paese/area geografica. Il set di stringhe di lingua e paese/area geografica supportate da setlocale è elencato in Stringhe di lingua e stringhe paese/area geografica. Ai fini delle prestazioni e delle manutenibilità delle stringhe delle impostazioni locali, è consigliabile incorporare il nome delle impostazioni locali nel codice o serializzarlo nell'archiviazione. È più probabile che in seguito a un aggiornamento del sistema operativo venga modificato il formato del nome della lingua e del paese e non le stringhe del nome delle impostazioni locali.

Un puntatore Null passato come argomento locale indica a setlocale di eseguire query anziché impostare l'ambiente internazionale. Se l'argomento locale è un puntatore Null, l'impostazione delle impostazioni locali correnti del programma non viene modificata. Al contrario, setlocale restituisce un puntatore alla stringa associata alla category delle impostazioni locali correnti del thread. Se l'argomento category è LC_ALL, la funzione restituisce una stringa che indica l'impostazione corrente di tutte le categorie, separate da punti e virgola. Ad esempio, la sequenza di chiamate

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

restituisce

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

che è la stringa associata alla categoria LC_ALL.

Gli esempi seguenti riguardano la categoria LC_ALL. Una delle stringhe ". OCP" e ". ACP" può essere usato invece di un numero di tabella codici per specificare rispettivamente l'uso della tabella codici OEM predefinita dell'utente e della tabella codici ANSI predefinita per tale nome delle impostazioni locali.

setlocale( LC_ALL, "" );

Imposta le impostazioni locali sui valori predefiniti, ovvero la tabella codici ANSI predefinita dell'utente ottenuta dal sistema operativo. Il nome delle impostazioni locali è impostato sul valore restituito da GetUserDefaultLocaleName. La tabella codici è impostata sul valore restituito da GetACP.
setlocale( LC_ALL, ".OCP" );

Imposta le impostazioni locali sulla tabella codici OEM corrente ottenuta dal sistema operativo. Il nome delle impostazioni locali è impostato sul valore restituito da GetUserDefaultLocaleName. La tabella codici è impostata sul LOCALE_IDEFAULTCODEPAGE valore per il nome delle impostazioni locali predefinite dell'utente in GetLocaleInfoExbase a .
setlocale( LC_ALL, ".ACP" );

Imposta le impostazioni locali sulla tabella codici ANSI ottenuta dal sistema operativo. Il nome delle impostazioni locali è impostato sul valore restituito da GetUserDefaultLocaleName. La tabella codici è impostata sul LOCALE_IDEFAULTANSICODEPAGE valore per il nome delle impostazioni locali predefinite dell'utente in GetLocaleInfoExbase a .
setlocale( LC_ALL, "<localename>" );

Imposta le impostazioni locali sul nome delle impostazioni locali indicato da <localename>. La tabella codici è impostata sul valore per il LOCALE_IDEFAULTANSICODEPAGE nome delle impostazioni locali specificato da GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>" );

Imposta le impostazioni locali sulla lingua e il paese/area geografica indicati da <language> e <country>, insieme alla tabella codici predefinita ottenuta dal sistema operativo host. La tabella codici è impostata sul valore per il LOCALE_IDEFAULTANSICODEPAGE nome delle impostazioni locali specificato da GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );

Imposta le impostazioni locali sulla lingua, il paese o l'area geografica e la <language>tabella codici indicate dalle stringhe , <country>e <code_page> . È possibile utilizzare varie combinazioni di lingua, paese e tabella codici. Questa chiamata imposta ad esempio le impostazioni locali sulla lingua francese del Canada con la tabella codici 1252:

setlocale( LC_ALL, "French_Canada.1252" );

Questa chiamata imposta le impostazioni locali sulla lingua francese del Canada con la tabella codici ANSI predefinita:

setlocale( LC_ALL, "French_Canada.ACP" );

Questa chiamata imposta le impostazioni locali sulla lingua francese del Canada con la tabella codici OEM predefinita:

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

Imposta le impostazioni locali sulla lingua indicata da <language>e usa il paese/area geografica predefinito per la lingua specificata e la tabella codici ANSI predefinita dell'utente per il paese o l'area geografica ottenuta dal sistema operativo host. Ad esempio, le chiamate a setlocale seguenti sono equivalenti a livello funzionale:

setlocale( LC_ALL, "en-US" );

setlocale( LC_ALL, "English" );

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

Ai fini delle prestazioni e della manutenibilità, è consigliabile utilizzare la prima forma.
setlocale( LC_ALL, ".<code_page>" );

Imposta la tabella codici sul valore indicato da <code_page>, insieme al paese/area geografica e alla lingua predefiniti (come definito dal sistema operativo host) per la tabella codici specificata.

La categoria deve essere LC_ALL o LC_CTYPE per rendere effettiva una modifica della tabella codici. Ad esempio, se il paese/area geografica e la lingua predefiniti del sistema operativo host sono "United States" e "English", le due chiamate seguenti a setlocale sono equivalenti a livello funzionale:

setlocale( LC_ALL, ".1252" );

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

Per altre informazioni, vedere la setlocale direttiva pragma nella Guida di riferimento al preprocessore C/C++.

La funzione _configthreadlocale viene utilizzata per controllare se setlocale influisce sulle impostazioni locali di tutti i thread in un programma o solo sulle impostazioni locali del thread chiamante.

Supporto UTF-8

A partire da Windows 10 versione 1803 (10.0.17134.0), Universal C Runtime supporta l'uso di una tabella codici UTF-8. La modifica indica che char le stringhe passate alle funzioni di runtime C possono prevedere stringhe nella codifica UTF-8. Per abilitare la modalità UTF-8, usare ".UTF8" come tabella codici quando si usa setlocale. Ad esempio, setlocale(LC_ALL, ".UTF8") usa la tabella codici PREDEFINITa corrente di Windows ANSI (ACP) per le impostazioni locali e UTF-8 per la tabella codici.

La stringa per specificare la modalità UTF-8 è:

non fa distinzione tra maiuscole e minuscole
il trattino (-) è facoltativo
Deve trovarsi nella parte della tabella codici del nome delle impostazioni locali, quindi deve avere un punto iniziale (.) come negli esempi seguenti: "en_US.UTF8" o ".utf8"

Gli esempi seguenti illustrano come specificare la stringa UTF-8:

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

Dopo aver chiamato setlocale(LC_ALL, ".UTF8"), è possibile passare "😊" a mbtowcs e verrà convertito correttamente in una wchar_t stringa. In precedenza non era disponibile un'impostazione delle impostazioni locali per eseguire questa traduzione.

La modalità UTF-8 è abilitata anche per le funzioni che hanno storicamente convertito char stringhe usando la tabella codici PREDEFINITa di Windows ANSI (ACP). Ad esempio, la chiamata _mkdir("😊") durante l'uso di una tabella codici UTF-8 produrrà correttamente una directory con tale emoji come nome della cartella, invece di richiedere che l'ACP venga modificato in UTF-8 prima di eseguire il programma. Analogamente, la chiamata _getcwd() in tale cartella restituisce una stringa con codifica UTF-8. Per la compatibilità, l'ACP viene ancora usato se la tabella codici delle impostazioni locali C non è impostata su UTF-8.

Gli aspetti seguenti del runtime C non possono usare UTF-8 perché vengono impostati durante l'avvio del programma e devono usare la tabella codici PREDEFINITa di Windows ANSI (ACP): __argv, _acmdlne _pgmptr.

Precedentemente a questo supporto, , mbrtoc16mbrtoc32,c16rtomb e c32rtomb esisteva per la conversione tra stringhe strette UTF-8, UTF-16 (stessa codifica delle wchar_t piattaforme Windows) e UTF-32. Per motivi di compatibilità, queste API vengono comunque convertite solo in e da UTF-8 e non dalla tabella codici impostata tramite setlocale.

Per usare questa funzionalità in un sistema operativo precedente a Windows 10, è necessario usare la distribuzione locale dell'app o il collegamento in modo statico usando la versione 1803 (10.0.17134.0) di Windows SDK o versioni successive. Per i sistemi operativi Windows 10 precedenti alla versione 1803 (10.0.17134.0), è supportato solo il collegamento statico.

Requisiti

Ciclo	Intestazione obbligatoria
`setlocale`	`<locale.h>`
`_wsetlocale`	`<locale.h>` oppure `<wchar.h>`

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

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

Vedi anche

Nomi delle impostazioni locali, lingue e stringhe paese/area geografica
_configthreadlocale
_create_locale, _wcreate_locale
impostazioni locali
localeconv
_mbclen, mblen, _mblen_l
strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen_mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
Funzioni strcoll
strftime, wcsftime, _strftime_l_wcsftime_l
strxfrm, wcsxfrm, _strxfrm_l_wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l

`setlocale`, `_wsetlocale`

Sintassi

Parametri

Valore restituito

Osservazioni:

Mapping di routine di testo generico

Supporto UTF-8

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

setlocale, _wsetlocale

Sintassi

Parametri

Valore restituito

Osservazioni:

Mapping di routine di testo generico

Supporto UTF-8

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

`setlocale`, `_wsetlocale`