string.h File Reference

Optimized string handling code, including c11-compliant "safe C library" variants. More...

Include dependency graph for string.h:

Go to the source code of this file.

Macros
#define	clib_memcpy_fast(a, b, c)   memcpy(a,b,c)
#define	EINVAL   22
#define	ESRCH   3
#define	EOVERFLOW   75
#define	CLIB_STRING_MACRO_MAX   4096
#define	clib_memcpy(d, s, n)   memcpy_s_inline(d,n,s,n)
#define	clib_memset(s, c, n)   memset_s_inline(s,n,c,n)
#define	clib_memcmp(s1, s2, m1)
#define	clib_strnlen(s, m)   strnlen_s_inline(s,m)
#define	clib_strcmp(s1, s2)
#define	clib_strncmp(s1, s2, n)
#define	clib_strcpy(d, s)   strcpy_s_inline(d,CLIB_STRING_MACRO_MAX,s)
#define	clib_strncpy(d, s, n)   strncpy_s_inline(d,CLIB_STRING_MACRO_MAX,s,n)
#define	clib_strcat(d, s)   strcat_s_inline(d,CLIB_STRING_MACRO_MAX,s)
#define	clib_strncat(d, s, n)   strncat_s_inline(d,CLIB_STRING_MACRO_MAX,s,n)
#define	clib_strtok(s1, s2, p)
#define	STRTOK_DELIM_MAX_LEN   16
#define	clib_strstr(s1, s2)

Typedefs
typedef int	errno_t
typedef uword	rsize_t

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...
static errno_t	memcpy_s_inline (void *__restrict__ dest, rsize_t dmax, const void *__restrict__ src, rsize_t n)
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...
static errno_t	memset_s_inline (void *s, rsize_t smax, int c, rsize_t n)
static_always_inline void	clib_memcpy_le (u8 *dst, u8 *src, u8 len, u8 max_len)
static_always_inline void	clib_memcpy_le64 (u8 *dst, u8 *src, u8 len)
static_always_inline void	clib_memcpy_le32 (u8 *dst, u8 *src, u8 len)
static_always_inline void	clib_memset_u64 (void *p, u64 val, uword count)
static_always_inline void	clib_memset_u32 (void *p, u32 val, uword count)
static_always_inline void	clib_memset_u16 (void *p, u16 val, uword count)
static_always_inline void	clib_memset_u8 (void *p, u8 val, uword count)
static_always_inline uword	clib_count_equal_u64 (u64 *data, uword max_count)
static_always_inline uword	clib_count_equal_u32 (u32 *data, uword max_count)
static_always_inline uword	clib_count_equal_u16 (u16 *data, uword max_count)
static_always_inline uword	clib_count_equal_u8 (u8 *data, uword max_count)
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...
static errno_t	memcmp_s_inline (const void *s1, rsize_t s1max, const void *s2, rsize_t s2max, int *diff)
size_t	strnlen_s (const char *s, size_t maxsize)
	compute the length in s, no more than maxsize More...
static size_t	strnlen_s_inline (const char *s, size_t maxsize)
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...
static errno_t	strcmp_s_inline (const char *s1, rsize_t s1max, const char *s2, int *indicator)
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...
static errno_t	strncmp_s_inline (const char *s1, rsize_t s1max, const char *s2, rsize_t n, int *indicator)
errno_t	strcpy_s (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src)
	copy src string to dest string More...
static errno_t	strcpy_s_inline (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src)
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...
static errno_t	strncpy_s_inline (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src, rsize_t n)
errno_t	strcat_s (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src)
	append src string to dest string, including null More...
static errno_t	strcat_s_inline (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src)
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...
static errno_t	strncat_s_inline (char *__restrict__ dest, rsize_t dmax, const char *__restrict__ src, rsize_t n)
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...
static char *	strtok_s_inline (char *__restrict__ s1, rsize_t *__restrict__ s1max, const char *__restrict__ s2, char **__restrict__ ptr)
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...
static errno_t	strstr_s_inline (char *s1, rsize_t s1max, const char *s2, rsize_t s2max, char **substring)

Detailed Description

Optimized string handling code, including c11-compliant "safe C library" variants.

Definition in file string.h.

Macro Definition Documentation

#define clib_memcmp	(		s1,
			s2,
			m1
	)

Value:

({ int __diff = 0;                                     \
    memcmp_s_inline (s1, m1, s2, m1, &__diff);  \
    __diff; \
  })

Definition at line 737 of file string.h.

#define clib_memcpy	(		d,
			s,
			n
	)		memcpy_s_inline(d,n,s,n)

Definition at line 180 of file string.h.

#define clib_memcpy_fast	(		a,
			b,
			c
	)		memcpy(a,b,c)

Definition at line 81 of file string.h.

#define clib_memset	(		s,
			c,
			n
	)		memset_s_inline(s,n,c,n)

Definition at line 214 of file string.h.

#define clib_strcat	(		d,
			s
	)		strcat_s_inline(d,CLIB_STRING_MACRO_MAX,s)

Definition at line 1074 of file string.h.

#define clib_strcmp	(		s1,
			s2
	)

Value:

({ int __indicator = 0; \
    strcmp_s_inline (s1, CLIB_STRING_MACRO_MAX, s2, &__indicator);      \
    __indicator;                        \
  })

Definition at line 826 of file string.h.

#define clib_strcpy	(		d,
			s
	)		strcpy_s_inline(d,CLIB_STRING_MACRO_MAX,s)

Definition at line 938 of file string.h.

#define CLIB_STRING_MACRO_MAX   4096

Definition at line 111 of file string.h.

#define clib_strncat	(		d,
			s,
			n
	)		strncat_s_inline(d,CLIB_STRING_MACRO_MAX,s,n)

Definition at line 1135 of file string.h.

#define clib_strncmp	(		s1,
			s2,
			n
	)

Value:

({ int __indicator = 0; \
    strncmp_s_inline (s1, CLIB_STRING_MACRO_MAX, s2, n, &__indicator);  \
    __indicator;                        \
  })

Definition at line 880 of file string.h.

#define clib_strncpy	(		d,
			s,
			n
	)		strncpy_s_inline(d,CLIB_STRING_MACRO_MAX,s,n)

Definition at line 995 of file string.h.

#define clib_strnlen	(		s,
			m
	)		strnlen_s_inline(s,m)

Definition at line 785 of file string.h.

#define clib_strstr	(		s1,
			s2
	)

Value:

({ char * __substring = 0; \
    strstr_s_inline (s1, CLIB_STRING_MACRO_MAX, s2, CLIB_STRING_MACRO_MAX, \
                     &__substring);              \
    __substring;                                 \
  })

Definition at line 1366 of file string.h.

#define clib_strtok	(		s1,
			s2,
			p
	)

Value:

({ rsize_t __s1max = CLIB_STRING_MACRO_MAX;     \
    strtok_s_inline (s1, &__s1max, s2, p);              \
  })

Definition at line 1214 of file string.h.

#define EINVAL   22

Definition at line 93 of file string.h.

#define EOVERFLOW   75

Definition at line 99 of file string.h.

#define ESRCH   3

Definition at line 96 of file string.h.

#define STRTOK_DELIM_MAX_LEN   16

Typedef Documentation

typedef int errno_t

Definition at line 113 of file string.h.

typedef uword rsize_t

Definition at line 114 of file string.h.

Function Documentation

void clib_c11_violation

(

const char *

s

)

Definition at line 95 of file string.c.

Here is the caller graph for this function:

static_always_inline uword clib_count_equal_u16	(	u16 *	data,
		uword	max_count
	)

Definition at line 588 of file string.h.

Here is the call graph for this function:

static_always_inline uword clib_count_equal_u32	(	u32 *	data,
		uword	max_count
	)

Definition at line 520 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

static_always_inline uword clib_count_equal_u64	(	u64 *	data,
		uword	max_count
	)

Definition at line 470 of file string.h.

Here is the call graph for this function:

static_always_inline uword clib_count_equal_u8	(	u8 *	data,
		uword	max_count
	)

Definition at line 656 of file string.h.

Here is the call graph for this function:

static_always_inline void clib_memcpy_le	(	u8 *	dst,
		u8 *	src,
		u8	len,
		u8	max_len
	)

Definition at line 217 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

static_always_inline void clib_memcpy_le32	(	u8 *	dst,
		u8 *	src,
		u8	len
	)

Definition at line 289 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

static_always_inline void clib_memcpy_le64	(	u8 *	dst,
		u8 *	src,
		u8	len
	)

Definition at line 283 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

static_always_inline void clib_memset_u16	(	void *	p,
		u16	val,
		uword	count
	)

Definition at line 378 of file string.h.

Here is the caller graph for this function:

static_always_inline void clib_memset_u32	(	void *	p,
		u32	val,
		uword	count
	)

Definition at line 332 of file string.h.

static_always_inline void clib_memset_u64	(	void *	p,
		u64	val,
		uword	count
	)

Definition at line 295 of file string.h.

static_always_inline void clib_memset_u8	(	void *	p,
		u8	val,
		uword	count
	)

Definition at line 424 of file string.h.

Here is the caller graph for this function:

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:

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:

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

inlinestatic

Definition at line 747 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 121 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 185 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 1080 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 836 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 944 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 1141 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 890 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 1002 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

static size_t strnlen_s_inline ( const char *  s, size_t  maxsize  )

inlinestatic

Definition at line 790 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 1377 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function:

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:

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

inlinestatic

Definition at line 1223 of file string.h.

Here is the call graph for this function:

Here is the caller graph for this function: