[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 2

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 strok_r subroutine to perform scanning on the String parameter. In the first call to the strok_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 strok_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

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:

EFAULT A String parameter is an invalid address.

Related Information

The strlen, strchr, strrchr, strpbrk, strspn, strcspn, strstr, strtok, or strsep Subroutine.

Writing Reentrant and Thread-Safe Code in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]