strtok(3)                  Library Functions Manual                  strtok(3)

NOM
       strtok, strtok_r - Extraire des sequences d'une chaine

BIBLIOTHEQUE
       Bibliotheque C standard (libc, -lc)

SYNOPSIS
       #include <string.h>

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

   Exigences de macros de test de fonctionnalites pour la glibc (consulter
   feature_test_macros(7)) :

       strtok_r() :
           _POSIX_C_SOURCE
               || /* glibc <= 2.19 : */ _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION
       La fonction strtok() scinde une chaine en une suite de zero ou
       plusieurs sequences non vides. Lors du premier appel a strtok(), la
       chaine a scinder doit etre specifiee dans str. Dans chaque appel
       ulterieur fait pour analyser la meme chaine, str doit etre NULL.

       L'argument delim indique l'ensemble des octets qui delimitent les
       sequences dans la chaine a analyser. La chaine de separateurs delim
       peut etre differente a chaque appel sur la meme chaine.

       Chaque appel a strtok() renvoie un pointeur sur une chaine terminee par
       un octet NULL contenant la sequence suivante. Cette chaine n'inclut pas
       le separateur. S'il n'y a plus de sequences, strtok renvoie NULL.

       Une suite d'appels a strtok() qui s'execute sur la meme chaine gere un
       pointeur qui indique le point de depart de la recherche pour la
       sequence suivante. Le premier appel a strtok() positionne ce pointeur
       sur le premier octet de la chaine. Le debut de la sequence suivante est
       determine en parcourant str jusqu'a l'octet suivant qui ne soit pas un
       separateur. Lorsqu'un tel octet est rencontre, il est pris comme point
       de depart de la sequence suivante. Si aucun octet n'est trouve qui ne
       soit pas un separateur, alors il n'y a plus de sequence dans la chaine
       et strtok() renvoie NULL. (Ainsi, pour une chaine vide ou qui ne
       contient que des separateurs, strtok() renverra NULL des le premier
       appel).

       La fin de chaque sequence est determinee en parcourant la chaine
       jusqu'a ce que l'octet suivant soit un delimiteur, ou jusqu'a ce qu'on
       rencontre l'octet NULL final (<< \0 >>). Si un delimiteur est trouve,
       il est ecrase par un octet NULL pour signifier la fin de la sequence en
       cours de determination, et strtok() positionne un pointeur sur l'octet
       suivant ; ce pointeur marque le point de depart de la recherche de la
       sequence suivante. Dans ce cas, strtok() renvoie un pointeur vers le
       debut de la sequence qui vient d'etre isolee.

       De ce qui precede, il decoule qu'une suite de deux separateurs contigus
       ou plus est consideree comme un seul separateur et que les separateurs
       en debut et en fin de chaine sont ignores. Les sequences renvoyees par
       strtok() sont toujours des chaines non vides. Si l'on considere par
       exemple la chaine <<aaa;;bbb,>>, les appels successifs a strtok() pour
       lequel le separateur serait <<;,>> renverraient les chaines <<aaa>> et
       <<bbb>>, puis un pointeur NULL.

       La fonction strtok_r() est la version reentrante de la fonction
       strtok(). L'argument saveptr est un pointeur sur une variable char *
       utilisee de maniere interne par strtok_r() afin de maintenir le
       contexte entre les appels successifs qui analysent la meme chaine.

       Au premier appel de strtok_r(), str doit pointer sur la chaine a
       analyser et la valeur de *saveptr est ignoree (mais consultez les
       NOTES). Dans les appels suivants, str doit etre NULL et saveptr (et le
       tampon vers lequel il pointe) ne doit pas etre modifie depuis le
       precedent appel.

       Differentes chaines peuvent etre analysees de maniere concurrente en
       utilisant des suites d'appels a strtok_r() qui specifient differents
       arguments saveptr.

VALEUR RENVOYEE
       Les fonctions strtok() et strtok_r() renvoient un pointeur sur la
       sequence suivante, ou NULL s'il n'y en a plus.

ATTRIBUTS
       Pour une explication des termes utilises dans cette section, consulter
       attributes(7).

       +-------------------+--------------------------+-----------------------+
       |Interface          | Attribut                 | Valeur                |
       +-------------------+--------------------------+-----------------------+
       |strtok()           | Securite des threads     | MT-Unsafe race:strtok |
       +-------------------+--------------------------+-----------------------+
       |strtok_r()         | Securite des threads     | MT-Safe               |
       +-------------------+--------------------------+-----------------------+
VERSIONS
       Pour plusieurs implementations, *saveptr doit etre NULL lors du premier
       appel a strtok_r() utilise pour analyser str.

STANDARDS
       strtok()
              C11, POSIX.1-2008.

       strtok_r()
              POSIX.1-2008.

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

       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 parametre.

       -  Ces fonctions ne peuvent pas etre utilisees avec des chaines
          constantes.

       -  L'identite du delimiteur est perdue.

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

EXEMPLES
       Le programme ci-dessous utilise des boucles imbriquees qui utilisent
       strtok_r() pour scinder une chaine en une hierarchie de sequences a
       deux niveaux. Le premier argument de la ligne de commande indique la
       chaine a analyser. Le second argument indique le ou les separateurs
       utilises pour separer la chaine en sequences << majeures >>. Le
       troisieme argument indique le ou les separateurs utilises pour separer
       les sequences << majeures >> en sous-sequences.

       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("\t --> %s\n", subtoken);
               }
           }

           exit(EXIT_SUCCESS);
       }

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

VOIR AUSSI
       memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3),
       strstr(3), wcstok(3)

TRADUCTION
       La traduction francaise de cette page de manuel a ete creee par
       Christophe Blaess <https://www.blaess.fr/christophe/>, Stephan Rafin
       <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>,
       Francois Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe
       Guerard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
       luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas
       Huriaux <thomas.huriaux@gmail.com>, Nicolas Francois
       <nicolas.francois@centraliens.net>, Florentin Duneau
       <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-
       bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prevot
       <david@tilapin.org>, Frederic Hantrais <fhantrais@gmail.com> et
       Gregoire Scano <gregoire.scano@malloc.fr>

       Cette traduction est une documentation libre ; veuillez vous reporter a
       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 RESPONSABILITE LEGALE.

       Si vous decouvrez un bogue dans la traduction de cette page de manuel,
       veuillez envoyer un message a <debian-l10n-french@lists.debian.org>.

Pages du manuel de Linux 6.06   31 octobre 2023                      strtok(3)