*** UNIX MANUAL PAGE BROWSER ***

strtok(3) Library Functions Manual strtok(3) NAME strtok, strtok_r - Split string into tokens LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <string.h> char *strtok( char *s1, const char *s2); char *strtok_r( char *s1, const char *s2, char **savept); 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 in- dustry 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 to- kens 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() function then searches from there for a byte that does occur in the de- limiter 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 re- turns 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 oc- cur 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 successful 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 ap- plications. Instead, its reentrant equivalent, strtok_r(), should be used with multiple threads. 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++; } } } } } RETURN VALUES Upon successful completion, the strtok() and strtok_r() functions re- turn 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. RELATED INFORMATION Functions: string(3), wcstok(3), wcstok_r(3) Standards: standards(5) delim off strtok(3)