Provided by: manpages-fr-dev_4.21.0-2_all bug

NOM

       mbstowcs  -  Convertir  une  chaîne  de caractères multioctets en une chaîne de caractères
       larges

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <stdlib.h>

       size_t mbstowcs(wchar_t dest[restrict .n], const char *restrict src,
                       size_t n);

DESCRIPTION

       Si dest n'est pas un pointeur NULL, la fonction mbstowcs() convertit la chaîne  multioctet
       src  en  chaîne  de  caractères  larges dest. Elle écrira au plus n caractères larges dans
       dest. La séquence de caractères dans la chaîne src  commencera  dans  l'état  de  décalage
       initial. La conversion peut s'arrêter pour l'une des trois raisons suivantes :

       -  Une  séquence  multioctet  incorrecte  a  été  rencontrée.  Dans  ce  cas, elle renvoie
          (size_t) -1.

       -  n caractères larges différents de L'\0' ont été stockés dans  dest.  Dans  ce  cas,  le
          nombre de caractères larges écrits dans dest est renvoyé, mais l'état de décalage en ce
          point est perdu.

       -  La chaîne multioctet a été complètement convertie, y compris le  caractère  NULL  final
          (« \0 »). Dans ce cas, le nombre de caractères larges écrits dans dest, sans compter le
          caractère large NULL final, est renvoyé.

       Le programmeur doit s'assurer qu'il y a assez de place pour au moins n  caractères  larges
       dans dest.

       Si  dest est NULL, n est ignoré, et la conversion se présente comme au-dessus, excepté que
       les caractères larges ne sont pas écrits  en  mémoire  et  qu'aucune  limite  de  longueur
       n'existe.

       Afin  d'éviter  la  situation  numéro 2 ci-dessus, le programmeur doit s'assurer que n est
       supérieur ou égal a mbstowcs(NULL,src,0)+1.

VALEUR RENVOYÉE

       La fonction mbstowcs() renvoie le nombre de caractères larges qui  constituent  la  partie
       convertie  de  la chaîne, sans compter le caractère NULL final. Si une séquence multioctet
       incorrecte est rencontrée, elle renvoie (size_t) -1.

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌────────────────────────────────────────────────────────┬──────────────────────┬─────────┐
       │InterfaceAttributValeur  │
       ├────────────────────────────────────────────────────────┼──────────────────────┼─────────┤
       │mbstowcs()                                              │ Sécurité des threads │ MT-Safe │
       └────────────────────────────────────────────────────────┴──────────────────────┴─────────┘

STANDARDS

       POSIX.1-2001, POSIX.1-2008, C99.

NOTES

       Le comportement de mbstowcs() dépend de la catégorie LC_CTYPE de la localisation en cours.

       La fonction mbsrtowcs(3) fournit une meilleure interface pour la même fonctionnalité.

EXEMPLES

       Le programme ci-dessous illustre l’utilisation  de  mbstowcs(),  ainsi  que  de  certaines
       fonctions de classification pour les caractères larges. Voici un exemple de son exécution.

           $ ./t_mbstowcs de_DE.UTF-8 Grüße!
           Taille de la chaîne source (sans le caractère final) :
               8 octets
               6 caractères multioctets

           La chaîne de caractères larges est : Grüße! (6 caractères)
               G alpha majuscule
               r alpha minuscule
               ü alpha minuscule
               ß alpha minuscule
               e alpha minuscule
               ! !alpha

   Source du programme

       #include <locale.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #include <wchar.h>
       #include <wctype.h>

       int
       main(int argc, char *argv[])
       {
           size_t mbslen;      /* Nombre de caractères multioctets dans
                                  la source */
           wchar_t *wcs;       /* Pointeur vers la chaîne convertie de
                                  caractères larges */

           if (argc < 3) {
               fprintf(stderr, "Utilisation : %s <locale> <chaîne>\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           /* Appliquer les paramètres régionaux indiqués. */

           if (setlocale(LC_ALL, argv[1]) == NULL) {
               perror("setlocale");
               exit(EXIT_FAILURE);
           }

           /* Calculer la taille nécessaire pour stocker argv[2] convertie en
              chaîne de caractères larges. */

           mbslen = mbstowcs(NULL, argv[2], 0);
           if (mbslen == (size_t) -1) {
               perror("mbstowcs");
               exit(EXIT_FAILURE);
           }

           /* Décrire la chaîne source à l’utilisateur. */

           printf("Taille de la chaîne source (sans le caractère final) :\n");
           printf("    %zu octets\n", strlen(argv[2]));
           printf("    %zu caractères multioctet\n\n", mbslen);

           /* Allouer une chaîne de caractères larges de la taille voulue.
              Ajouter 1 pour accepter le caractère NULL final large (L'\0'). */

           wcs = calloc(mbslen + 1, sizeof(*wcs));
           if (wcs == NULL) {
               perror("calloc");
               exit(EXIT_FAILURE);
           }

           /* Convertir la chaîne de caractères multioctets de argv[2]
              en une chaîne de caractères larges. */

           if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
               perror("mbstowcs");
               exit(EXIT_FAILURE);
           }

           printf("La chaîne de caractères larges est : %ls (%zu caractères)\n",
                  wcs, mbslen);

           /* Inspecter un peu les classes des caractères dans la chaîne
              de caractères larges. */

           for (wchar_t *wp = wcs; *wp != 0; wp++) {
               printf("    %lc ", (wint_t) *wp);

               if (!iswalpha(*wp))
                   printf("!");
               printf("alpha ");

               if (iswalpha(*wp)) {
                   if (iswupper(*wp))
                       printf("majuscule ");

                   if (iswlower(*wp))
                       printf("minuscule ");
               }

               putchar('\n');
           }

           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)

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  <stephan.rafin@laposte.net>,  Thierry
       Vignaud  <tvignaud@mandriva.com>,  François Micaux, Alain Portal <aportal@univ-montp2.fr>,
       Jean-Philippe   Guérard   <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)    <jean-
       luc.coulon@wanadoo.fr>,    Julien    Cristau    <jcristau@debian.org>,    Thomas   Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau  <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
       Barbier <barbier@debian.org> et David Prévot <david@tilapin.org>

       Cette traduction est une documentation libre ; veuillez vous reporter  à  la  GNU  General
       Public   License   version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  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 à ⟨debian-l10n-french@lists.debian.org⟩.