strtok() — Tokenize String

Format

#include <string.h>

char *strtok(char * __restrict__string1, const char * __restrict__string2);

General Description

The strtok() function breaks a character string, pointed to by string, into a sequence of tokens. The tokens are separated from one another by the characters in the string pointed to by string2.

The token starts with the first character not in the string pointed to by string2. If such a character is not found, there are no tokens in the string. strtok() returns a NULL pointer. The token ends with the first character contained in the string pointed to by string2. If such a character is not found, the token ends at the terminating NULL character. Subsequent calls to strtok() will return the NULL pointer. If such a character is found, then it is overwritten by a NULL character, which terminates the token.

If the next call to strtok() specifies a NULL pointer for string1, the tokenization resumes at the first character following the found and overwritten character from the previous call. For example:
/* Here are two calls  */
strtok(string," ")
strtok(NULL," ")


/* Here is the string they are processing */
                   abc defg hij
    first call finds  ↑
                       ↑ second call starts
Note: To use the strtok() function, set up an environment by using the __cinit() function. When the function is called, GPR 12 must contain the environment token created by the __cinit() call.

Returned Value

The first time strtok() is called, it returns a pointer to the first token in string1. In later calls with the same token string, strtok() returns a pointer to the next token in the string. A NULL pointer is returned when there are no more tokens. All tokens are NULL-terminated.

Related Information