strtok(3)strtok(3)NAME
strtok, strtok_r - Split string into tokens
SYNOPSIS
#include <string.h>
char *strtok(
char *s1,
const char *s2 ); char *strtok_r(
char *s1,
const char *s2,
char **savept );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
strtok_r(): POSIX.1c
strtok(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Contains a pointer to the string to be searched. Contains a pointer to
the string of byte token delimiters. [POSIX] Identifies the location
of the byte where the search for tokens should be started in the next
call to strtok_r(). The savept parameter contains a pointer to a vari‐
able that contains a pointer to the byte in the string.
DESCRIPTION
The strtok() function splits the string pointed to by the s1 parameter
into a sequence of tokens, each of which is delimited by a byte equal
to one of the bytes in the s2 parameter.
Usually, the strtok() function is called repeatedly to extract the
tokens in a string. The first time the application program calls the
strtok() function, it sets the s1 parameter to point to the input
string. The function returns a pointer to the first token. Then the
application program calls the function again with the s1 parameter set
to the null pointer. This call returns a pointer to the next token in
the string. The application program repeats the call to strtok() with
the s1 parameter set to the null pointer until all the tokens in the
string have been returned.
Note
If the input string contains no instances of bytes from the delimiter
string, the first call to strtok() results in the return of a pointer
to the original string. On subsequent calls, strtok() returns NULL.
In the initial call to strtok(), the function first searches the string
pointed to by the s1 parameter to locate the first byte that does not
occur in the delimiter string pointed to by the s2 parameter. If such
a byte is found, it is the start of the first token. The strtok() func‐
tion then searches from there for a byte that does occur in the delim‐
iter string. If such a delimiter is found, strtok() overwrites it with
a null byte, which terminates the current token. The strtok() function
saves a pointer to the byte following the null byte and returns a
pointer to the start of the token.
In the subsequent calls to strtok(), in which the s1 parameter is set
to the null pointer, the function starts at its saved pointer and
searches for the next byte that does not occur in the delimiter string
pointed to by the s2 parameter. If such a byte is found, it is the
start of the new token. The strtok() function then searches from there
for a byte that does occur in the delimiter string. If such a delim‐
iter is found, strtok() overwrites it with a null byte, which termi‐
nates the new token. The strtok() function saves a pointer to the byte
following the null byte and returns a pointer to the start of the new
token.
If a call to the strtok() function cannot find a byte that does not
occur in the delimiter string, it returns the null pointer. If a call
to the strtok() function cannot find the terminating byte that does
occur in the delimiter string, the current token extends to the end of
the string and subsequent calls to strtok() will return the null
pointer.
If the delimiters used in the string change from one set of characters
to another within the string, the application program can set the sec‐
ond parameter, s2, to different strings from call to call.
The implementation behaves as though no function calls the strtok()
function.
The strtok_r() function is the reentrant version of strtok(). Upon suc‐
cessful completion, the strtok_r() function stores the saved pointer in
*savept. If the s1 parameter is a null pointer, the strtok_r() function
uses the saved pointer in *savept to start searching for the next
token. In the initial call to strtok_r(), the *savept must be the null
pointer.
NOTES
[POSIX] The strtok() function is not supported for multithreaded
applications. Instead, its reentrant equivalent, strtok_r(), should be
used with multiple threads.
RETURN VALUES
Upon successful completion, the strtok() and strtok_r() functions
return a pointer to the first byte of the parsed token in the string.
When there is no token in the string, a null pointer is returned.
EXAMPLES
The following example demonstrates how to split a string into tokens.
#include <string.h> #include <locale.h> #include <stdio.h> #define
LENGTH 40
main() {
char string1[LENGTH], delimiters[LENGTH];
char *pstr ;
int counter;
(void)setlocale(LC_ALL, );
printf("Enter the string to be searched: ");
if (fgets(string1, LENGTH, stdin) != NULL) {
printf("Enter the delimiter(s): ");
if (fgets(delimiters, LENGTH, stdin) != NULL) {
if ((pstr = strtok(string1, delimiters ))
!= NULL) {
/* pstr points to the first token */
printf("Token 1 is %s\n", pstr);
counter = 2;
while ((pstr = strtok((char *)NULL, delimiters ))
!= NULL) {
printf("Token %d is %s\n", counter, pstr);
counter++;
}
}
}
} }
SEE ALSO
Functions: string(3), wcstok(3), wcstok_r(3)
Standards: standards(5)strtok(3)