#include "safe_str_lib.h"

Include dependency graph for strtok_s.c:

Functions
EXPORT char *	strtok_s (char restrict dest, rsize_t restrict dmax, const char restrict delim, char *restrict ptr)
	A sequence of calls to the strtok_s function breaks the string pointed to by dest into a sequence of tokens, each of which is delimited by a character from the string pointed to by delim. More...

Function Documentation

◆ strtok_s()

EXPORT char* strtok_s	(	char *restrict	dest,
		rsize_t *restrict	dmax,
		const char *restrict	delim,
		char **restrict	ptr
	)

A sequence of calls to the strtok_s function breaks the string pointed to by dest into a sequence of tokens, each of which is delimited by a character from the string pointed to by delim.

The fourth argument points to a caller-provided char pointer into which the strtok_s function stores information necessary for it to continue scanning the same string.

The first call in a sequence has a non-null first argument and dmax points to an object whose value is the number of elements in the character array pointed to by the first argument. The first call stores an initial value in the object pointed to by ptr and updates the value pointed to by dmax to reﬂect the number of elements that remain in relation to ptr. Subsequent calls in the sequence have a null first argument and the objects pointed to by dmax and ptr are required to have the values stored by the previous call in the sequence, which are then updated. The separator string pointed to by delim may be different from call to call.

The first call in the sequence searches the string pointed to by dest for the first character that is not contained in the current separator string pointed to by delim. If no such character is found, then there are no tokens in the string pointed to by dest and the strtok_s function returns a null pointer. If such a character is found, it is the start of the first token.

The strtok_s function then searches from there for the first character in dest that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by dest, and subsequent searches in the same string for a token return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token.

In all cases, the strtok_s function stores sufﬁcient information in the pointer pointed to by ptr so that subsequent calls, with a null pointer for dest and the unmodiﬁed pointer value for ptr, shall start searching just past the element overwritten by a null character (if any).

delim uses a STRTOK_DELIM_MAX_LEN of 16.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.7.3.1 The strtok_s function (p: 620-621) http://en.cppreference.com/w/c/string/byte/strok
ISO/IEC TR 24731-1, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to tokenize
[out]	dmax	restricted maximum length of dest string
[in]	delim	pointer to delimiter string (len < 255)
[out]	ptr	returned pointer to token

Precondition: delim shall not be a null pointer.; ptr shall not be a null pointer.; dmax shall not be a null pointer.; *dmax shall not be 0.; If dest is a null pointer, then *ptr shall not be a null pointer.; dest must not be unterminated.; The value of *dmax shall not be greater than RSIZE_MAX_STR. The end of the token found shall occur within the first *dmax characters of dest for the first call, and shall occur within the first *dmax characters of where searching resumes on subsequent calls.; delim must not be longer than STRTOK_DELIM_MAX_LEN (default: 16).

Note: The mingw MINGW_HAS_SECURE_API declares it without the dmax argument and without restrict. Skip it there. char* strtok_s (char *str, const char *delim, char **ctx); C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: The strtok_s function returns a pointer to the first character of a token; or a null pointer if there is no token or there is a runtime-constraint violation. Each call modifies dest by substituting a NULL character for the first delimiter that occurs after the returned token. If there is a runtime-constraint violation, the strtok_s function does not indirect through the dest/delim pointers, and does not store a value in the object pointed to by ptr.

errno is set to: ESNULLP when dest/delim/ptr is NULL pointer ESZEROL when *dmax = 0 ESLEMAX when *dmax > RSIZE_MAX_STR ESUNTERM when unterminated string C11 just returns EINVAL

Remarks: Example to demonstrate usage of strtok_s() to tokenize a string
// Approach1: sequential strtok_s() calls
str1 = ",.:*one,two;three,;four*.*.five-six***"; // String to tokenize
len = 38;
str2 = ",.;*"; // String of delimiters
p2tok = strtok_s(str1, &len, str2, &p2str);
// token: one, remaining: two;three,;four*.*.five-six***, len: 30
p2tok = strtok_s(NULL, &len, str2, &p2str);
// token: two, remaining: three,;four*.*.five-six***, len: 26
p2tok = strtok_s(NULL, &len, str2, &p2str);
// token: three, remaining: ;four*.*.five-six***, len: 20
p2tok = strtok_s(NULL, &len, str2, &p2str);
// token: four, remaining .*.five-six***, len: 14
p2tok = strtok_s(NULL, &len, str2, &p2str);
// token: five-six, remaining: **, len: 2
p2tok = strtok_s(NULL, &len, str2, &p2str);
// token: (null), remaining: **, len: 0
// Approach2: Use of while loop with same entry data as used above
p2tok = str1;
while (p2tok && len)
{
p2tok = strtok_s(NULL, &len, str2, &p2str);
printf(" token -- remaining -- len=0 \n", p2tok, p2str, (int)len );
}

Functions

Function Documentation

◆ strtok_s()