string.c File Reference

String Handling routines, including a performant implementation of many c-11 "safe" string functions. More...

Include dependency graph for string.c:

Go to the source code of this file.

Functions
void	clib_memswap (void *_a, void *_b, uword bytes)
void	clib_c11_violation (const char *s)
errno_t	memcpy_s (void *__restrict__ dest, rsize_t dmax, const void *__restrict__ src, rsize_t n)
	copy src to dest, at most n bytes, up to dmax More...
errno_t	memset_s (void *s, rsize_t smax, int c, rsize_t n)
	set n bytes starting at s to the specified c value More...
errno_t	memcmp_s (const void *s1, rsize_t s1max, const void *s2, rsize_t s2max, int *diff)
	compare memory until they differ, and their difference is returned in diff More...
errno_t	strcmp_s (const char *s1, rsize_t s1max, const char *s2, int *indicator)
	compare string s2 to string s1, and their difference is returned in indicator More...
errno_t	strncmp_s (const char *s1, rsize_t s1max, const char *s2, rsize_t n, int *indicator)
	compare string s2 to string s1, no more than n characters, and their difference is returned in indicator More...
errno_t	strcpy_s (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src)
	copy src string to dest string More...
errno_t	strncpy_s (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src, rsize_t n)
	copy src string to dest string, no more than n characters More...
errno_t	strcat_s (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src)
	append src string to dest string, including null More...
errno_t	strncat_s (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src, rsize_t n)
	append src string to dest string, including null, no more than n characters More...
char *	strtok_s (char *__restrict__ s1, rsize_t *__restrict__ s1max, const char *__restrict__ s2, char **__restrict__ ptr)
	tokenize string s1 with delimiter specified in s2. More...
size_t	strnlen_s (const char *s, size_t maxsize)
	compute the length in s, no more than maxsize More...
errno_t	strstr_s (char *s1, rsize_t s1max, const char *s2, rsize_t s2max, char **substring)
	locate the first occurrence of the substring s2 in s1 More...

Detailed Description

String Handling routines, including a performant implementation of many c-11 "safe" string functions.

Definition in file string.c.

Function Documentation

clib_c11_violation()

void clib_c11_violation

(

const char *

s

)

Definition at line 95 of file string.c.

Here is the caller graph for this function:

clib_memswap()

void clib_memswap	(	void *	_a,
		void *	_b,
		uword	bytes
	)

Definition at line 49 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

memcmp_s()

errno_t memcmp_s	(	const void *	s1,
		rsize_t	s1max,
		const void *	s2,
		rsize_t	s2max,
		int *	diff
	)

compare memory until they differ, and their difference is returned in diff

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s1	pointer to memory to compare against
s1max	maximum length of s1
*s2	pointer to memory to compare with s1
s2max	length of s2
*diff	pointer to the diff which is an integer greater than, equal to, or less than zero according to s1 is greater than, equal to, or less than s2.

No null pointers s1max and s2max shall not be zero s2max shall not be greater than s1max

Returns

EOK success diff when the return code is EOK >0 s1 greater s2 0 s1 == s2 <0 s1 < s2 EINVAL runtime constraint error

Definition at line 178 of file string.c.

Here is the call graph for this function:

memcpy_s()

errno_t memcpy_s	(	void *__restrict__	dest,
		rsize_t	dmax,
		const void *__restrict__	src,
		rsize_t	n
	)

copy src to dest, at most n bytes, up to dmax

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*dest	pointer to memory to copy to
dmax	maximum length of resulting dest
*src	pointer to memory to copy from
n	maximum number of characters to copy from src

No null pointers n shall not be greater than dmax no memory overlap between src and dest

Returns

EOK success EINVAL runtime constraint error

Definition at line 120 of file string.c.

Here is the call graph for this function:

memset_s()

errno_t memset_s	(	void *	s,
		rsize_t	smax,
		int	c,
		rsize_t	n
	)

set n bytes starting at s to the specified c value

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s	pointer to memory to set the c value
smax	maximum length of resulting s
c	byte value
n	maximum number of characters to set in s

No null pointers n shall not be greater than smax

Returns

EOK success EINVAL runtime constraint error

Definition at line 145 of file string.c.

Here is the call graph for this function:

strcat_s()

errno_t strcat_s	(	char *__restrict__	dest,
		rsize_t	dmax,
		const char *__restrict__	src
	)

append src string to dest string, including null

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*dest	pointer to string to append to
dmax	maximum length of resulting dest string, including null
*src	pointer to string to append from

No null pointers dmax shall not be zero dest shall be null terminated given m = dmax - strnlen (dest, dmax) n = strnlen (src, m) n shall not be >= m no memory overlap between src and dest

Returns

EOK success EINVAL runtime constraint error

Definition at line 328 of file string.c.

Here is the call graph for this function:

strcmp_s()

errno_t strcmp_s	(	const char *	s1,
		rsize_t	s1max,
		const char *	s2,
		int *	indicator
	)

compare string s2 to string s1, and their difference is returned in indicator

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s1	pointer to string to compare against
s1max	maximum length of s1, excluding null
*s2	pointer to string to compare with s1
*indicator	pointer to the comparison result, which is an integer greater than, equal to, or less than zero according to s1 is greater than, equal to, or less than s2.

No null pointers s1max shall not be zero s1 shall be null terminated n shall not be greater than the smaller of s1max and strlen of s1

Returns

EOK success indicator when the return code is EOK >0 s1 greater s2 0 s1 == s2 <0 s1 < s2 EINVAL runtime constraint error

Definition at line 213 of file string.c.

Here is the call graph for this function:

strcpy_s()

errno_t strcpy_s	(	char *__restrict__	dest,
		rsize_t	dmax,
		const char *__restrict__	src
	)

copy src string to dest string

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*dest	pointer to string to copy to
dmax	maximum length of resulting dest string, including null
*src	pointer to string to copy from

No null pointers dmax shall not be zero dmax shall be greater than string length of src no memory overlap between src and dest

Returns

EOK success EINVAL runtime constraint error

Definition at line 272 of file string.c.

Here is the call graph for this function:

strncat_s()

errno_t strncat_s	(	char *__restrict__	dest,
		rsize_t	dmax,
		const char *__restrict__	src,
		rsize_t	n
	)

append src string to dest string, including null, no more than n characters

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*dest	pointer to string to append to
dmax	maximum length of resulting dest string, including null
*src	pointer to string to append from
n	maximum characters to append (excluding null)

No null pointers dmax shall not be zero dest shall be null terminated dmax - strnlen (dest, dmax) shall not be zero no memory overlap between src and dest

Returns

EOK success EINVAL runtime constraint error EOVERFLOW truncated operation. dmax - 1 characters were appended. dest is null terminated.

Definition at line 358 of file string.c.

Here is the call graph for this function:

strncmp_s()

errno_t strncmp_s	(	const char *	s1,
		rsize_t	s1max,
		const char *	s2,
		rsize_t	n,
		int *	indicator
	)

compare string s2 to string s1, no more than n characters, and their difference is returned in indicator

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s1	pointer to string to compare against
s1max	maximum length of s1, excluding null
*s2	pointer to string to compare with s1
n	maximum number of characters to compare
*indicator	pointer to the comparison result, which is an integer greater than, equal to, or less than zero according to s1 is greater than, equal to, or less than s2.

No null pointers s1max shall not be zero s1 shall be null terminated

Returns

EOK success indicator when the return code is EOK >0 s1 greater s2 0 s1 == s2 <0 s1 < s2 EINVAL runtime constraint error

Definition at line 246 of file string.c.

Here is the call graph for this function:

strncpy_s()

errno_t strncpy_s	(	char *__restrict__	dest,
		rsize_t	dmax,
		const char *__restrict__	src,
		rsize_t	n
	)

copy src string to dest string, no more than n characters

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*dest	pointer to string to copy to
dmax	maximum length of resulting dest string, including null
*src	pointer to string to copy from
n	maximum number of characters to copy from src, excluding null

No null pointers dmax shall not be zero no memory overlap between src and dest

Returns

EOK success EINVAL runtime constraint error EOVERFLOW truncated operation. dmax - 1 characters were copied. dest is null terminated.

Definition at line 299 of file string.c.

Here is the call graph for this function:

strnlen_s()

size_t strnlen_s	(	const char *	s,
		size_t	maxsize
	)

compute the length in s, no more than maxsize

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s	pointer to string
maxsize	restricted maximum length

No null pointers maxsize shall not be zero

Returns

size_t the string length in s, excluding null character, and no more than maxsize or 0 if there is a constraint error

Definition at line 433 of file string.c.

Here is the call graph for this function:

Here is the caller graph for this function:

strstr_s()

errno_t strstr_s	(	char *	s1,
		rsize_t	s1max,
		const char *	s2,
		rsize_t	s2max,
		char **	substring
	)

locate the first occurrence of the substring s2 in s1

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s1	pointer to string to be searched for substring
s1max	restricted maximum length of s1
*s2	pointer to substring to search
s2max	restricted maximum length of s2
**substring	pointer to pointer substring to be returned

No null pointers s1max and s2max shall not be zero s1 and s2 shall be null terminated

Returns

EOK success substring when the return code is EOK, it contains the pointer which points to s1 that matches s2 EINVAL runtime constraint error ESRCH no match

Example: char *sub = 0; char *s1 = "success is not final, failure is not fatal.";

strstr_s (s1, strlen (s1), "failure", strlen ("failure"), &sub);

After the above call, sub = "failure is not fatal."

Definition at line 470 of file string.c.

Here is the call graph for this function:

strtok_s()

char* strtok_s	(	char *__restrict__	s1,
		rsize_t *__restrict__	s1max,
		const char *__restrict__	s2,
		char **__restrict__	ptr
	)

tokenize string s1 with delimiter specified in s2.

This is a stateful API when it is iterately called, it returns the next token from s1 which is delimited by s2. s1max and ptr maintain the stateful information for the same caller and must not be altered by the caller during the iteration for the correct result

ISO/IEC 9899:2017(C11), Porgramming languages – C Annex K; Bounds-checking interfaces

Parameters

*s1	pointer to string to be searched for substring
*s1max	restricted maximum length of s1
*s2	pointer to substring to search (16 characters max, including null)
**ptr	in/out pointer which maintains the stateful information

s2, s1max, and ptr shall not be null if s1 is null, contents of ptr shall not be null s1 and s2 shall be null terminated

Returns

non-null pointer to the first character of a token s1max and ptr are modified to contain the state null runtime constraint error or token is not found

Example: char *str2 = " "; char str1[100]; uword len; char *p2str = 0; char *tok1, *tok2, *tok3, *tok4, *tok5, *tok6, *tok7;

strncpy (str1, "brevity is the soul of wit", sizeof (str1)); len = strlen (str1); tok1 = strtok_s (str1, &len, str2, &p2str); tok2 = strtok_s (0, &len, str2, &p2str); tok3 = strtok_s (0, &len, str2, &p2str); tok4 = strtok_s (0, &len, str2, &p2str); tok5 = strtok_s (0, &len, str2, &p2str); tok6 = strtok_s (0, &len, str2, &p2str); tok7 = strtok_s (0, &len, str2, &p2str);

After the above series of calls, tok1 = "brevity", tok2 = "is", tok3 = "the", tok4 = "soul", tok5 = "of", tok6 = "wit", tok7 = null

Definition at line 410 of file string.c.

Here is the call graph for this function: