strtok_s, wcstok_s

Go Up to string.h Index

Header File

string.h, _str.h

Category

Memory and String Manipulation Routines

Prototype

char *strtok_s(char * _RESTRICT __s1, rsize_t * _RESTRICT __s1max, const char * _RESTRICT __s2, char ** _RESTRICT __ptr);

wchar_t *wcstok_s(wchar_t * _RESTRICT __s1, rsize_t * _RESTRICT __s1max, const wchar_t * _RESTRICT __s2, wchar_t ** _RESTRICT __ptr);

Description

Replaces strtok, _mbstok, wcstok adding security enhancements.

Searches one string for tokens, which are separated by delimiters defined in a second string.

strtok_s considers the string __s1 to consist of a sequence of zero or more text tokens, separated by spans of one or more characters from the separator string __s2.

The first call to strtok_s returns a pointer to the first character of the first token in __s1 and writes a null character into __s1 immediately following the returned token. Subsequent calls with null for the first argument will work through the string __s1 this way, until no tokens remain.

The separator string __s2 can be different from call to call. ptr is used to point to a user-defined char* to store information necessary to continue scanning for other tokens in the same __s1.

If there is a run-time constraint violation, strtok_s does not indirect through the __s1 or __s2 pointers and does not store any value where ptr is pointing to.

Note: Calls to strtok_s cannot be nested with a function call that also uses strtok_s. Doing so causes an endless loop.

Return Value

strtok_s returns a pointer to the first token found in __s1. A NULL pointer is returned when there are no more tokens or there is a run-time constraint violation.

Example

 #include <string.h>
 #include <stdio.h>
 int main(void)
 {
    unsigned int s1max = 16;
    char input[16] = "abc,d";
    char *p;
    char *ptr = " ";
    /* strtok places a NULL terminator
    in front of the token, if found */
    p = strtok_s(input, &s1max, ",", &ptr);
    if (p)   printf("%s\n", p);
    /* A second call to strtok using NULL
    as the first parameter returns a pointer
    to the character following the token  */
    p = strtok_s(NULL, &s1max, ",", &ptr);
    if (p)   printf("%s\n", p);
    return 0;
 }

Portability

	POSIX	Win32	ANSI C	ANSI C++
strtok_s	+	+	+	+
wcstok_s		+	+	+

See Also

• Secure C Library