strtok_r Subroutine

Purpose

Breaks a string into a sequence of tokens.

Libraries

Thread-Safe C Library (libc_r.a)

Syntax

#include<string.h>
char *strtok_r (String, Separators, Pointer);
char *String;
const char *Separators;
char **Pointer;

Description

Note: The strtok_r subroutine is used in a multithreaded environment.

The strtok_r subroutine breaks the string pointed to by the String parameter into a sequence of tokens, each of which is delimited by a byte from the string pointed to by the Separators parameter. The Pointer parameter holds the information necessary for the strtok_r subroutine to perform scanning on the String parameter. In the first call to the strtok_r subroutine, the value passed as the Pointer parameter is ignored.

The first call in the sequence searches the String parameter for the first byte that is not contained in the current separator string pointed to by the Separators parameter. If no such byte is found, no tokens exist in the String parameter, and a null pointer is returned. If such a byte is found, it is the start of the first token. The strtok_r subroutine also updates the Pointer parameter with the starting address of the token following the first occurrence of the Separators parameter.

In subsequent calls, a null pointer should be passed as the first parameter to the strtok_r subroutine instead of the String parameter. Each subsequent call with a null pointer as the value of the first argument starts searching from the Pointer parameter, using it as the first token. Otherwise, the subroutine's behavior does not change. The strtok_r subroutine would return successive tokens until no tokens remain. The Separators parameter may be different from one call to another.

Parameters

Item Description
String Points to a string from which an operation returns results.
Separators Points to a string which contains source for an operation.
Pointer Points to a user provided pointer.

Error Codes

The strtok_r subroutine fails if the following occurs:
Item Description
EFAULT A String parameter is an invalid address.