`setlocale`, `_wsetlocale`

Article
01/04/2024

Définissez ou récupérez les paramètres régionaux d’exécution.

Syntaxe

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

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

Paramètres

category
Catégorie affectée par les paramètres régionaux.

locale
Spécificateur de paramètres régionaux.

Valeur retournée

Si une valeur est valide locale et category donnée, les fonctions retournent un pointeur vers la chaîne associée à l’élément spécifié locale et category. Si l’argument locale est NULL, les fonctions retournent les paramètres régionaux actuels.

Si un argument non valide est passé à l’une ou l’autre des fonctions, la valeur de retour est NULL. Le comportement des arguments non valides est le suivant :

Fonction	Paramètre non valide	Gestionnaire non valide appelé comme décrit dans la validation des paramètres	Studios `errno`
`setlocale`	`category`	Oui	oui
`setlocale`	`locale`	non	non
`_wsetlocale`	`category`	oui	oui
`_wsetlocale`	`locale`	non	non

L'appel :

setlocale( LC_ALL, "en-US" );

définit toutes les catégories, en retournant uniquement la chaîne

en-US

Vous pouvez copier la chaîne retournée par setlocale pour restaurer cette partie des informations relatives aux paramètres régionaux du programme. Un stockage local des threads ou un stockage global est utilisé pour la chaîne retournée par setlocale. Les appels ultérieurs à setlocale remplacent la chaîne, ce qui rend les pointeurs de chaîne retournés par les appels antérieurs non valides.

Notes

Utilisez la fonction setlocale pour définir, modifier, ou interroger certaines ou toutes les informations de paramètres régionaux du programme actif spécifié par locale et category. locale fait référence à la localité (pays/région et langue) pour laquelle vous pouvez personnaliser certains aspects du programme. Certaines catégories dépendent des paramètres régionaux, notamment la mise en forme des dates et le format d'affichage des valeurs monétaires. Si vous affectez le paramètre locale à la chaîne par défaut pour une langue qui a plusieurs formes prises en charge sur votre ordinateur, vous devrez d'abord vérifier la valeur de retour de setlocale pour connaître la langue appliquée. Par exemple, si vous définissez "chinese"locale sur la valeur de retour peut être l’une ou l’autre "chinese-simplified""chinese-traditional".

_wsetlocale est une version à caractères larges de setlocale; l’argument locale et la valeur de retour de _wsetlocale sont des chaînes à caractères larges. Sinon,_wsetlocale et setlocale se comportent de la même façon.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Mappages de routine de texte générique

`TCHAR.H` Routine	`_UNICODE` et `_MBCS` non défini	`_MBCS` Défini	`_UNICODE` Défini
`_tsetlocale`	`setlocale`	`setlocale`	`_wsetlocale`

L'argument category spécifie les parties des informations relatives aux paramètres régionaux d'un programme qui sont affectées. Les macros utilisées pour category et les parties du programme qu'elles affectent sont les suivantes :

Indicateur`category`	Éléments affectés
`LC_ALL`	Toutes les catégories, comme indiqué ci-dessous.
`LC_COLLATE`	Les fonctions `strcoll`, `_stricoll`, `wcscoll`, `_wcsicoll`, `strxfrm`, `_strncoll`, `_strnicoll`, `_wcsncoll`, `_wcsnicoll` et `wcsxfrm`.
`LC_CTYPE`	Les fonctions de gestion de caractères (sauf `isdigit`, `isxdigit`, `mbstowcs`, et `mbtowc`, qui ne sont pas affectés).
`LC_MONETARY`	Les informations de mise en forme monétaire retournées par la fonction `localeconv`.
`LC_NUMERIC`	Caractère décimal pour les routines de sortie mises en forme (par exemple `printf`), pour les routines de conversion de données et pour les informations de mise en forme nonmonetaires retournées par `localeconv`. En plus du caractère décimal, `LC_NUMERIC` définit le séparateur de milliers et la chaîne de contrôle de regroupement retournée par `localeconv`.
`LC_TIME`	Les fonctions `strftime` et `wcsftime`.

Cette fonction valide le paramètre de catégorie. Si le paramètre de catégorie n’est pas l’une des valeurs fournies dans le tableau précédent, le gestionnaire de paramètres non valide est appelé, comme décrit dans la validation des paramètres. Si l'exécution est autorisée à se poursuivre, la fonction définit errno avec la valeur EINVAL et retourne NULL.

L'argument locale est un pointeur vers une chaîne qui spécifie les paramètres régionaux. Pour plus d’informations sur le format de l’argument locale , consultez les noms de paramètres régionaux, les langues et les chaînes Pays/Région. Si locale pointe vers une chaîne vide, les paramètres régionaux sont donnés par l'environnement défini lors de l'implémentation. Une valeur de C spécifie l'environnement de conformation minimal ANSI pour la conversion en C. Les paramètres régionaux de C supposent que tous les types de données de char sont de 1 octet et que leur valeur est toujours inférieure à 256.

Au démarrage du programme, l'équivalent de l'instruction suivante est exécuté :

setlocale( LC_ALL, "C" );

L'argument locale peut accepter un nom de paramètres régionaux, une chaîne de langue, une chaîne de langue et un pays/région, une page de codes, ou une chaîne de langue, un pays/région, et une page de codes. Les noms de paramètres régionaux, langues, codes pays/région disponibles et les pages de codes incluent toutes celles prises en charge par l’API NLS Windows. L’ensemble de noms de paramètres régionaux pris en charge est setlocale décrit dans les chaînes De paramètres régionaux, Langues et Pays/Région. L’ensemble de chaînes de langue et de pays/région pris en charge par setlocale sont répertoriés dans les chaînes de langue et les chaînes Country/Region. Nous recommandons d'utiliser la forme de nom des paramètres régionaux pour des questions de performance et de maintenance des chaînes de paramètres régionaux incorporées dans le code ou sérialisées du stockage. Les chaînes de nom des paramètres régionaux sont moins susceptibles d'être modifiées par une mise à niveau du système d'exploitation que la forme de nom de la langue et du pays ou de la région.

Un pointeur null ajouté à l'argument locale indique à setlocale d'interroger au lieu de définir l'environnement international. Si l’argument locale est un pointeur Null, le paramètre de paramètres régionaux actuel du programme n’est pas modifié. À la place, setlocale retourne un pointeur vers la chaîne associée à l'argument category des paramètres régionaux actuels du thread. Si l'argument category est LC_ALL, la fonction retourne une chaîne qui indique le paramètre actuel de chaque catégorie, séparé par des points-virgules. Par exemple, la séquence d'appels

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

renvoie

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

qui est la chaîne associée à la catégorie LC_ALL.

Les exemples suivants appartiennent à la catégorie LC_ALL. L’une des chaînes ». OCP » et « . ACP » peut être utilisé au lieu d’un numéro de page de codes pour spécifier l’utilisation de la page de codes OEM par défaut utilisateur et de la page de codes ANSI par défaut de l’utilisateur pour ce nom de paramètres régionaux, respectivement.

setlocale( LC_ALL, "" );

Définit les paramètres régionaux à la valeur par défaut, qui est la page de codes ANSI utilisateur par défaut obtenue du système d'exploitation. Le nom des paramètres régionaux est défini sur la valeur retournée par GetUserDefaultLocaleName. La page de codes est définie sur la valeur retournée par GetACP.
setlocale( LC_ALL, ".OCP" );

Définit les paramètres régionaux sur la page de codes OEM actuelle obtenue à partir du système d’exploitation. Le nom des paramètres régionaux est défini sur la valeur retournée par GetUserDefaultLocaleName. La page de codes est définie sur la LOCALE_IDEFAULTCODEPAGE valeur du nom de paramètres régionaux par défaut de l’utilisateur par GetLocaleInfoEx.
setlocale( LC_ALL, ".ACP" );

Définit les paramètres régionaux à la page de codes ANSI fournie par le système d'exploitation. Le nom des paramètres régionaux est défini sur la valeur retournée par GetUserDefaultLocaleName. La page de codes est définie sur la LOCALE_IDEFAULTANSICODEPAGE valeur du nom de paramètres régionaux par défaut de l’utilisateur par GetLocaleInfoEx.
setlocale( LC_ALL, "<localename>" );

Définit les paramètres régionaux sur le nom des paramètres régionaux indiqué par <localename>. La page de codes est définie sur la LOCALE_IDEFAULTANSICODEPAGE valeur du nom de paramètres régionaux spécifié par GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>" );

Définit les paramètres régionaux sur la langue et le pays/région indiqués par <language> et <country>, avec la page de codes par défaut obtenue à partir du système d’exploitation hôte. La page de codes est définie sur la LOCALE_IDEFAULTANSICODEPAGE valeur du nom de paramètres régionaux spécifié par GetLocaleInfoEx.
setlocale( LC_ALL, "<language>_<country>.<code_page>" );

Définit les paramètres régionaux sur la langue, le pays/la région et la page de codes indiqués par les chaînes et <code_page> les <language><country>chaînes. Vous pouvez utiliser différentes combinaisons de langues, pays/région et page de codes. Par exemple, cet appel définit les paramètres régionaux à français du Canada avec la page de codes 1252 :

setlocale( LC_ALL, "French_Canada.1252" );

Cet appel définit les paramètres régionaux à français du Canada avec la page de codes ANSI par défaut :

setlocale( LC_ALL, "French_Canada.ACP" );

Cet appel définit les paramètres régionaux à français du Canada avec la page de codes OEM par défaut :

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

Définit les paramètres régionaux sur la langue indiquée par <language>, et utilise le pays/la région par défaut pour la langue spécifiée et la page de codes ANSI par défaut de l’utilisateur pour ce pays/région tel qu’il est obtenu à partir du système d’exploitation hôte. Par exemple, les appels suivants à setlocale sont fonctionnellement équivalents :

setlocale( LC_ALL, "en-US" );

setlocale( LC_ALL, "English" );

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

Nous recommandons la première forme pour des questions de performances et de maintenance.
setlocale( LC_ALL, ".<code_page>" );

Définit la page de codes sur la valeur indiquée par <code_page>, ainsi que le pays/la région par défaut et la langue (tel que défini par le système d’exploitation hôte) pour la page de codes spécifiée.

La catégorie doit être LC_ALL ou LC_CTYPE pour effectuer un changement de page de codes. Par exemple, si le pays/la région par défaut et la langue du système d’exploitation hôte sont «United States » et «English », les deux appels setlocale suivants sont fonctionnellement équivalents :

setlocale( LC_ALL, ".1252" );

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

Pour plus d’informations, consultez la setlocale directive pragma dans la référence du préprocesseur C/C++.

La fonction _configthreadlocale est utilisée pour contrôler si setlocale les paramètres régionaux de tous les threads d’un programme ou uniquement les paramètres régionaux du thread appelant sont affectés.

Prise en charge d’UTF-8

À compter de Windows 10 version 1803 (10.0.17134.0), le runtime C universel prend en charge l’utilisation d’une page de codes UTF-8. La modification signifie que char les chaînes passées aux fonctions runtime C peuvent s’attendre à des chaînes dans l’encodage UTF-8. Pour activer le mode UTF-8, utilisez ".UTF8" la page de codes lors de l’utilisation setlocale. Par exemple, setlocale(LC_ALL, ".UTF8") utilise la page de codes WINDOWS ANSI (ACP) par défaut actuelle pour les paramètres régionaux et UTF-8 pour la page de codes.

La chaîne à spécifier en mode UTF-8 est la suivante :

ne respecte pas la casse
le trait d’union (-) est facultatif
Il doit se trouver dans la partie page de codes du nom des paramètres régionaux. Il doit donc avoir une période de début (.) comme dans ces exemples : "en_US.UTF8" ou ".utf8"

Les exemples suivants montrent comment spécifier la chaîne UTF-8 :

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

Après l’appel setlocale(LC_ALL, ".UTF8"), vous pouvez passer «😊 » à mbtowcs et il sera correctement traduit en chaîne wchar_t . Auparavant, il n’y avait pas de paramètre régional disponible pour effectuer cette traduction.

Le mode UTF-8 est également activé pour les fonctions qui ont des chaînes historiquement traduites char à l’aide de la page de codes ANSI (ACP) Windows par défaut. Par exemple, l’appel _mkdir("😊") lors de l’utilisation d’une page de codes UTF-8 génère correctement un répertoire avec cet emoji comme nom de dossier, au lieu d’exiger que l’ACP soit remplacé par UTF-8 avant d’exécuter votre programme. De même, l’appel _getcwd() dans ce dossier retourne une chaîne encodée UTF-8. Pour la compatibilité, l’ACP est toujours utilisé si la page de codes des paramètres régionaux C n’est pas définie sur UTF-8.

Les aspects suivants du runtime C ne peuvent pas utiliser UTF-8, car ils sont définis au démarrage du programme et doivent utiliser la page de codes ANSI Windows par défaut (ACP) : __argv, _acmdlnet _pgmptr.

Avant cette prise en charge, mbrtoc16, , mbrtoc32c16rtombet c32rtomb existait pour traduire entre des chaînes étroites UTF-8, UTF-16 (même encodage que wchar_t sur les plateformes Windows) et UTF-32. Pour des raisons de compatibilité, ces API se traduisent toujours uniquement vers et depuis UTF-8 et non la page de codes définie via setlocale.

Pour utiliser cette fonctionnalité sur un système d’exploitation antérieur à Windows 10, vous devez utiliser le déploiement local d’application ou lier statiquement à l’aide de la version 1803 (10.0.17134.0) du Kit de développement logiciel (SDK) Windows ou version ultérieure. Pour les systèmes d’exploitation Windows 10 antérieurs à 1803 (10.0.17134.0), seule la liaison statique est prise en charge.

Spécifications

Routine	En-tête requis
`setlocale`	`<locale.h>`
`_wsetlocale`	`<locale.h>` ou `<wchar.h>`

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple

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

Voir aussi

Noms de paramètres régionaux, langues et chaînes pays/région
_configthreadlocale
_create_locale, _wcreate_locale
Paramètres régionaux
localeconv
_mbclen, , mblen_mblen_l
strlen, , wcslen, _mbslen_l_mbslen, , _mbstrlen_mbstrlen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
_setmbcp
strcoll, fonctions
strftime, , wcsftime_strftime_l, ,_wcsftime_l
strxfrm, , wcsxfrm_strxfrm_l, ,_wcsxfrm_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l

`setlocale`, `_wsetlocale`

Syntaxe

Paramètres

Valeur retournée

Notes

Mappages de routine de texte générique

Prise en charge d’UTF-8

Spécifications

Exemple

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

setlocale, _wsetlocale

Syntaxe

Paramètres

Valeur retournée

Notes

Mappages de routine de texte générique

Prise en charge d’UTF-8

Spécifications

Exemple

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

`setlocale`, `_wsetlocale`