strtok_s、_strtok_s_l、wcstok_s、_wcstok_s_l、_mbstok_s、_mbstok_s_lstrtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l

通过使用当前区域设置或传入的区域设置,查找字符串中的下一个标记。Finds the next token in a string, by using the current locale or a locale that's passed in. 这些版本的 strtok、_strtok_l、wcstok、_wcstok_l、_mbstok、_mbstok_l 具有安全增强功能,如 CRT 中的安全功能中所述。These versions of strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l have security enhancements, as described in Security Features in the CRT.

重要

_mbstok_s_mbstok_s_l不能用于在 Windows 运行时中执行的应用程序。_mbstok_s and _mbstok_s_l cannot be used in applications that execute in the Windows Runtime. 有关详细信息,请参阅通用 Windows 平台应用中不支持的 CRT 函数For more information, see CRT functions not supported in Universal Windows Platform apps.

语法Syntax

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(
   unsigned char* str,
   const unsigned char* delimiters,
   char** context,
   _locale_t locale
);

参数Parameters

strstr
包含或多个令牌若要查找的字符串。A string containing the token or tokens to find.

分隔符delimiters
若要使用的分隔符集。The set of delimiter characters to use.

contextcontext
用于存储对函数的调用之间的位置信息。Used to store position information between calls to the function.

localelocale
要使用的区域设置。The locale to use.

返回值Return Value

将指针返回到下一步中找到的令牌strReturns a pointer to the next token found in str. 返回NULL当找到没有更多的令牌时。Returns NULL when no more tokens are found. 每个调用修改str通过用在返回的令牌之后的第一个分隔符 null 字符替换。Each call modifies str by substituting a null character for the first delimiter that occurs after the returned token.

错误条件Error Conditions

strstr 分隔符delimiters contextcontext 返回值Return value errnoerrno
NULLNULL 任何any 指向空指针的指针pointer to a null pointer NULLNULL EINVALEINVAL
任何any NULLNULL 任何any NULLNULL EINVALEINVAL
任何any 任何any NULLNULL NULLNULL EINVALEINVAL

如果strNULL上下文是一个指针,到有效的上下文指针时,没有错误。If str is NULL but context is a pointer to a valid context pointer, there is no error.

备注Remarks

Strtok_s系列函数查找中的下一个标记strThe strtok_s family of functions finds the next token in str. 中的字符组分隔符指定可能要在中找到的标记分隔符str上当前的调用。The set of characters in delimiters specifies possible delimiters of the token to be found in str on the current call. wcstok_s_mbstok_s宽字符及多字节字符版本的strtok_swcstok_s and _mbstok_s are wide-character and multibyte-character versions of strtok_s. 自变量和返回值wcstok_s_wcstok_s_l是宽字符字符串; 而的 _mbstok_s_mbstok_s_l是多字节字符字符串。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 functions behave identically otherwise.

此函数验证其参数。This function validates its parameters. 如果出现错误条件表中的错误条件,则调用无效的参数处理程序,如参数验证中所述。If an error condition occurs, as in the Error Conditions table, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数将设置errnoEINVAL并返回NULLIf execution is allowed to continue, these functions set errno to EINVAL and return NULL.

在第一个调用strtok_s函数跳过前导分隔符,并将指针返回到中的第一个标记str,终止 null 字符的标记。On the first call to strtok_s the function skips leading delimiters and returns a pointer to the first token in str, terminating the token with a null character. 多个令牌的更改会损坏外的其余部分str对的调用一系列strtok_sMore tokens can be broken out of the remainder of str by a series of calls to strtok_s. 每次调用strtok_s修改str的方法是在该调用返回的标记后插入 null 字符。Each call to strtok_s modifies str 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. 若要读取下一个令牌以从str,调用strtok_sNULLstr自变量,并将传递相同上下文参数。To read the next token from str, call strtok_s with a NULL value for the str argument, and pass the same context parameter. NULL str参数可以使strtok_s搜索中修改后的下一个标记strThe NULL str argument causes strtok_s to search for the next token in the modified str. 分隔符自变量可以采用到下一次调用之间的任何值,以便分隔符集可能会有所不同。The delimiters argument can take any value from one call to the next so that the set of delimiters may vary.

由于上下文参数将取代中使用的静态缓冲区strtok_strtok_l,可以分析同时在同一线程中的两个字符串。Since the context parameter supersedes the static buffers used in strtok and _strtok_l, it is possible to parse two strings simultaneously in the same thread.

输出值受区域设置的 LC_CTYPE 类别设置影响;有关详细信息,请参阅 setlocaleThe output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. 版本的这些功能,而不必 _l后缀区域设置相关的行为使用当前线程区域设置。The versions of these functions without the _l suffix use the current thread locale for this locale-dependent behavior. 版本与 _l后缀是相同,只不过它们改用区域设置参数。The versions with the _l suffix are identical except that they instead use the locale parameter. 有关详细信息,请参阅 LocaleFor more information, see Locale.

要求Requirements

例程Routine 必需的标头Required header
strtok_sstrtok_s <string.h><string.h>
_strtok_s_l_strtok_s_l <string.h><string.h>
wcstok_swcstok_s,
_wcstok_s_l_wcstok_s_l
<string.h> 或 <wchar.h><string.h> or <wchar.h>
_mbstok_s_mbstok_s,
_mbstok_s_l_mbstok_s_l
<mbstring.h><mbstring.h>

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

一般文本例程映射Generic-Text Routine Mappings

TCHAR.H 例程TCHAR.H routine _UNICODE (& a) _MBCS 未定义_UNICODE & _MBCS not defined _MBCS 定义_MBCS defined 已定义 _UNICODE_UNICODE defined
_tcstok_s_tcstok_s strtok_sstrtok_s _mbstok_s_mbstok_s wcstok_swcstok_s
_tcstok_s_l_tcstok_s_l _strtok_s_l_strtok_s_l _mbstok_s_l_mbstok_s_l _wcstok_s_l_wcstok_s_l

示例Example

// 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

请参阅See also

字符串操作String Manipulation
区域设置Locale
多字节字符序列的解释Interpretation of Multibyte-Character Sequences
strcspn、wcscspn、_mbscspn、_mbscspn_lstrcspn, wcscspn, _mbscspn, _mbscspn_l
strspn、wcsspn、_mbsspn、_mbsspn_lstrspn, wcsspn, _mbsspn, _mbsspn_l