Provided by: manpages-fr-dev_3.57d1p1-1_all bug

NOM

       strtok, strtok_r - Extraire des mots d'une chaîne

SYNOPSIS

       #include <string.h>

       char *strtok(char *str, const char *delim);

       char *strtok_r(char *str, const char *delim, char **saveptr);

   Exigences    de    macros    de   test   de   fonctionnalités   pour   la   glibc   (consultez
   feature_test_macros(7)) :

       strtok_r() : _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE ||
       _POSIX_SOURCE

DESCRIPTION

       La  fonction  strtok() scinde une chaîne en une séquence de zéro, un ou plusieurs éléments
       lexicaux non vides. Lors du premier appel à  strtok(),  la  chaîne  à  scinder  doit  être
       spécifiée  dans  str.  Dans  chaque appel ultérieur fait pour analyser la même chaîne, str
       devrait normalement valoir NULL.

       L'argument delimit indique l'ensemble des octets  qui  délimitent  les  éléments  dans  la
       chaîne  à  analyser.  La chaîne de séparateurs delimit peut être différente à chaque appel
       sur la même chaîne.

       Chaque appel à strtok() renvoie un pointeur sur une chaîne, terminée  par  un  octet  nul,
       contenant  l'élément  suivant.  Cette  chaîne  n'inclut pas le séparateur. S'il n'y a plus
       d'éléments, strtok renvoie NULL.

       Une séquence d'appels à strtok() qui s'exécute sur la même chaîne  gère  un  pointeur  qui
       indique  le  point  de  départ  de la recherche pour l'élément lexical suivant. Le premier
       appel à strtok() positionne ce pointeur sur le premier octet de la  chaîne.  Le  début  de
       l'élément  lexical  suivant est déterminé en parcourant str jusqu'à l'octet suivant qui ne
       soit pas un séparateur. Lorsqu'un tel octet est rencontré, il  est  pris  comme  point  de
       départ  de  l'élément  lexical  suivant.  Si  on ne trouve plus d'octet qui ne soit pas un
       séparateur, alors il n'y a plus d'élément lexical dans la chaîne, et strtok()  renvoie  la
       valeur NULL. (Ainsi, pour une chaîne vide ou qui ne contient que des séparateurs, strtok()
       renverra la valeur NULL dès le premier appel).

       La fin de chaque élément lexical est déterminée en parcourant la  chaîne  jusqu'à  ce  que
       l'octet  suivant soit un délimiteur, ou jusqu'à ce qu'on rencontre l'octet vide ('\0'). Si
       un délimiteur est trouvé, il est écrasé par  un  octet  vide  pour  signifier  la  fin  de
       l'élément  lexical  en  cours  de  détermination,  et  strtok() positionne un pointeur sur
       l'octet suivant ; ce pointeur marque le point de  départ  de  la  recherche  de  l'élément
       lexical  suivant.  Dans  ce  cas,  strtok() renvoie un pointeur vers le début de l'élément
       lexical qui vient d'être isolé.

       De ce qui précède, il découle qu'une séquence de deux séparateurs  contigus  ou  plus  est
       considérée  comme  un  seul séparateur et que les séparateurs en début et en fin de chaîne
       sont ignorés. Les éléments renvoyés par strtok() sont toujours des chaînes non  vides.  Si
       l'on  considère  par  exemple la chaîne «aaa;;bbb,», les appels successifs à strtok() pour
       lequel le séparateur serait «;,»  renverraient  les  chaînes  «aaa»  and  «bbb»,  puis  un
       pointeur NULL.

       La  fonction  strtok_r()  est  la  version  réentrante de la fonction strtok(). L'argument
       saveptr est un pointeur sur une variable char * utilisée de manière interne  à  strtok_r()
       afin de maintenir le contexte entre les appels successifs qui analysent la même chaîne.

       Au  premier appel de strtok_r(), str doit pointer sur la chaîne à analyser et la valeur de
       saveptr est ignorée. Dans les appels suivants, str doit être NULL et saveptr ne  doit  pas
       être modifié depuis le précédent appel.

       Différentes  chaînes  peuvent  être  analysées  de  manière  concurrente  en utilisant des
       séquences d'appels à strtok_r() qui spécifient différents arguments saveptr.

VALEUR RENVOYÉE

       Les fonctions strtok() et strtok_r() renvoient un pointeur sur l'élément lexical  suivant,
       ou NULL s'il n'y en a plus.

ATTRIBUTS

   Multithreading (voir pthreads(7))
       La fonction strtok() n'est pas sûre dans un contexte multithread.

       La fonction strtok_r() est sûre dans un contexte multithread.

CONFORMITÉ

       strtok()
              SVr4, POSIX.1-2001, BSD 4.3, C89, C99.

       strtok_r()
              POSIX.1-2001.

BOGUES

       Faites  attention quand vous utilisez ces fonctions. Si vous les utilisez, prenez note des
       informations suivantes :

       * Ces fonctions modifient leur premier paramètre.

       * Ces fonctions ne peuvent pas être utilisées avec des chaînes constantes.

       * L'identité du délimiteur est perdue.

       * La fonction strtok() utilise un tampon statique et n'est donc pas sûre dans un  contexte
         multithread. Dans ce cas, il vaut mieux utiliser strtok_r().

EXEMPLE

       Le  programme  ci-dessous  utilise  des  boucles  imbriquées qui utilisent strtok_r() pour
       scinder une chaîne en une hiérarchie d'éléments à deux niveaux. Le premier argument de  la
       ligne  de  commande  indique  la  chaîne  à analyser. Le second argument indique le ou les
       séparateurs utilisés pour séparer la chaîne en éléments « majeurs ». Le troisième argument
       indique  le  ou  les  séparateurs  utilisés  pour  séparer  les  éléments  « majeurs »  en
       sous-éléments.

       Voici un exemple de la sortie produite par ce programme :

           $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
           1: a/bbb///cc
                    --> a
                    --> bbb
                    --> cc
           2: xxx
                    --> xxx
           3: yyy
                    --> yyy

   Source du programme

       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           char *str1, *str2, *token, *subtoken;
           char *saveptr1, *saveptr2;
           int j;

           if (argc != 4) {
               fprintf(stderr, "Usage: %s string delim subdelim\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
               token = strtok_r(str1, argv[2], &saveptr1);
               if (token == NULL)
                   break;
               printf("%d: %s\n", j, token);

               for (str2 = token; ; str2 = NULL) {
                   subtoken = strtok_r(str2, argv[3], &saveptr2);
                   if (subtoken == NULL)
                       break;
                   printf(" --> %s\n", subtoken);
               }
           }

           exit(EXIT_SUCCESS);
       }

       Un autre exemple de programme qui utilise strtok() se trouve dans getaddrinfo_a(3).

VOIR AUSSI

       index(3), memchr(3), rindex(3), strchr(3), string(3),  strpbrk(3),  strsep(3),  strspn(3),
       strstr(3), wcstok(3)

COLOPHON

       Cette  page  fait partie de la publication 3.57 du projet man-pages Linux. Une description
       du projet et des  instructions  pour  signaler  des  anomalies  peuvent  être  trouvées  à
       l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Depuis    2010,    cette   traduction   est   maintenue   à   l'aide   de   l'outil   po4a
       <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du  projet
       perkamon <http://perkamon.alioth.debian.org/>.

       Christophe    Blaess    <http://www.blaess.fr/christophe/>   (1996-2003),   Alain   Portal
       <http://manpagesfr.free.fr/> (2003-2006). Nicolas  François  et  l'équipe  francophone  de
       traduction de Debian (2006-2009).

       Veuillez     signaler     toute     erreur     de     traduction     en     écrivant     à
       <debian-l10n-french@lists.debian.org>  ou  par  un  rapport  de  bogue   sur   le   paquet
       manpages-fr.

       Vous  pouvez  toujours  avoir  accès  à la version anglaise de ce document en utilisant la
       commande « man -L C <section> <page_de_man> ».