newlocale

NOM

newlocale, freelocale - Créer, modifier et libérer un objet de paramètres régionaux

BIBLIOTHÈQUE

Bibliothèque C standard ( libc, -lc)

SYNOPSIS

#include <locale.h>

locale_t newlocale(int category_mask, const char *locale,
                   locale_t base);
void freelocale(locale_t locobj);

newlocale(), freelocale() :

    Depuis la version 2.10 de la glibc :
        _XOPEN_SOURCE >= 700
    Avant la version 2.10 de la glibc :
        _GNU_SOURCE

DESCRIPTION

La fonction newlocale() crée un nouvel objet de paramètres régionaux ou modifie un objet existant, en renvoyant une référence vers le nouvel objet ou l’objet modifié comme résultat de la fonction. L’appel crée un nouvel objet ou modifie un objet existant en fonction de la valeur de base :

•

si base est (locale_t) 0, un nouvel objet est créé ;

•

si base indique un objet de paramètres régionaux valable existant (c’est-à-dire un objet renvoyé par un précédent appel de newlocale() ou duplocale(3)), alors cet objet est modifié par l’appel. Si l’appel réussit, le contenu de base n’est pas garanti (en particulier, l’objet indiqué par base pourrait être libéré et un nouvel objet créé). Par conséquent, l’appelant devrait s’assurer de ne plus utiliser base avant l’appel de newlocale() et devrait ensuite se rapporter à l’objet modifié à l’aide de la référence renvoyée comme résultat de la fonction. Si l’appel échoue, le contenu de base reste valable et sans modification.

Si base est l’objet spécial de paramètres régionaux LC_GLOBAL_LOCALE (consultez duplocale(3)), ou n’est pas (locale_t) 0 ni un identifiant d’objet de paramètres régionaux valable, le comportement est non défini. L’argument category_mask est un masque binaire indiquant les catégories de paramètres régionaux à définir dans un objet de paramètres régionaux nouvellement créé ou modifié dans un objet existant. Le masque est construit avec un OU binaire des constantes LC_ADDRESS_MASK, LC_CTYPE_MASK, LC_COLLATE_MASK, LC_IDENTIFICATION_MASK, LC_MEASUREMENT_MASK, LC_MESSAGES_MASK, LC_MONETARY_MASK, LC_NUMERIC_MASK, LC_NAME_MASK, LC_PAPER_MASK, LC_TELEPHONE_MASK et LC_TIME_MASK. Alternativement, le masque peut être défini comme LC_ALL_MASK, ce qui est équivalent à effectuer un OU binaire sur toutes les constantes précédentes. Pour chaque catégorie indiquée dans category_mask, les données de paramètres régionaux de locale seront utilisées dans l’objet renvoyé par newlocale(). Si un nouvel objet de paramètres régionaux est en cours de création, les données de toutes les catégories non indiquées dans category_mask sont prises dans les paramètres régionaux par défaut ("POSIX"). Les valeurs prédéfinies suivantes de locale sont définies pour toutes les catégories qui peuvent être indiquées dans category_mask :

"POSIX"

Un environnement de paramètres régionaux minimal pour les programmes en langage C.

"C"

Équivalent à "POSIX".

""

Un environnement natif défini pour l’implémentation correspondant aux valeurs des variables d’environnement LC_* et LANG (consultez locale(7)).

freelocale()

La fonction freelocale() désalloue les ressources associées à locobj, un objet de paramètres régionaux renvoyé par un appel à newlocale() ou duplocale(3). Si locobj est LC_GLOBAL_LOCALE ou n’est pas un identifiant d’objet valable de paramètres régionaux, le résultat n’est pas défini. Une fois qu’un objet de paramètres régionaux à été libéré, le programme ne devrait plus l’utiliser.

VALEUR RENVOYÉE

On success, newlocale() returns a handle that can be used in calls to duplocale(3), freelocale(), and other functions that take a locale_t argument. On error, newlocale() returns (locale_t) 0, and sets errno to indicate the error.

ERREURS

EINVAL

Au moins un bit de category_mask ne correspond pas à une catégorie valable de paramètres régionaux.

EINVAL

locale est NULL.

ENOENT

locale n’est pas un pointeur de chaîne vers des paramètres régionaux valables.

ENOMEM

Pas assez de mémoire pour créer un objet de paramètres régionaux.

VERSIONS

The newlocale() and freelocale() functions first appeared in glibc 2.3.

STANDARDS

POSIX.1-2008.

NOTES

Each locale object created by newlocale() should be deallocated using freelocale().

EXEMPLES

Le programme suivant prend jusqu’à deux arguments en ligne de commande, identifiant chacun des paramètres régionaux. Le premier argument est nécessaire et sert à définir le catégorie LC_NUMERIC dans un objet de paramètres régionaux créé avec newlocale(). Le second argument est facultatif et sert à définir la catégorie LC_TIME de l’objet de paramètres régionaux s’il est présent. Après création et initialisation de l’objet de paramètres régionaux, le programme l’applique en utilisant uselocale(3) et teste ensuite l’effet de la modification de paramètres régionaux en :

(1)

affichant un nombre à virgule avec une partie décimale. Cette sortie sera affectée par le réglage LC_NUMERIC. Dans de nombreux paramètres régionaux de langues européennes, le partie décimale du nombre est séparée de la partie entière par une virgule, plutôt que par un point ;

(2)

affichant la date. Le format et la langue de sortie seront affectés par le réglage LC_TIME.

Les sessions suivantes d’interpréteur de commandes montrent des exemples d’exécution de ce programme. Définir la catégorie LC_NUMERIC à fr_FR (français) :

$  ./a.out fr_FR
123456,789
Fri Mar  7 00:25:08 2014

Définir la catégorie LC_NUMERIC à fr_FR (français) et la catégorie LC_TIME à it_IT (italien) :

$  ./a.out fr_FR it_IT
123456,789
ven 07 mar 2014 00:26:01 CET

Specify the LC_TIME setting as an empty string, which causes the value to be taken from environment variable settings (which, here, specify mi_NZ, New Zealand Māori):

$ LC_ALL=mi_NZ ./a.out fr_FR ""
123456,789
Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET

Source du programme

#define _XOPEN_SOURCE 700
#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                        } while (0)

int
main(int argc, char *argv[])
{
    char buf[100];
    time_t t;
    size_t s;
    struct tm *tm;
    locale_t loc, nloc;

    if (argc < 2) {
        fprintf(stderr, "Utilisation : %s locale1 [locale2]\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    /* Create a new locale object, taking the LC_NUMERIC settings
       from the locale specified in argv[1]. */

    loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
    if (loc == (locale_t) 0)
        errExit("newlocale");

    /* If a second command-line argument was specified, modify the
       locale object to take the LC_TIME settings from the locale
       specified in argv[2]. We assign the result of this newlocale()
       call to 'nloc' rather than 'loc', since in some cases, we might
       want to preserve 'loc' if this call fails. */

    if (argc > 2) {
        nloc = newlocale(LC_TIME_MASK, argv[2], loc);
        if (nloc == (locale_t) 0)
            errExit("newlocale");
        loc = nloc;
    }

    /* Apply the newly created locale to this thread. */

    uselocale(loc);

    /* Test effect of LC_NUMERIC. */

    printf("%8.3f\n", 123456.789);

    /* Test effect of LC_TIME. */

    t = time(NULL);
    tm = localtime(&t);
    if (tm == NULL)
        errExit("time");

    s = strftime(buf, sizeof(buf), "%c", tm);
    if (s == 0)
        errExit("strftime");

    printf("%s\n", buf);

    /* Free the locale object. */

    uselocale(LC_GLOBAL_LOCALE);    /* So 'loc' is no longer in use */
    freelocale(loc);

    exit(EXIT_SUCCESS);
}

VOIR AUSSI

locale(1), duplocale(3), setlocale(3), uselocale(3), locale(5), locale(7)

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <[email protected]>, Thierry Vignaud <[email protected]>, François Micaux, Alain Portal <[email protected]>, Jean-Philippe Guérard <[email protected]>, Jean-Luc Coulon (f5ibh) <[email protected]>, Julien Cristau <[email protected]>, Thomas Huriaux <[email protected]>, Nicolas François <[email protected]>, Florentin Duneau <[email protected]>, Simon Paillard <[email protected]>, Denis Barbier <[email protected]> et David Prévot <[email protected]> Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à [email protected]