NAME

strtok, strtok_r - split string into tokens

 SYNOPSIS

#include <string.h>

char *strtok(char *s1, const char *s2);
char *strtok_r(char *s, const char *sep, char **lasts);

 DESCRIPTION

A sequence of calls to strtok() breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a byte from the string pointed to by s2. The first call in the sequence has s1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 may be different from call to call.

The first call in the sequence searches the string pointed to by s1 for the first byte that is not contained in the current separator string pointed to by s2. If no such byte is found, then there are no tokens in the string pointed to by s1 and strtok() returns a null pointer. If such a byte is found, it is the start of the first token.

The strtok() function then searches from there for a byte that is contained in the current separator string. If no such byte is found, the current token extends to the end of the string pointed to by s1, and subsequent searches for a token will return a null pointer. If such a byte is found, it is overwritten by a null byte, which terminates the current token. The strtok() function saves a pointer to the following byte, from which the next search for a token will start.

Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.

The implementation will behave as if no function defined in this document calls strtok().

The strtok() interface need not be reentrant.

The function strtok_r() considers the null-terminated string s as a sequence of zero or more text tokens separated by spans of one or more characters from the separator string sep. The argument lasts points to a user-provided pointer which points to stored information necessary for strtok_r() to continue scanning the same string.

In the first call to strtok_r(), s points to a null-terminated string, sep to a null-terminated string of separator characters and the value pointed to by lasts is ignored. The function strtok_r() returns a pointer to the first character of the first token, writes a null character into s immediately following the returned token, and updates the pointer to which lasts points.

In subsequent calls, s is a NULL pointer and lasts will be unchanged from the previous call so that subsequent calls will move through the string s, returning successive tokens until no tokens remain. The separator string sep may be different from call to call. When no token remains in s, a NULL pointer is returned.

 RETURN VALUE

Upon successful completion, strtok() returns a pointer to the first byte of a token. Otherwise, if there is no token, strtok() returns a null pointer.

The function strtok_r() returns a pointer to the token found, or a NULL pointer when no token is found.

 ERRORS

No errors are defined.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

<string.h>.

DERIVATION

strtok() derived from Issue 1 of the SVID.

strtok_r() derived from the POSIX Threads Extension (1003.1c-1995).