strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

Article
06/09/2015

Recherche le jeton suivant dans une chaîne, en utilisant les paramètres régionaux actuels ou des paramètres régionaux qui sont passés. Ces versions strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

Important

_mbstok_s et _mbstok_s_l ne peuvent pas être utilisée dans les applications qui s'exécutent dans le Windows Runtime.Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /ZW.

char *strtok_s( 
char *strToken, 
const char *strDelimit,
   char **context 
); 
char *_strtok_s_l( 
char *strToken, 
const char *strDelimit,
   char **context, 
_locale_tlocale 
); 
wchar_t *wcstok_s( 
wchar_t *strToken, 
const wchar_t *strDelimit, 
   wchar_t**context 
); 
wchar_t *_wcstok_s_l( 
wchar_t *strToken, 
const wchar_t *strDelimit, 
   wchar_t**context, 
_locale_tlocale 
); 
unsigned char *_mbstok_s( 
unsigned char*strToken, 
const unsigned char *strDelimit, 
   char **context 
); 
unsigned char *_mbstok_s( 
unsigned char*strToken, 
const unsigned char *strDelimit, 
   char **context, 
_locale_tlocale 
);

Paramètres

strToken
Chaîne contenant un ou plusieurs jetons.
strDelimit
Ensemble de caractères délimiteurs.
context
Utilisé pour stocker les informations de position entre les appels à strtok_s
locale
Paramètres régionaux à utiliser.

Valeur de retour

Retourne un pointeur vers le jeton suivant trouvé dans strToken. Ils retournent la valeur NULL lorsque plus aucun jeton n'est détecté. Chaque appel change strToken en substituant un caractère NULL au premier séparateur qui se produit après que le jeton soit retourné.

Conditions d'erreur

strToken	strDelimit	context	Valeur de retour	errno
NULL	any	pointeur vers un pointeur null	NULL	EINVAL
any	NULL	any	NULL	EINVAL
any	any	NULL	NULL	EINVAL

Si strToken est NULL mais le contexte est un pointeur vers un pointeur valide de contexte, il n'y a aucune erreur.

Notes

La fonction strtok_s recherche le jeton suivant dans strToken. Le jeu de caractères de strDelimit spécifie les séparateurs possibles du jeton à rechercher dans strToken sur l'appel actif. wcstok_s et _mbstok_ssont des versions à caractères élargis et à caractères multi-octets de strtok_s. Les arguments et les valeurs de retour de wcstok_s et de _wcstok_s_l sont des chaînes à caractères larges ; ceux de _mbstok_s et de _mbstok_s_l sont des chaînes de caractères multioctets. Ces trois fonctions se comportent sinon de façon identique.

Cette fonction valide ses paramètres. Si une condition d'erreur apparaît, comme dans la table de conditions d'erreur, le gestionnaire de paramètres invalides est appelé, comme il est décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions définissent errno à la valeur EINVAL et retournent NULL.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_MBCS défini	_UNICODE défini
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

Au premier appel à strtok_s la fonction ignore des séparateurs et retourne un pointeur vers le premier jeton de strToken, terminant le jeton avec un caractère Null. Plus de jetons peuvent être séparés du reste de strToken par une série d'appels à strtok_s. Chaque appel à strtok_s change strToken en insérant un caractère Null après le jeton retourné par cet appel. Le pointeur context garde la trace des chaînes étant lues et où dans la chaîne le jeton suivant doit être lu. Pour lire le jeton suivant de strToken, appelez strtok_s avec une valeur NULL pour l'argument strToken, puis passez le paramètre context. L'argument strToken NULL force strtok_s à rechercher le jeton suivant dans le strTokenmodifié. L'argument strDelimit peut prendre n'importe quelle valeur d'un appel au suivant afin que l'ensemble des séparateurs puisse varier.

Puisque le paramètre context remplace les mémoires tampons statiques utilisés dans strtok et _strtok_l, il est possible d'analyser deux chaînes simultanément dans le même thread.

La valeur de la sortie est affectée par la valeur du paramètre de la catégorie LC_CTYPE des paramètres régionaux ; consultez setlocale, pour plus d'informations. Les versions de ces fonctions sans le suffixe _l utilisent les paramètres régionaux pour ce comportement dépendant des paramètres régionaux ; les versions avec le suffixe _l sont identiques, sauf qu'elles utilisent à la place les paramètres régionaux transmis. Pour plus d'informations, consultez Paramètres régionaux.

Configuration requise

Routine	En-tête requis
strtok_s	<string.h>
_strtok_s_l	<string.h>
wcstok_s, _wcstok_s_l	<string.h> ou <wchar.h>
_mbstok_s, _mbstok_s_l	<mbstring.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité.

Exemple

// crt_strtok_s.c
// In this program, a loop uses strtok_s
// to print all the tokens (separated by commas
// or blanks) in two strings at the same time.
//

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

char string1[] =
    "A string\tof ,,tokens\nand some  more tokens";
char string2[] =
    "Another string\n\tparsed at the same time.";
char seps[]   = " ,\t\n";
char *token1 = NULL;
char *token2 = NULL;
char *next_token1 = NULL;
char *next_token2 = NULL;

int main( void )
{
    printf( "Tokens:\n" );

    // Establish string and get the first token:
    token1 = strtok_s( string1, seps, &next_token1);
    token2 = strtok_s ( string2, seps, &next_token2);

    // While there are tokens in "string1" or "string2"
    while ((token1 != NULL) || (token2 != NULL))
    {
        // Get next token:
        if (token1 != NULL)
        {
            printf( " %s\n", token1 );
            token1 = strtok_s( NULL, seps, &next_token1);
        }
        if (token2 != NULL)
        {
            printf("        %s\n", token2 );
            token2 = strtok_s (NULL, seps, &next_token2);
        }
    }
}