strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

Artikel
11/16/2012

Find the next token in a string, using either the current locale or a specified locale parameter. These functions are versions of strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l with security enhancements as described in Security Enhancements in the CRT.

char *strtok_s( 
   char *strToken, 
   const char *strDelimit,
   char **context 
); 
char *_strtok_s_l( 
   char *strToken, 
   const char *strDelimit,
   char **context, 
   _locale_t locale 
); 
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_t locale 
); 
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_t locale 
);

Parameters

strToken
In the first call, this parameter is a pointer to a writeable string that contains one or more tokens. Pass NULL for this parameter in subsequent calls to strtok to find the remaining tokens.
strDelimit
Set of delimiter characters.
context
Used to store position information between calls to strtok_s
locale
Locale to use.

Return Value

Returns a pointer to the next token found in strToken, or NULL when no more tokens are found. Each call modifies strToken by substituting a null character for the first delimiter that occurs after the returned token.

Error Conditions

strToken	strDelimit	context	Return value	errno
NULL	any	pointer to a null pointer	NULL	EINVAL
any	NULL	any	NULL	EINVAL
any	any	NULL	NULL	EINVAL

Remarks

The strtok_s function finds the next token in strToken. The set of characters in strDelimit specifies the delimiters of the token to be found in strToken.

wcstok_s and _mbstok_sare wide-character and multibyte-character versions of strtok_s. The arguments and return values of wcstok_s and _wcstok_s_l are wide-character strings; those of _mbstok_s and _mbstok_s_l are multibyte-character strings. These three functions behave identically otherwise.

This function validates its parameters. If an error condition occurs (see the Error Conditions table), the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, these functions set errno to EINVAL and return NULL.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_tcstok_s	strtok_s	_mbstok_s	wcstok_s
_tcstok_s_l	_strtok_s_l	_mbstok_s_l	_wcstok_s_l

On the first call to strtok_s the function skips leading delimiters and returns a pointer to the first token in strToken, terminating the token with a null character. More tokens can be broken out of the remainder of strToken by a series of calls to strtok_s. Each call to strtok_s modifies strToken by inserting a null character after the token returned by that call.

The context pointer keeps track of which string is being read and where in the string the next token is to be read. To read subsequent tokens from the original strToken parameter, call strtok_s with NULL for strToken and the same context parameter.

Because the context parameter supersedes the buffers used in strtok and _strtok_l, you can parse two strings simultaneously in the same thread.

The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. For more information, see Locale.

Requirements

Routine	Required header
strtok_s	<string.h>
_strtok_s_l	<string.h>
wcstok_s, _wcstok_s_l	<string.h> or <wchar.h>
_mbstok_s, _mbstok_s_l	<mbstring.h>

For additional compatibility information, see Compatibility in the Introduction.

Example

// crt_strtok_s.c
// In this program, a loop uses strtok_s
// to print all the tokens (separated by commas, tabs, 
// 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

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

Change History

Date	History	Reason
May 2009	Topic cleanup.	Information enhancement.

Dela via