Contains those _s-functions that are related to strings. More...

#include "./base_.h"
#include "./stddef.h"
#include "./errno.h"

Functions
SLIBC_BEGIN_DECLS size_t	strnlen_s (const char *s, size_t maxsize)
	The strnlen_s function determines the length of s.
errno_t	strcpy_s (char restrict s1, rsize_t s1max, const char restrict s2)
	The strcpy_s function copies the string s2 to s1.
errno_t	strncpy_s (char restrict s1, rsize_t s1max, const char restrict s2, rsize_t n)
	The strncpy_s function copies not more than n characters from s2 to s1.
errno_t	strcat_s (char restrict s1, rsize_t s1max, const char restrict s2)
	The strcat_s function copies the string s2 to the end of s1.
errno_t	strncat_s (char restrict s1, rsize_t s1max, const char restrict s2, rsize_t n)
	The strncat_s function copies not more than n characters of the string s2 to the end of s1.
errno_t	memcpy_s (void restrict s1, rsize_t s1max, const void restrict s2, rsize_t n)
	The memcpy_s function copies n bytes from buffer s2 to buffer s1.
errno_t	memmove_s (void s1, rsize_t s1max, const void s2, rsize_t n)
	The memmove_s function copies n bytes from buffer s2 to buffer s1 while allowing the buffers to overlap.
char *	strtok_s (char restrict s1, rsize_t restrict s1max, const char restrict delim, char *restrict ptr)
	The strtok_s function breaks a string into smaller strings according to a specified delimiter.
errno_t	strerror_s (char *s, rsize_t maxsize, errno_t errnum)
	The strerror_s function returns a human-readable error message for a specified error number.
size_t	strerrorlen_s (errno_t errnum)
	The strerrorlen_s function determines the length of the error-message for a specified error number.

Detailed Description

Contains those _s-functions that are related to strings.

Function Documentation

errno_t memcpy_s	(	void *restrict	s1,
		rsize_t	s1max,
		const void *restrict	s2,
		rsize_t	n
	)

The memcpy_s function copies n bytes from buffer s2 to buffer s1.

Unlike the traditional memcpy function memcpy_s accepts a new parameter s1max for specifying the buffer size of s1. A runtime-constraint violation occurrs (instead of a buffer overflow) if s1 not large enough to hold n bytes of s2.

Runtime-constraints:

A runtime-constraint violation occurs if

either s1 or s2 is a null pointer.
s1 (as determined by s1max) is not large enough to hold the result.
s1 and s2 overlap.

Parameters:

[out]	s1	The destination buffer
[in]	s1max	The size of s1
[in]	s2	The source buffer
[in]	n	Amount of bytes to be copied

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

See also:: memcpy

errno_t memmove_s	(	void *	s1,
		rsize_t	s1max,
		const void *	s2,
		rsize_t	n
	)

The memmove_s function copies n bytes from buffer s2 to buffer s1 while allowing the buffers to overlap.

Unlike the traditional memmove function memmove_s accepts a new parameter s1max for specifying the buffer size of s1. A runtime-constraint violation occurrs (instead of a buffer overflow) if s1 not large enough to hold n bytes of s2.

Runtime-constraints:

A runtime-constraint violation occurs if

either s1 or s2 is a null pointer.
s1 (as determined by s1max) is not large enough to hold the result.

Remarks:: s1 and s2 are allowed to overlap.

Parameters:

[out]	s1	The destination buffer
[in]	s1max	The size of s1
[in]	s2	The source buffer
[in]	n	Amount of bytes to be copied

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

See also:: memmove

errno_t strcat_s	(	char *restrict	s1,
		rsize_t	s1max,
		const char *restrict	s2
	)

The strcat_s function copies the string s2 to the end of s1.

The string concatentation operation will overwrite the existing terminating null byte of s1. The buffer s1 must be large enough to accomodate both for s1, s2 and s2's terminating null byte. In contrast to the traditional strcat function, strcat_s expects its caller to explicitly specify the size of the destination buffer s1. This allows the function to check whether the supplied is indeed large enough.

Runtime-constraints:

A runtime-constraint violation occurs if

either s1 or s2 is a null pointer.
s1 (as determined by s1max) is not large enough to hold s1+s2.
s1 and s2 overlap.

Parameters:

[in,out]	s1	The destination buffer
[in]	s1max	The size of s1
[in]	s2	The source string

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

See also:: strcat

Referenced by strcat_s().

errno_t strcpy_s	(	char *restrict	s1,
		rsize_t	s1max,
		const char *restrict	s2
	)

The strcpy_s function copies the string s2 to s1.

Unlike the traditional strcpy, the size of the destination buffer s1 has to be specified. The function makes sure that it never writes outside the specified bounds.

The buffer s1 must be large enough for holding s2 plus the terminating null byte.

Postcondition:: As long as s1 is not null, the string in s1 will always be null-terminated.

Runtime-constraints:

A runtime-constraint violation occurs if

either s1 or s2 is a null pointer.
s1 (as determined by s1max) is not large enough to hold s2 (including its terminating null byte).
s1 and s2 overlap.

Parameters:

[out]	s1	The destination buffer
[in]	s1max	The size of s1
[in]	s2	The source string

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

Referenced by strcpy_s().

errno_t strerror_s	(	char *	s,
		rsize_t	maxsize,
		errno_t	errnum
	)

The strerror_s function returns a human-readable error message for a specified error number.

strerror_s copies the message to buffer s. The caller is expected to provide the length of s in parameter maxsize. If the buffer s is not big enough to hold the result, the error message is truncated and the last byte of s is set to the null byte.

Runtime-constraints:

A runtime-constraint violation occurs if

s is a null pointer

Parameters:

[out]	s	destination buffer for the error message
[in]	maxsize
[in]	errnum	the error number (typically from errno)

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

See also:: strerror, strerror_r

size_t strerrorlen_s ( errno_t errnum )

The strerrorlen_s function determines the length of the error-message for a specified error number.

You can use this function to find out how big the buffer passed to strerror_s shall be in order to have a non-truncated error mesage.

Parameters:

[in] errnum the error number

Returns:: The strerrorlen_s function returns the number of characters (not including the null character) in the error-message.

errno_t strncat_s	(	char *restrict	s1,
		rsize_t	s1max,
		const char *restrict	s2,
		rsize_t	n
	)

The strncat_s function copies not more than n characters of the string s2 to the end of s1.

The string concatentation operation will overwrite the existing terminating null byte of s1. The buffer s1 must be large enough to accomodate both for s1, s2 and s2's terminating null byte. In contrast to the traditional strcat function, strcat_s expects its caller to explicitly specify the size of the destination buffer s1. This allows the function to check whether the supplied is indeed large enough.

Runtime-constraints:

A runtime-constraint violation occurs if

either s1 or s2 is a null pointer.
s1 (as determined by s1max) is not large enough to hold the result.
s1 and s2 overlap.

Parameters:

[in,out]	s1	The destination buffer
[in]	s1max	The size of s1
[in]	s2	The source string
[in]	n	Maximum amount of characters that should be copied. (If s2 is shorter than n, less bytes are copied)

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

See also:: strncat

Referenced by strncat_s().

errno_t strncpy_s	(	char *restrict	s1,
		rsize_t	s1max,
		const char *restrict	s2,
		rsize_t	n
	)

The strncpy_s function copies not more than n characters from s2 to s1.

In contrast to strncpy this functions expects the buffer size of s1 as a second parameter. The function will never write beyond the specified buffer size.

Runtime-constraints:

A runtime-constraint violation occurs if

either s1 or s2 is a null pointer.
s1 (as determined by s1max) is not large enough to hold the source (including its terminating null byte).
s1 and s2 overlap.

Parameters:

[out]	s1	The destination buffer
[in]	s1max	The size of s1
[in]	s2	The source string
[in]	n	Maximum amount of characters that should be copied. (If s2 is shorter than n, less bytes are copied)

Returns:: 0 if there was no runtime-constraint violation. Otherwise a non-zero value is returned.

Referenced by strncpy_s().

SLIBC_BEGIN_DECLS size_t strnlen_s	(	const char *	s,
		size_t	maxsize
	)

The strnlen_s function determines the length of s.

At most maxsize characters are accessed and maxsize is returned. Otherwise the number of characters before the nullbyte are returned. The only difference to strnlen is that in case of s being a null pointer this function gracefully returns 0.

Runtime-constraints:: There are no runtime-constraints.

Parameters:

[in]	s	The string of whose length should be calculated
[in]	maxsize	Only maxsize characters should be accessed

Returns:: Zero if s is a null pointer. Maxsize characters if there is no nullbyte in the first maxsize chars of s. Otherwise the number of characters before the nullbyte.

See also:: strlen, strnlen

char* strtok_s	(	char *restrict	s1,
		rsize_t *restrict	s1max,
		const char *restrict	delim,
		char **restrict	ptr
	)

The strtok_s function breaks a string into smaller strings according to a specified delimiter.

A sequence of strok_s invocations is necessary to break up a string. On the first call, s1 points to the buffer to be tokenized, s1max denotes its size, delim points to the delimiter string, ptr points to a caller-provided char pointer. On successive calls, s1 should be NULL, while ptr should be unchanged from the previous call.

Remarks:: Please note that the buffer s1 will be modified by strok_s. If a delimiter is found in s1, it will be replaced with a null byte.

Parameters:

[in]	s1	on the first call: the buffer to be tokenized. On subsequent calls: Null
[in,out]	s1max	on the first call the caller supplies the size of s1 here. on subsequent calls the number is upated to reflect the number of characters in the current oken.
[in]	delim	the delimiter
[in,out]	ptr	used internally by strtok_s in order to maintain state between successive calls of this 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.

See also:: strtok, strtok_r

Functions

Detailed Description

Function Documentation