strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

Busca el siguiente token en una cadena, con la configuración regional actual o con la configuración regional que se pase. Estas versiones de strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, tienen _mbstok_l mejoras de seguridad, como se describe en Características de seguridad de CRT.

Importante

_mbstok_s y _mbstok_s_l no se pueden usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.

Sintaxis

char* strtok_s(
   char* str,
   const char* delimiters,
   char** context
);

char* _strtok_s_l(
   char* str,
   const char* delimiters,
   char** context,
   _locale_t locale
);

wchar_t* wcstok_s(
   wchar_t* str,
   const wchar_t* delimiters,
   wchar_t** context
);

wchar_t *_wcstok_s_l(
   wchar_t* str,
   const wchar_t* delimiters,
   wchar_t** context,
   _locale_t locale
);

unsigned char* _mbstok_s(
   unsigned char* str,
   const unsigned char* delimiters,
   char** context
);

unsigned char* _mbstok_s_l(
   unsigned char* str,
   const unsigned char* delimiters,
   char** context,
   _locale_t locale
);

Parámetros

str
Cadena que contiene los tokens que se van a buscar.

delimiters
Conjunto de caracteres delimitadores que se van a usar.

context
Se usa para almacenar información de posición entre llamadas a la función.

locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve un puntero al siguiente token que se encuentra en str. Devuelve NULL cuando no se encuentran más tokens. Cada llamada modifica str sustituyendo un carácter nulo por el primer delimitador que aparece después del token devuelto.

Condiciones de error

str	delimiters	context	Valor devuelto	errno
NULL	cualquiera	puntero a un puntero nulo	NULL	EINVAL
cualquiera	NULL	cualquiera	NULL	EINVAL
cualquiera	cualquiera	NULL	NULL	EINVAL

Si str es NULL, pero context es un puntero a un puntero de contexto válido, no se producirá un error.

Comentarios

La familia de funciones strtok_s encuentra el token siguiente en str. El juego de caracteres de delimiters especifica los delimitadores posibles del token que se van a buscar en str en la llamada actual. wcstok_s y _mbstok_s son versiones de caracteres anchos y multibyte de strtok_s. Los argumentos y los valores devueltos de y _wcstok_s_l son cadenas de wcstok_s caracteres anchos. Los argumentos y los valores devueltos de y _mbstok_s_l son cadenas de _mbstok_s caracteres multibyte. Por lo demás, estas funciones se comportan exactamente igual.

Esta función valida sus parámetros. Cuando se produce una condición de error, como en la tabla Condiciones de error, se invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones establecen errno en EINVAL y devuelven NULL.

En la primera llamada a strtok_s, la función omite los delimitadores iniciales y devuelve un puntero al primer token de str, y finaliza el token con un carácter nulo. Del resto de str se pueden extraer más tokens mediante una serie de llamadas a strtok_s. Cada llamada a strtok_s modifica str insertando un carácter nulo después del token devuelto por la llamada. El puntero a context realiza el seguimiento de la cadena que se está leyendo y dónde en la cadena se debe leer el token siguiente. Para leer el token siguiente de str, llame a strtok_s con un valor NULL para el argumento de str, y pase el mismo parámetro context. El argumento NULL de str hace que strtok_s busque el token siguiente en el str modificado. El argumento delimiters acepta cualquier valor de una llamada a la siguiente, por lo que el juego de delimitadores puede variar.

Puesto que el parámetro context reemplaza los búferes estáticos que se usan en strtok y _strtok_l, es posible analizar dos cadenas simultáneamente en el mismo subproceso.

El valor de salida se ve afectado por el valor de la categoría LC_CTYPE de la configuración regional. Para obtener más información, vea setlocale.

Las versiones de estas funciones sin el sufijo _l utilizan la configuración regional del subproceso actual para el comportamiento que depende de esta configuración regional. Las versiones con el sufijo _l son idénticas, salvo que usan la configuración regional que especifica el parámetro locale. Para obtener más información, vea Locale.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

Requisitos

Routine	Encabezado necesario
strtok_s	<string.h>
_strtok_s_l	<string.h>
wcstok_s, _wcstok_s_l	<string.h> o <wchar.h>
_mbstok_s, _mbstok_s_l	<mbstring.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// 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);
        }
    }
}

Tokens:
A
        Another
string
        string
of
        parsed
tokens
        at
and
        the
some
        same
more
        time.
tokens

Consulte también

Manipulación de cadenas
Configuración regional
Interpretación de secuencias de caracteres multibyte
strcspn, wcscspn, _mbscspn, _mbscspn_l
strspn, wcsspn, _mbsspn, _mbsspn_l