#include "safe_config.h"
#include "safe_lib_errno.h"
#include "safe_types.h"
#include "safe_compile.h"
#include <stdarg.h>
#include <time.h>
#include <wchar.h>

Include dependency graph for safe_str_lib.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	EXTERN extern

#define	SAFECLIB_UNICODE_VERSION 15
	With this UCD version we generated our tables.

#define	RSIZE_MIN_STR (1)
	The shortest string is a null string!!

#define	RSIZE_MAX_WSTR (RSIZE_MAX_STR / sizeof(wchar_t))
	wide chars

#define	SAFE_STR_MIN_LOWERCASE (2)
	The makeup of a password.

#define	SAFE_STR_MIN_UPPERCASE (2)

#define	SAFE_STR_MIN_NUMBERS (1)

#define	SAFE_STR_MIN_SPECIALS (1)

#define	SAFE_STR_PASSWORD_MIN_LENGTH (6)

#define	SAFE_STR_PASSWORD_MAX_LENGTH (32)

#define	sl_default_handler ignore_handler_s

#define	strcat_s(dest, dmax, src) _strcat_s_chk(dest, dmax, src, BOS(dest))
	The strcat_s function appends a copy of the string pointed to by src (including the terminating NUL character) to the end of the string pointed to by dest.

#define	strcpy_s(dest, dmax, src) _strcpy_s_chk(dest, dmax, src, BOS(dest))
	The strcpy_s function copies the string pointed to by src (including the terminating NUL character) into the array pointed to by dest.

#define	strncat_s(dest, dmax, src, slen) _strncat_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))
	The strncat_s function appends a copy of the string pointed to by src (including the terminating NUL character) to the end of the string pointed to by dest.

#define	strncpy_s(dest, dmax, src, slen) _strncpy_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))
	The strncpy_s function copies not more than slen successive characters (characters that follow a NUL character are not copied) from the array pointed to by src to the array pointed to by dest.

#define	strnlen_s(str, smax) _strnlen_s_chk(str, smax, BOS(str))
	The strnlen_s function computes the length of the string pointed to by `str`, refusing to read past smax.

#define	strtok_s(dest, dmaxp, delim, ptr) _strtok_s_chk(dest, dmaxp, delim, ptr, BOS(dest))
	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.

#define	vsprintf_s(dest, dmax, fmt, ap) _vsprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)
	The vsprintf_s function composes a string with the same content that would be printed if format was used on `printf`.

#define	vsnprintf_s(dest, dmax, fmt, ap) _vsnprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)
	The truncating `vsnprintf_s` function composes a string with same test that would be printed if format was used on `printf`.

#define	strerror_s(dest, dmax, errnum) _strerror_s_chk(dest, dmax, errnum, BOS(dest))
	The `strerror_s` function returns a pointer to the textual description of the system error code errnum, identical to the description that would be printed by perror().

#define	stpcpy_s(dest, dmax, src, errp) _stpcpy_s_chk(dest, dmax, src, errp, BOS(dest), BOS(src))
	The stpcpy_s function copies the string pointed to by src (including the terminating NUL character) into the array pointed to by dest.

#define	stpncpy_s(dest, dmax, src, slen, errp) _stpncpy_s_chk(dest, dmax, src, slen, errp, BOS(dest), BOS(src))
	The strncpy_s function copies max slen bytes of the string pointed to by src (excluding the terminating NUL character) into the array pointed to by dest.

#define	strcmp_s(dest, dmax, src, resultp) _strcmp_s_chk(dest, dmax, src, resultp, BOS(dest), BOS(src))
	Compares string src to string dest.

#define	strcasecmp_s(dest, dmax, src, resultp) _strcasecmp_s_chk(dest, dmax, src, resultp, BOS(dest))
	Case insensitive string comparison by converting to uppercase prior to the compare.

#define	strnatcmp_s(dest, dmax, src, resultp) _strnatcmp_s_chk(dest, dmax, src, 0, resultp, BOS(dest), BOS(src))
	Natural order comparison of strings.

#define	strnatcasecmp_s(dest, dmax, src, resultp) _strnatcasecmp_s_chk(dest, dmax, src, 1, resultp, BOS(dest), BOS(src))

#define	strcasestr_s(dest, dmax, src, slen, substring) _strcasestr_s_chk(dest, dmax, src, slen, substring, BOS(dest), BOS(src))
	The strcasestr_s() function locates the first occurrence of the substring pointed to by src which would be located in the string pointed to by dest.

#define	strcmpfld_s(dest, dmax, src, resultp) _strcmpfld_s_chk(dest, dmax, src, resultp, BOS(dest))
	Compares the character array pointed to by src to the character array pointed to by dest for dmax characters.

#define	strcpyfld_s(dest, dmax, src, slen) _strcpyfld_s_chk(dest, dmax, src, slen, BOS(dest))

#define	strcpyfldin_s(dest, dmax, src, slen) _strcpyfldin_s_chk(dest, dmax, src, slen, BOS(dest))

#define	strcpyfldout_s(dest, dmax, src, slen) _strcpyfldout_s_chk(dest, dmax, src, slen, BOS(dest))

#define	strcspn_s(dest, dmax, src, slen, countp) _strcspn_s_chk(dest, dmax, src, slen, countp, BOS(dest), BOS(src))
	This function computes the prefix length of the string pointed to by dest which consists entirely of characters that are excluded from the string pointed to by src.

#define	strfirstchar_s(dest, dmax, c, firstp) _strfirstchar_s_chk(dest, dmax, c, firstp, BOS(dest))
	This function returns a pointer to the first occurrence of character c in dest.

#define	strfirstdiff_s(dest, dmax, src, resultp) _strfirstdiff_s_chk(dest, dmax, src, resultp, BOS(dest))
	Returns the index of the first character that is different between dest and src.

#define	strisalphanumeric_s(dest, dmax) _strisalphanumeric_s_chk(dest, dmax, BOS(dest))
	This function checks if the entire string contains alphanumerics.

#define	strisascii_s(dest, dmax) _strisascii_s_chk(dest, dmax, BOS(dest))
	This function checks if the entire string contains ascii characters.

#define	strisdigit_s(dest, dmax) _strisdigit_s_chk(dest, dmax, BOS(dest))
	This function checks that the entire string contains digits.

#define	strishex_s(dest, dmax) _strishex_s_chk(dest, dmax, BOS(dest))
	This function checks that the entire string contains hex characters.

#define	strislowercase_s(dest, dmax) _strislowercase_s_chk(dest, dmax, BOS(dest))
	This function checks if entire string is lowercase.

#define	strismixedcase_s(dest, dmax) _strismixedcase_s_chk(dest, dmax, BOS(dest))
	This function checks that the entire string is mixed case.

#define	strispassword_s(dest, dmax) _strispassword_s_chk(dest, dmax, BOS(dest))
	This function validates the make-up of a password string.

#define	strisuppercase_s(dest, dmax) _strisuppercase_s_chk(dest, dmax, BOS(dest))
	This function checks if entire string is uppercase The scanning stops at the first null or after dmax characters.

#define	strlastchar_s(dest, dmax, c, lastp) _strlastchar_s_chk(dest, dmax, c, lastp, BOS(dest))
	Returns a pointer to the last occurrence of character c in dest.

#define	strlastdiff_s(dest, dmax, src, resultp) _strlastdiff_s_chk(dest, dmax, src, resultp, BOS(dest))
	Returns the index of the last character that is different between dest and src.

#define	strljustify_s(dest, dmax) _strljustify_s_chk(dest, dmax, BOS(dest))
	Removes beginning whitespace from the string pointed to by dest by shifting the text left over writting the beginning whitespace, left justifying the text.

#define	strnterminate_s(dest, dmax) _strnterminate_s_chk(dest, dmax, BOS(dest))
	The strnterminate_s function will terminate the string if a null is not encountered before dmax characters.

#define	strpbrk_s(dest, dmax, src, slen, firstp) _strpbrk_s_chk(dest, dmax, src, slen, firstp, BOS(dest), BOS(src))
	Returns a pointer, first, to the first ocurrence of any character in src which is contained in dest.

#define	strfirstsame_s(dest, dmax, src, resultp) _strfirstsame_s_chk(dest, dmax, src, resultp, BOS(dest))
	Returns the index of the first character that is the same between dest and src.

#define	strlastsame_s(dest, dmax, src, resultp) _strlastsame_s_chk(dest, dmax, src, resultp, BOS(dest))
	Returns the index of the last character that is the same between dest and src.

#define	strprefix_s(dest, dmax, src) _strprefix_s_chk(dest, dmax, src, BOS(dest))
	Determines if the prefix pointed to by src is at the beginning of string pointed to by dest.

#define	strremovews_s(dest, dmax) _strremovews_s_chk(dest, dmax, BOS(dest))
	Removes beginning and trailing whitespace from the string pointed to by dest by shifting the text left over writting the beginning whitespace (space or tab).

#define	strspn_s(dest, dmax, src, slen, countp) _strspn_s_chk(dest, dmax, src, slen, countp, BOS(dest), BOS(src))
	This function computes the prefix length of the string pointed to by dest which consists entirely of characters that are included from the string pointed to by src.

#define	strstr_s(dest, dmax, src, slen, substringp) _strstr_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))
	The strstr_s() function locates the first occurrence of the substring pointed to by src which would be located in the string pointed to by dest.

#define	strchr_s(dest, dmax, ch, resultp) _strchr_s_chk(dest, dmax, ch, resultp, BOS(dest))
	Finds the first occurrence of ch (after conversion to char as if by (char)ch) in the null-terminated byte string pointed to by dest (each character interpreted as unsigned char).

#define	strrchr_s(dest, dmax, ch, resultp) _strrchr_s_chk(dest, dmax, ch, resultp, BOS(dest))
	Finds the last occurrence of ch (after conversion to char as if by (char)ch) in the null-terminated byte string pointed to by dest (each character interpreted as unsigned char).

#define	strtolowercase_s(dest, dmax) _strtolowercase_s_chk(dest, dmax, BOS(dest))
	Converts all uppercase characters to lowercase, leaving all other characters unchanged.

#define	strtouppercase_s(dest, dmax) _strtouppercase_s_chk(dest, dmax, BOS(dest))
	Converts all lowercase characters to uppercase, leaving all other characters unchanged.

#define	strlwr_s(str, slen) strtolowercase_s((str), (slen))

#define	strupr_s(str, slen) strtouppercase_s((str), (slen))

#define	strzero_s(dest, dmax) _strzero_s_chk(dest, dmax, BOS(dest))
	Nulls maximal dmax characters of dest.

#define	strcoll_s(dest, dmax, src, resultp) _strcoll_s_chk(dest, dmax, src, resultp, BOS(dest))
	Compares two null-terminated byte strings according to the current locale as defined by the `LC_COLLATE` category.

#define	strset_s(dest, dmax, value) _strset_s_chk(dest, dmax, value, BOS(dest))
	Sets maximal dmax characters of dest to a character value, but not the final NULL character.

#define	strnset_s(dest, dmax, value, n) _strnset_s_chk(dest, dmax, value, n, BOS(dest))
	Sets maximal n characters of dest to a character value, but not the final NULL character.

#define	mbstowcs_s(retvalp, dest, dmax, src, len) _mbstowcs_s_chk(retvalp, dest, dmax, src, len, BOS(dest))
	The `mbstowcs_s` function converts a null-terminated multibyte character sequence from the current LC_CTYPE locale to wchar, which begins in the conversion state described by `ps`, from the array whose first element is pointed to by `src` to its wide character representation.

#define	mbsrtowcs_s(retvalp, dest, dmax, srcp, len, ps) _mbsrtowcs_s_chk(retvalp, dest, dmax, srcp, len, ps, BOS(dest))
	Does not permit the `ps` parameter (the pointer to the conversion state) to be a null pointer.

#define	wcsrtombs_s(retvalp, dest, dmax, srcp, len, ps) _wcsrtombs_s_chk(retvalp, dest, dmax, srcp, len, ps, BOS(dest))
	Does not permit the `ps` parameter (the pointer to the conversion state) to be a null pointer.

#define	wcstombs_s(retvalp, dest, dmax, src, len) _wcstombs_s_chk(retvalp, dest, dmax, src, len, BOS(dest))
	The `wcstombs_s` function converts a sequence of wide characters from the array whose first element is pointed to by `src` to to its narrow multibyte representation from the current LC_CTYPE locale.

#define	wcrtomb_s(retvalp, dest, dmax, wc, ps) _wcrtomb_s_chk(retvalp, dest, dmax, wc, ps, BOS(dest))
	Does not permit the `ps` parameter (the pointer to the conversion state) to be a null pointer.

#define	wctomb_s(retvalp, dest, dmax, wc) _wctomb_s_chk(retvalp, dest, dmax, wc, BOS(dest))
	The `wctomb_s` function converts a single wide character to its narrow multibyte representation from the current LC_CTYPE locale.

#define	wcsnlen_s(str, smax) _wcsnlen_s_chk(str, smax, BOS(str))
	The wcsnlen_s function computes the length of the wide string pointed to by str, providing limited support for non-zero terminated strings.

#define	wcscpy_s(dest, dmax, src) _wcscpy_s_chk(dest, dmax, src, BOS(dest))
	The `wcscpy_s` function copies the string pointed to by `src` (including the terminating NUL character) into the array pointed to by dest.

#define	wcsncpy_s(dest, dmax, src, slen) _wcsncpy_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))
	The wcsncpy_s function copies the wide string pointed to by src (including the terminating NUL character) into the wide string pointed to by dest.

#define	wcscat_s(dest, dmax, src) _wcscat_s_chk(dest, dmax, src, BOS(dest))
	The wcscat_s function appends a copy of the wide string pointed to by src (including the terminating NUL character) to the end of the wide string pointed to by dest.

#define	wcsncat_s(dest, dmax, src, slen) _wcsncat_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))
	The wcsncat_s function appends a copy of the wide string pointed to by src (including the terminating null wide character) to the end of the wide string pointed to by dest.

#define	wcstok_s(dest, dmaxp, delim, ptr) _wcstok_s_chk(dest, dmaxp, delim, ptr, BOS(dest))
	A sequence of calls to the wcstok_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.

#define	swprintf_s(dest, dmax, ...) _swprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)

#define	vswprintf_s(dest, dmax, fmt, ap) _vswprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

#define	vsnwprintf_s(dest, dmax, fmt, ap) _vsnwprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)
	The truncating `vsnwprintf_s` function composes a wide string with same test that would be printed if format was used on `wprintf`.

#define	wcsstr_s(dest, dmax, src, slen, substringp) _wcsstr_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))
	The wcsstr_s() function locates the first occurrence of the wide substring pointed to by `src` which would be located in the wide string pointed to by `dest`.

#define	wcscmp_s(dest, dmax, src, smax, resultp) _wcscmp_s_chk(dest, dmax, src, smax, resultp, BOS(dest), BOS(src))
	Compares wide string src to wide string dest.

#define	wcsncmp_s(dest, dmax, src, smax, count, resultp) _wcsncmp_s_chk(dest, dmax, src, smax, count, resultp, BOS(dest), BOS(src))
	Compares at most count wide characters of wide string src with wide string dest, and returns if difference in the last parameter.

#define	wcsicmp_s(dest, dmax, src, smax, resultp) _wcsicmp_s_chk(dest, dmax, src, smax, resultp, BOS(dest), BOS(src))
	Compares two wide strings case-folded, via `wcsfc_s()`, i.e.

#define	wcsnatcmp_s(dest, dmax, src, smax, resultp) _wcsnatcmp_s_chk(dest, dmax, src, smax, 0, resultp, BOS(dest), BOS(src))

#define	wcsnaticmp_s(dest, dmax, src, smax, resultp) _wcsnatcmp_s_chk(dest, dmax, src, smax, 1, resultp, BOS(dest), BOS(src))
	Natural order comparison of strings.

#define	wcsset_s(dest, dmax, value) _wcsset_s_chk(dest, dmax, value, BOS(dest))
	Sets maximal dmax wide characters of dest to a wide character value, but not the final NULL character.

#define	wcsnset_s(dest, dmax, value, n) _wcsnset_s_chk(dest, dmax, value, n, BOS(dest))
	Sets maximal n wide characters of dest to a wide character value, but not the final NULL character.

#define	wcscoll_s(dest, dmax, src, smax, resultp) _wcscoll_s_chk(dest, dmax, src, smax, resultp, BOS(dest), BOS(src))
	Compares two null-terminated wide strings according to the current locale as defined by the `LC_COLLATE` category.

#define	wcslwr_s(src, slen) _wcslwr_s_chk(src, slen, BOS(src))
	Scans the string converting uppercase characters to simple lowercase, leaving all other characters unchanged.

#define	wcsupr_s(src, slen) _wcsupr_s_chk(src, slen, BOS(src))
	Scans the string converting lowercase characters to uppercase, leaving all other characters unchanged.

#define	towfc_s(dest, dmax, src) _towfc_s_chk(dest, dmax, src, BOS(dest))
	`towfc_s()` converts a wide character to fully fold-cased (lowercased with possible expansions), according to the Unicode 10.0 CaseFolding table.

#define	wcsfc_s(dest, dmax, src, lenp) _wcsfc_s_chk(dest, dmax, src, lenp, BOS(dest))
	Converts the wide string via full case-folding NFD normalized to lowercase.

#define	wcsnorm_decompose_s(dest, dmax, src, lenp, iscompat) _wcsnorm_decompose_s_chk(dest, dmax, src, lenp, iscompat, BOS(dest))
	Converts the wide string to the canonical NFD normalization, as defined in the latest Unicode standard.

#define	wcsnorm_reorder_s(dest, dmax, src, len) _wcsnorm_reorder_s_chk(dest, dmax, src, len, BOS(dest))
	Reorder all decomposed sequences in a wide string to NFD, as defined in the latest Unicode standard.

#define	wcsnorm_compose_s(dest, dmax, src, lenp, iscontig) _wcsnorm_compose_s_chk(dest, dmax, src, lenp, iscontig, BOS(dest))
	Combine all decomposed sequences in a wide string to NFC, as defined in the latest Unicode standard.

#define	wcsnorm_s(dest, dmax, src, mode, lenp) _wcsnorm_s_chk(dest, dmax, src, mode, lenp, BOS(dest))
	Converts the wide string to the canonical NFC or NFD normalization, as defined in the latest Unicode standard.

Functions
EXTERN void	abort_handler_s (const char restrict msg, void restrict ptr, errno_t error)
	This function writes a message on the standard error stream in an implementation-defined format.

EXTERN void	ignore_handler_s (const char restrict msg, void restrict ptr, errno_t error)
	This function simply returns to the caller.

EXTERN constraint_handler_t	set_str_constraint_handler_s (constraint_handler_t handler)
	The set_str_constraint_handler_s function sets the runtime-constraint handler to be handler.

EXTERN constraint_handler_t	thrd_set_str_constraint_handler_s (constraint_handler_t handler)
	The thrd_set_str_constraint_handler_s function sets the runtime-constraint handler to a thread-local handler.

EXTERN errno_t	_strcat_s_chk (char restrict dest, rsize_t dmax, const char restrict src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)

EXTERN errno_t	_strcpy_s_chk (char restrict dest, rsize_t dmax, const char restrict src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)

EXTERN errno_t	_strncat_s_chk (char restrict dest, rsize_t dmax, const char restrict src, rsize_t slen, const size_t destbos, const size_t srcbos) BOS_ATTR((slen\|\|dest\|\|dmax) &&(_BOS_NULL(dest)\|\|_BOS_ZERO(dest

EXTERN errno_t empty dest or dmax	BOS_ATTR ((slen\|\|dest\|\|dmax) &&_BOS_OVR(dest, dmax), "dest overflow") BOS_OVR2_BUTZERO(src

EXTERN errno_t	_strncpy_s_chk (char restrict dest, rsize_t dmax, const char restrict src, rsize_t slen, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2_BUTZERO(src

EXTERN rsize_t	_strnlen_s_chk (const char *str, rsize_t smax, size_t strbos) BOS_CHK2(str

EXTERN char *	_strtok_s_chk (char restrict dest, rsize_t restrict dmaxp, const char restrict delim, char *restrict ptr, const size_t destbos) BOS_OVR2_BUTNULL(dest

EXTERN char *dmaxp	BOS_ATTR (dest &&_BOS_NULL(dmaxp), "empty dmax") BOS_NULL(delim) BOS_NULL(ptr)

EXTERN int	sprintf_s (char restrict dest, rsize_t dmax, const char restrict fmt,...) __attribute_format__(printf

EXTERN int	BOS_CHK (dest) BOS_FMT(fmt)

EXTERN int	_vsprintf_s_chk (char restrict dest, rsize_t dmax, const size_t destbos, const char restrict fmt, va_list ap) BOS_CHK(dest) BOS_FMT(fmt)

EXTERN int	snprintf_s (char restrict dest, rsize_t dmax, const char restrict fmt,...) __attribute_format__(printf

EXTERN int	_vsnprintf_s_chk (char restrict dest, rsize_t dmax, const size_t destbos, const char restrict fmt, va_list ap) BOS_CHK(dest) BOS_FMT(fmt)

EXTERN int	sscanf_s (const char restrict buffer, const char restrict fmt,...) __attribute_format__(scanf

EXTERN int	BOS_NULL (buffer) BOS_FMT(fmt)

EXTERN int	fscanf_s (FILE restrict stream, const char restrict fmt,...) __attribute_format__(scanf

EXTERN int	BOS_NULL (stream) BOS_FMT(fmt)

EXTERN int	scanf_s (const char *restrict fmt,...) __attribute_format__(scanf

EXTERN int	BOS_FMT (fmt)

EXTERN int	vscanf_s (const char *restrict fmt, va_list ap) BOS_FMT(fmt)
	The `vscanf_s` function reads a formatted string from stdin, and writes to a list of arguments.

EXTERN int	vfscanf_s (FILE restrict stream, const char restrict fmt, va_list ap) BOS_NULL(stream) BOS_FMT(fmt)
	The `vfscanf_s` function reads a formatted string from a buffered FILE stream, and writes to a list of arguments.

EXTERN int	vsscanf_s (const char restrict dest, const char restrict fmt, va_list ap) BOS_NULL(dest) BOS_FMT(fmt)
	The `vsscanf_s` function reads a formatted string, and writes to a list of arguments.

EXTERN int	printf_s (const char *restrict fmt,...) __attribute_format__(printf

EXTERN int	fprintf_s (FILE restrict stream, const char restrict fmt,...) __attribute_format__(printf

EXTERN int	vprintf_s (const char *restrict fmt, va_list ap) BOS_FMT(fmt)
	The vprintf_s function composes a string via the format string and writes it to a FILE buffer.

EXTERN int	vfprintf_s (FILE restrict stream, const char restrict fmt, va_list arg) BOS_FMT(fmt)
	The vfprintf_s function composes a string via the format string and writes it to a FILE buffer.

EXTERN errno_t	_strerror_s_chk (char *dest, rsize_t dmax, errno_t errnum, const size_t destbos) BOS_CHK(dest)

EXTERN size_t	strerrorlen_s (errno_t errnum)
	The `strerrorlen_s` function returns the untruncated length of the textual description of the system error code `errnum`, identical to the description that would be printed by `perror()`.

EXTERN char *	_stpcpy_s_chk (char restrict dest, rsize_t dmax, const char restrict src, errno_t *restrict errp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(errp)

EXTERN char *	_stpncpy_s_chk (char restrict dest, rsize_t dmax, const char restrict src, rsize_t slen, errno_t *restrict errp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK2(src

EXTERN char slen	BOS_NULL (errp)

EXTERN errno_t	_strcmp_s_chk (const char dest, rsize_t dmax, const char src, int *resultp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strcasecmp_s_chk (const char dest, rsize_t dmax, const char src, int *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strnatcmp_s_chk (const char dest, rsize_t dmax, const char src, const int fold_case, int *resultp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strcasestr_s_chk (char dest, rsize_t dmax, const char src, rsize_t slen, char **substring, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK2(src

EXTERN errno_t slen	BOS_NULL (substring)

EXTERN errno_t	_strcmpfld_s_chk (const char dest, rsize_t dmax, const char src, int *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strcpyfld_s_chk (char dest, const rsize_t dmax, const char src, rsize_t slen, const size_t destbos) BOS_CHK_BUTZERO(dest

EXTERN errno_t slen	BOS_OVR2_BUTZERO (src, slen) VAL_OVR2(slen

EXTERN errno_t	_strcpyfldin_s_chk (char dest, rsize_t dmax, const char src, rsize_t slen, const size_t destbos) BOS_CHK_BUTZERO(dest

EXTERN errno_t	_strcpyfldout_s_chk (char dest, rsize_t dmax, const char src, rsize_t slen, const size_t destbos) BOS_CHK_BUTZERO(dest

EXTERN errno_t	_strcspn_s_chk (const char dest, rsize_t dmax, const char src, rsize_t slen, rsize_t *countp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src

EXTERN errno_t slen	BOS_NULL (countp)

EXTERN errno_t	_strfirstchar_s_chk (char dest, rsize_t dmax, char c, char *firstp, const size_t destbos) BOS_CHK(dest) BOS_NULL(firstp)

EXTERN errno_t	_strfirstdiff_s_chk (const char dest, rsize_t dmax, const char src, rsize_t *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN bool	_strisalphanumeric_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strisascii_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strisdigit_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strishex_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strislowercase_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strismixedcase_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strispassword_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN bool	_strisuppercase_s_chk (const char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN errno_t	_strlastchar_s_chk (char dest, rsize_t dmax, char c, char *lastp, const size_t destbos) BOS_CHK(dest) BOS_NULL(lastp)

EXTERN errno_t	_strlastdiff_s_chk (const char dest, rsize_t dmax, const char src, rsize_t *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strljustify_s_chk (char *dest, rsize_t dmax, const size_t destbos) BOS_CHK(dest)

EXTERN rsize_t	_strnterminate_s_chk (char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN errno_t	_strpbrk_s_chk (char dest, rsize_t dmax, char src, rsize_t slen, char **firstp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src

EXTERN errno_t slen	BOS_NULL (firstp)

EXTERN errno_t	_strfirstsame_s_chk (const char dest, rsize_t dmax, const char src, rsize_t *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strlastsame_s_chk (const char dest, rsize_t dmax, const char src, rsize_t *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strprefix_s_chk (const char dest, rsize_t dmax, const char src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)

EXTERN errno_t	_strremovews_s_chk (char *dest, rsize_t dmax, const size_t destbos) BOS_CHK(dest)

EXTERN errno_t	_strspn_s_chk (const char dest, rsize_t dmax, const char src, rsize_t slen, rsize_t *countp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK2(src

EXTERN errno_t	_strstr_s_chk (char dest, rsize_t dmax, const char src, rsize_t slen, char **substringp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src

EXTERN errno_t slen	BOS_NULL (substringp)

EXTERN errno_t	_strchr_s_chk (const char restrict dest, rsize_t dmax, const int ch, char *restrict resultp, const size_t destbos) BOS_CHK(dest) VAL_OVR2(ch

EXTERN errno_t	BOS_NULL (resultp)

EXTERN errno_t	_strrchr_s_chk (const char restrict dest, rsize_t dmax, const int ch, char *restrict resultp, const size_t destbos) BOS_CHK(dest) VAL_OVR2(ch

EXTERN errno_t	_strtolowercase_s_chk (char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN errno_t	_strtouppercase_s_chk (char *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest

EXTERN errno_t	_strzero_s_chk (char *dest, rsize_t dmax, const size_t destbos) BOS_CHK(dest)

EXTERN errno_t	_strcoll_s_chk (const char restrict dest, rsize_t dmax, const char restrict src, int *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)

EXTERN errno_t	_strset_s_chk (char *restrict dest, rsize_t dmax, int value, const size_t destbos) BOS_CHK(dest) VAL_OVR2(value

EXTERN errno_t	_strnset_s_chk (char *restrict dest, rsize_t dmax, int value, rsize_t n, const size_t destbos) BOS_CHK(dest) BOS_OVR2_BUTZERO(dest

EXTERN errno_t n	VAL_OVR2 (value, 255) VAL_OVR2_BUTZERO(n

EXTERN errno_t	_mbstowcs_s_chk (size_t restrict retvalp, wchar_t restrict dest, rsize_t dmax, const char *restrict src, rsize_t len, const size_t destbos) BOS_ATTR(!_BOS_NULL(dest) &&_BOS_ZERO(dest

EXTERN errno_t empty dmax	BOS_ATTR (!_BOS_NULL(dest) &&_BOSW_OVR(dest, dmax), "dest overflow") BOS_ATTR(!_BOS_NULL(dest) &&(void ) dest == srcp

EXTERN errno_t empty dmax dest overlap	BOS_CHK2 (src, len)

EXTERN errno_t	_mbsrtowcs_s_chk (size_t restrict retvalp, wchar_t restrict dest, rsize_t dmax, const char *restrict srcp, rsize_t len, mbstate_t restrict ps, const size_t destbos) BOS_NULL(retvalp) BOS_NULL(srcp) BOS_NULL(ps) BOS_ATTR(!_BOS_NULL(dest) &&_BOS_ZERO(dest

EXTERN errno_t empty dmax dest overlap BOS_CHK2 srcp	BOS_ATTR (dmax &&len > dmax, "len overflow >dmax")

EXTERN errno_t	_wcsrtombs_s_chk (size_t restrict retvalp, char restrict dest, rsize_t dmax, const wchar_t *restrict srcp, rsize_t len, mbstate_t restrict ps, const size_t destbos) BOS_NULL(retvalp) BOS_NULL(ps) BOS_ATTR(!_BOS_NULL(dest) &&!dmax

EXTERN errno_t empty dmax	BOS_ATTR (!_BOS_NULL(dest) &&_BOS_OVR(dest, dmax), "dest overflow") BOS_ATTR(!_BOS_NULL(dest) &&(void *) dest

EXTERN errno_t empty dmax dest overlap	BOS_NULL (srcp) BOSW_CHK2(*srcp

EXTERN errno_t	_wcstombs_s_chk (size_t restrict retvalp, char restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t len, const size_t destbos) BOS_NULL(retvalp) BOS_CHK(dest) BOSW_CHK2(src

EXTERN errno_t	_wcrtomb_s_chk (size_t restrict retvalp, char restrict dest, rsize_t dmax, wchar_t wc, mbstate_t *restrict ps, const size_t destbos) BOS_NULL(retvalp) BOS_CHK(dest) BOS_NULL(ps) VAL_OVR2(wc

EXTERN errno_t	_wctomb_s_chk (int restrict retvalp, char restrict dest, rsize_t dmax, wchar_t wc, const size_t destbos) BOS_ATTR(!_BOS_NULL(dest) &&(!dmax\|\|dmax > RSIZE_MAX_STR\|\|_BOS_OVR(dest

EXTERN errno_t dest overflow or empty	VAL_OVR2 (wc, 0x10ffff)

EXTERN size_t	_wcsnlen_s_chk (const wchar_t *str, size_t smax, size_t srcbos) BOSW_CHK2(str

EXTERN errno_t	_wcscpy_s_chk (wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, const size_t destbos) BOSW_CHK(dest) BOS_NULL(src)

EXTERN errno_t	_wcsncpy_s_chk (wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t slen, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_OVR2(src

EXTERN errno_t	_wcscat_s_chk (wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, const size_t destbos) BOSW_CHK(dest) BOS_NULL(src)

EXTERN errno_t	_wcsncat_s_chk (wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t slen, const size_t destbos, const size_t srcbos) BOS_ATTR(slen &&(_BOS_NULL(dest)\|\|_BOS_ZERO(dest

EXTERN errno_t dmax empty dest or dmax	BOS_ATTR (slen &&(_BOSW_OVR(src, slen)\|\|_BOS_NULL(src)), "src overflow or empty")

EXTERN wchar_t *	_wcstok_s_chk (wchar_t restrict dest, rsize_t restrict dmaxp, const wchar_t restrict delim, wchar_t *restrict ptr, const size_t destbos) BOSW_OVR2_BUTNULL(dest

EXTERN wchar_t *dmaxp	BOS_NULL (delim) BOS_NULL(ptr)

EXTERN int	_swprintf_s_chk (wchar_t restrict dest, rsize_t dmax, const size_t destbos, const wchar_t restrict fmt,...) __attribute_format_wprintf(4

EXTERN int	BOSW_CHK (dest) BOS_FMT(fmt)

EXTERN int	_vswprintf_s_chk (wchar_t restrict dest, rsize_t dmax, const size_t destbos, const wchar_t restrict fmt, va_list ap) BOSW_CHK(dest) BOS_FMT(fmt)

EXTERN int	snwprintf_s (wchar_t restrict dest, rsize_t dmax, const wchar_t restrict fmt,...) __attribute_format_wprintf(3

EXTERN int	_vsnwprintf_s_chk (wchar_t restrict dest, rsize_t dmax, const size_t destbos, const wchar_t restrict fmt, va_list ap) BOSW_CHK(dest) BOS_FMT(fmt)

EXTERN int	wprintf_s (const wchar_t *restrict fmt,...) __attribute_format_wprintf(1

EXTERN int	vwprintf_s (const wchar_t *restrict fmt, va_list ap) BOS_FMT(fmt)
	The vwprintf_s function prints formatted output to stdout as wide string.

EXTERN int	fwprintf_s (FILE restrict stream, const wchar_t restrict fmt,...) __attribute_format_wprintf(2

EXTERN int	vfwprintf_s (FILE restrict stream, const wchar_t restrict fmt, va_list ap) BOS_NULL(stream) BOS_FMT(fmt)
	The vfwprintf_s function prints formatted output to a wide stream.

EXTERN int	swscanf_s (const wchar_t restrict src, const wchar_t restrict fmt,...) __attribute_format_wscanf(2

EXTERN int	BOS_NULL (src) BOS_FMT(fmt)

EXTERN int	vswscanf_s (const wchar_t restrict src, const wchar_t restrict fmt, va_list ap) BOS_NULL(src) BOS_FMT(fmt)
	The vswscanf_s function reads a formatted wide string.

EXTERN int	wscanf_s (const wchar_t *restrict fmt,...) __attribute_format_wscanf(1

EXTERN int	vwscanf_s (const wchar_t *restrict fmt, va_list ap) BOS_FMT(fmt)
	The `vwscanf_s` function reads a formatted wide string from stdin.

EXTERN int	fwscanf_s (FILE restrict stream, const wchar_t restrict fmt,...) __attribute_format_wscanf(2

EXTERN int	vfwscanf_s (FILE restrict stream, const wchar_t restrict fmt, va_list ap) BOS_NULL(stream) BOS_FMT(fmt)
	The `vfwscanf_s` function reads a formatted wide string.

EXTERN errno_t	_wcsstr_s_chk (wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t slen, wchar_t **restrict substringp, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_OVR2(src

EXTERN errno_t	_wcscmp_s_chk (const wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t smax, int *resultp, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_CHK2(src

EXTERN errno_t	_wcsncmp_s_chk (const wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t smax, rsize_t count, int *resultp, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_CHK2(src

EXTERN errno_t	_wcsicmp_s_chk (const wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t smax, int *resultp, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_CHK2(src

EXTERN errno_t	_wcsnatcmp_s_chk (const wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t smax, const int fold_case, int *resultp, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_CHK2(src

EXTERN errno_t	_wcsset_s_chk (wchar_t *restrict dest, rsize_t dmax, const wchar_t value, const size_t destbos) BOSW_CHK(dest) VAL_OVR2(value

EXTERN errno_t	_wcsnset_s_chk (wchar_t *restrict dest, rsize_t dmax, const wchar_t value, size_t n, const size_t destbos) BOSW_CHK(dest) VAL_OVR2(value

EXTERN errno_t	_wcscoll_s_chk (const wchar_t restrict dest, rsize_t dmax, const wchar_t restrict src, rsize_t smax, int *resultp, const size_t destbos, const size_t srcbos) BOSW_CHK(dest) BOSW_CHK2(src

EXTERN errno_t	_wcslwr_s_chk (wchar_t *restrict src, rsize_t slen, const size_t srcbos) BOSW_OVR2_BUTZERO(src

EXTERN errno_t	_wcsupr_s_chk (wchar_t *restrict src, rsize_t slen, const size_t srcbos) BOSW_OVR2_BUTZERO(src

EXTERN int	iswfc (const uint32_t wc) VAL_OVR2(wc

EXTERN int EXTERN int	_towfc_s_chk (wchar_t *restrict dest, rsize_t dmax, const uint32_t src, const size_t destbos) BOSW_CHK(dest) BOS_ATTR(dmax< 4

Variables
EXTERN errno_t	dmax

EXTERN errno_t empty dest or dmax	slen

EXTERN rsize_t	smax

EXTERN errno_t empty *	dest

EXTERN errno_t dmax	!dmax

Macro Definition Documentation

◆ EXTERN

#define EXTERN extern

◆ SAFECLIB_UNICODE_VERSION

#define SAFECLIB_UNICODE_VERSION 15

With this UCD version we generated our tables.

◆ RSIZE_MIN_STR

#define RSIZE_MIN_STR (1)

The shortest string is a null string!!

◆ RSIZE_MAX_WSTR

#define RSIZE_MAX_WSTR (RSIZE_MAX_STR / sizeof(wchar_t))

wide chars

◆ SAFE_STR_MIN_LOWERCASE

#define SAFE_STR_MIN_LOWERCASE (2)

The makeup of a password.

◆ SAFE_STR_MIN_UPPERCASE

#define SAFE_STR_MIN_UPPERCASE (2)

◆ SAFE_STR_MIN_NUMBERS

#define SAFE_STR_MIN_NUMBERS (1)

◆ SAFE_STR_MIN_SPECIALS

#define SAFE_STR_MIN_SPECIALS (1)

◆ SAFE_STR_PASSWORD_MIN_LENGTH

#define SAFE_STR_PASSWORD_MIN_LENGTH (6)

◆ SAFE_STR_PASSWORD_MAX_LENGTH

#define SAFE_STR_PASSWORD_MAX_LENGTH (32)

◆ sl_default_handler

#define sl_default_handler ignore_handler_s

◆ strcat_s

#define strcat_s	(	dest,
		dmax,
		src
	)	_strcat_s_chk(dest, dmax, src, BOS(dest))

The strcat_s function appends a copy of the string pointed to by src (including the terminating NUL character) to the end of the string pointed to by dest.

The initial character from src overwrites the NUL character at the end of dest.

All elements following the terminating NUL character (if any) written by strcat_s in the array of dmax characters pointed to by dest take unspeciﬁed values when strcat_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest of dest is cleared with NULL bytes. With modern compilers and constant arguments most errors will be caught at compile-time.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.7.2.1 The strcat_s function (p: 617-618) http://en.cppreference.com/w/c/string/byte/strcat
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string that will be extended by src if dmax allows. The string is zero terminated. If the resulting concatenated string is less than dmax, the remaining slack space is nulled.
[in]	dmax	restricted maximum length of the resulting dest, including the null
[in]	src	pointer to the string that will be concatenaed to string dest

Precondition: Neither dest nor src shall be a null pointer; dmax shall be size of dest; dmax shall not equal zero; dmax shall not be greater than RSIZE_MAX_STR and size of dest; dmax shall be greater than strnlen_s(src,m).; Copying shall not take place between objects that overlap

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.; The Windows MSVCRT sec_api EINVAL and ERANGE works ok, ESLEMAX dmax/slen>MAX not, ESOVRLP returns EINVAL or ERANGE, unlike strncat_s.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then strcat_s nulls dest.

Return values

EOK	when successful operation, all the characters from src were appended to dest and the result in dest is null terminated.
ESNULLP	when dest or src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESUNTERM	when dest not terminated in the first dmax bytes
ESOVRLP	when src overlaps with dest

See also: strncat_s(), strcpy_s(), strncpy_s()

◆ strcpy_s

#define strcpy_s	(	dest,
		dmax,
		src
	)	_strcpy_s_chk(dest, dmax, src, BOS(dest))

The strcpy_s function copies the string pointed to by src (including the terminating NUL character) into the array pointed to by dest.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written by strcpy_s in the array of dmax characters pointed to by dest are nulled when strcpy_s returns. With modern compilers and constant arguments most errors will be caught at compile-time.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.7.1.3 The strcpy_s function (p: 615-616) http://en.cppreference.com/w/c/string/byte/strcpy
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the string that will be copied to dest

Precondition: Neither dest nor src shall be a null pointer.; dmax shall be size of dest; dmax shall not be greater than RSIZE_MAX_STR or size of dest.; dmax shall not equal zero.; dmax shall be greater than strnlen_s(src, dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.; The Windows MSVCRT sec_api EINVAL and ERANGE works ok, ESLEMAX dmax > MAX not, ESOVRLP partially. When dest > src Windows copies the result, when dest < src ERANGE is returned.

Returns: If there is a runtime-constraint violation, and if dest and dmax are valid, then strcpy_s nulls dest.

Return values

EOK	when successful operation, the characters in src were copied into dest and the result is zero terminated.
ESNULLP	when dest or src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when strings overlap
ESNOSPC	when dest < src

See also: strcat_s(), strncat_s(), strncpy_s()

◆ strncat_s

#define strncat_s	(	dest,
		dmax,
		src,
		slen
	)	_strncat_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))

The strncat_s function appends a copy of the string pointed to by src (including the terminating NUL character) to the end of the string pointed to by dest.

The initial character from src overwrites the NUL character at the end of dest.

All elements following the terminating NUL character (if any) written by strncat_s in the array of dmax characters pointed to by dest take unspeciﬁed values when strncat_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with NULL bytes. With modern compilers and constant arguments most errors will be caught at compile-time.

Remarks

SPECIFIED IN

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

Parameters

[out]	dest	pointer to string that will be extended by src if dmax allows. The string is zero terminated. If the resulting concatenated string is less than dmax, the remaining slack space is nulled.
[in]	dmax	restricted maximum length of the resulting dest, including the null
[in]	src	pointer to the string that will be concatenaed to string dest
[in]	slen	maximum characters to append

Precondition: Neither dest nor src shall be a null pointer.; With –enable-warn-dmax dmax should be the exact object size of dest.; dmax and slen should not be greater than RSIZE_MAX_STR.; dmax and slen should not be greater than the object sizes of dest and src.; dmax shall not equal zero.; dmax shall be greater than strnlen_s(src,dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.; The Windows MSVCRT sec_api EINVAL and ERANGE works ok, ESLEMAX dmax/slen > MAX not, ESOVRLP partially. When dest > src Windows appends the result, when dest < src ERANGE or EINVAL is returned.

Returns: If there is a runtime-constraint violation, and if dest and dmax are valid, then strncat_s clears dest.

Return values

EOK	successful operation, when slen == 0 or all the characters are copied from src and dest is zero terminated. As special case, analog to msvcrt: when slen == 0 and dmax is big enough for dest, also return EOK, but clear the rest of dest.
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESUNTERM	when dest not terminated
ESOVRLP	when src overlaps with dest

If dmax != sizeof(dest): With –enable-warn-dmax ESLEWRNG will be passed to the constraint handler. With –enable-error-dmax this error will be fatal, but dest will not be cleared. With clang-5 and/or diagnose_if and __builtin_object_size() support wrong dmax values will be caught at compile-time.

See also: strcat_s(), strncpy_s(), wcsncat_s() http://www.informit.com/articles/article.aspx?p=2036582&seqNum=5

◆ strncpy_s

#define strncpy_s	(	dest,
		dmax,
		src,
		slen
	)	_strncpy_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))

The strncpy_s function copies not more than slen successive characters (characters that follow a NUL character are not copied) from the array pointed to by src to the array pointed to by dest.

If no NUL character was copied from src, then dest[n] is set to a NUL character, thus guaranteeing zero termination.

All elements following the terminating NUL character (if any) written by strncpy_s in the array of dmax characters pointed to by dest take unspeciﬁed values when strncpy_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with NUL bytes. With modern compilers and constant arguments most errors will be caught at compile-time.

Remarks

SPECIFIED IN

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

Parameters

[out]	dest	pointer to string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the string that will be copied to dest
[in]	slen	the maximum number of characters to copy from src

Precondition: dmax shall not be zero.; With –enable-warn-dmax dmax should be the exact object size of dest.; dmax and slen should not be greater than RSIZE_MAX_STR.; dmax and slen should not be greater than the object sizes of dest and src.; dmax shall not equal zero; If slen is either greater than or equal to dmax, then dmax should be more than strnlen_s(src,dmax) to avoid truncation.; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, and if dest and dmax are valid, then strncpy_s zeros dest.

Return values

EOK	successful operation, when slen == 0 or the characters in src were copied to dest and the result is zero terminated.
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when strings overlap
ESNOSPC	when src longer than dest

If dmax != sizeof(dest): With –enable-warn-dmax ESLEWRNG will be passed to the constraint handler. With –enable-error-dmax this error will be fatal, but dest will not be cleared.

See also: strcat_s(), strncat_s(), strcpy_s(), wcsncpy_s() http://www.informit.com/articles/article.aspx?p=2036582&seqNum=5

◆ strnlen_s

#define strnlen_s	(	str,
		smax
	)	_strnlen_s_chk(str, smax, BOS(str))

The strnlen_s function computes the length of the string pointed to by str, refusing to read past smax.

Remarks: SPECIFIED IN ISO/IEC TR 24731-1, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

str	pointer to string
smax	maximum length of string

Precondition: str shall not be a null pointer.; smax shall not equal zero.; smax shall not be greater than RSIZE_MAX_STR nor sizeof(str).

Returns: The function returns the string length, excluding the terminating NUL character. If str is NULL, then strnlen_s returns 0. Otherwise, the strnlen_s function returns the number of characters that precede the terminating NUL character. If there is no NUL character in the first smax characters of str then strnlen_s returns smax. At most the first smax or sizeof(str) characters of str are accessed by strnlen_s.

See also: strnterminate_s() http://www.informit.com/articles/article.aspx?p=2036582&seqNum=5

◆ strtok_s

#define strtok_s	(	dest,
		dmaxp,
		delim,
		ptr
	)	_strtok_s_chk(dest, dmaxp, delim, ptr, BOS(dest))

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 NUL 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 NUL 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/strtok
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]	dmaxp	pointer to 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 and size of dest. 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 EOVERFLOW when *dmax > size of dest ESLEWRNG when *dmax != size of dest and –enable-error-dmax 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 );

}

◆ vsprintf_s

#define vsprintf_s	(	dest,
		dmax,
		fmt,
		ap
	)	_vsprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

The vsprintf_s function composes a string with the same content that would be printed if format was used on printf.

Instead of being printed, the content is stored in dest. If dmax is zero, nothing is written and dest may be a null pointer, however the return value (number of bytes that would be written) is still calculated and returned.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.13 The vsprintf_s function (p: 601) http://en.cppreference.com/w/c/io/vfprintf

Parameters

[out]	dest	pointer to string that will be written into.
[in]	dmax	restricted maximum length of dest
[in]	fmt	format-control string.
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR or the size of dest.; dmax shall not equal zero if dest is not null.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer (not yet); No encoding error shall occur.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: On success the total number of characters without the terminating \0 is returned.; On failure a negative number is returned (deviating from C11).; If dest is valid and too small for the formatted text, including the terminating null, then the buffer is cleared, and the invalid parameter handler is invoked.

Return values

-ESNULLP	when `fmt` is NULL pointer, or when `dest` is NULL and dmax > 0, or when a `s` argument is NULL
-ESZEROL	when `dmax` = 0 and dest is not NULL
-ESLEMAX	when `dmax` > `RSIZE_MAX_STR`
-EOVERFLOW	when `dmax` > size of dest
-ESNOSPC	when return value exceeds dmax unless dmax is zero and dest is NULL
-EINVAL	when `fmt` contains `n`

Note: The C11 standard was most likely wrong with changing the return value 0 on errors. All other functions and existing C11 implementations do return -1, so we return negative error codes. See the http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1141.pdf revision for their rationale. vsprintf_s does not set errno.

See also: sprintf_s(), vsnprintf_s()

◆ vsnprintf_s

#define vsnprintf_s	(	dest,
		dmax,
		fmt,
		ap
	)	_vsnprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

The truncating vsnprintf_s function composes a string with same test that would be printed if format was used on printf.

Instead of being printed, the content is stored in dest. At most dmax characters are written. It is guaranteed that dest will be null-terminated.

Note: POSIX specifies that errno is set on error. However, the safeclib extended ES* errors do not set errno, only when the underlying system vsnprintf call fails, errno is set.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.12 The vsnprintf_s function (p: 600) http://en.cppreference.com/w/c/io/vfprintf

Parameters

[out]	dest	pointer to string that will be written into.
[in]	dmax	restricted maximum length of `dest`
[in]	fmt	format-control string.
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; dest shall not be a null pointer.; dmax shall not be zero.; dmax shall not be greater than RSIZE_MAX_STR and the size of dest.; fmt shall not contain the conversion specifier n.; None of the arguments corresponding to s is a null pointer.; No encoding error shall occur.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: On success the total number of characters written is returned.; On failure a negative error number is returned.; If the buffer dest is too small for the formatted text, including the terminating null, then the buffer is truncated and zero terminated.

Return values

-ESNULLP	when `dest` or fmt is NULL pointer, or when a `s` argument is NULL
-ESZEROL	when `dmax` == 0
-ESLEMAX	when `dmax` > `RSIZE_MAX_STR`
-EOVERFLOW	when `dmax` > size of dest
-EINVAL	when fmt contains n

See also: snprintf_s(), sprintf_s(), vsprintf_s(), vsnwprintf_s()

◆ strerror_s

#define strerror_s	(	dest,
		dmax,
		errnum
	)	_strerror_s_chk(dest, dmax, errnum, BOS(dest))

The strerror_s function returns a pointer to the textual description of the system error code errnum, identical to the description that would be printed by perror().

In addition to strerror() it adds the size of the destination array in order to prevent buffer overflow, and it truncates overlong error messages with "...".

No more than dmax-1 bytes are written, the buffer is always null-terminated. If the message had to be truncated to fit the buffer and dmax is greater than 3, then only dmax-4 bytes are written, and the characters "..." are appended before the NUL terminator. The behavior is undefined if writing to dest occurs past the end of the array, which can happen when the size of the buffer pointed to by dest is less than the number of characters in the error message which in turn is less than dmax.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.7.4.2 The strerror_s function (p: 622) http://en.cppreference.com/w/c/byte/strerror
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to a user-provided string buffer
[in]	dmax	restricted maximum length of dest
[in]	errnum	integer value referring to an error code

Precondition: dest shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR and size of dest; dmax shall not equal zero.

Returns: Zero if the entire message was successfully stored in dest, non-zero otherwise.

Return values

EOK	on success
ESNULLP	when dest is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESLEMIN	when the result would be longer than 4 and dmax < 4

See also: strerrorlen_s()

◆ stpcpy_s

#define stpcpy_s	(	dest,
		dmax,
		src,
		errp
	)	_stpcpy_s_chk(dest, dmax, src, errp, BOS(dest), BOS(src))

The stpcpy_s function copies the string pointed to by src (including the terminating NUL character) into the array pointed to by dest.

The strings may not overlap. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written by stpcpy_s in the array of dmax characters pointed to by dest are nulled when stpcpy_s returns. With modern compilers and constant arguments most errors will be caught at compile-time.

Remarks

SPECIFIED IN

Since glibc 2.10: _POSIX_C_SOURCE >= 200809L
Before glibc 2.10: _GNU_SOURCE

Parameters

[out]	dest	pointer to string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the string that will be copied to dest
[out]	errp	EOK success. the characters in src were copied into dest and the result is zero terminated. ESNULLP when dest or src is a NULL pointer ESZEROL when dmax = 0 ESLEMAX when dmax > RSIZE_MAX_STR EOVERFLOW when dmax > size of dest (optionally, when the compiler knows the object_size statically) ESLEWRNG when dmax != size of dest and –enable-error-dmax ESUNTERM when src is unterminated ESOVRLP when strings overlap ESNOSPC when dest < src

Precondition: Neither dest, src nor errp nor shall be a null pointer.; dmax shall be size of dest; dmax shall not be greater than RSIZE_MAX_STR or size of dest.; dmax shall not equal zero.; dmax shall be greater than strnlen_s(src, dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: stpcpy_s() returns a pointer to the end of the string dest (that is, the address of the terminating null byte) rather than the beginning.; If there is a runtime-constraint violation, and if dest and dmax are valid, then stpcpy_s nulls dest.

See also: stpncpy_s(), strcpy_s(), strncpy_s()

◆ stpncpy_s

#define stpncpy_s	(	dest,
		dmax,
		src,
		slen,
		errp
	)	_stpncpy_s_chk(dest, dmax, src, slen, errp, BOS(dest), BOS(src))

The strncpy_s function copies max slen bytes of the string pointed to by src (excluding the terminating NUL character) into the array pointed to by dest.

The strings may not overlap.

All elements following the terminating NUL character (if any) written by stpncpy_s in the array of dmax characters pointed to by dest take unspeciﬁed values when stpncpy_s returns. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written by stpncpy_s in the array of dmax characters pointed to by dest are nulled when stpncpy_s returns. With modern compilers and constant arguments most errors will be caught at compile-time.

Remarks

SPECIFIED IN

Since glibc 2.10: _POSIX_C_SOURCE >= 200809L
Before glibc 2.10: _GNU_SOURCE

Parameters

[out]	dest	pointer to string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the string that will be copied to dest
[in]	slen	the maximum number of bytes to copy from src
[out]	errp	EOK success. the characters in src were copied into dest and the result is zero terminated. ESNULLP when dest or src is a NULL pointer ESZEROL when dmax = 0 ESLEMAX when dmax or slen > RSIZE_MAX_STR EOVERFLOW when dmax/slen > size of dest/slen (optionally, when the compiler knows the object_size statically) ESLEWRNG when dmax != size of dest and –enable-error-dmax ESUNTERM when src is unterminated ESOVRLP when strings overlap ESNOSPC when src longer than dest

Precondition: Neither dest, src nor err nor shall be a null pointer.; dmax shall be size of dest; dmax shall not be greater than RSIZE_MAX_STR or size of dest.; dmax shall not equal zero.; dmax shall be greater than strnlen_s(src, dmax).; If slen is either greater than or equal to dmax, then dmax should be more than strnlen_s(src,dmax) to avoid truncation.; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: stpncpy() returns a pointer to the terminating null byte in dest, or, if dest is not null-terminated, dest+n.; If there is a runtime-constraint violation, and if dest and dmax are valid, then stpncpy_s nulls dest.

See also: stpcpy_s(), strcpy_s(), strncpy_s()

◆ strcmp_s

#define strcmp_s	(	dest,
		dmax,
		src,
		resultp
	)	_strcmp_s_chk(dest, dmax, src, resultp, BOS(dest), BOS(src))

Compares string src to string dest.

Remarks: EXTENSION TO ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: resultp (when the return code is OK)

Return values

>0	when dest greater than src
0	when strings the same
<0	when dest less than src
EOK	when comparison is complete
ESUNTERM	when src is unterminated
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strcasecmp_s()

◆ strcasecmp_s

#define strcasecmp_s	(	dest,
		dmax,
		src,
		resultp
	)	_strcasecmp_s_chk(dest, dmax, src, resultp, BOS(dest))

Case insensitive string comparison by converting to uppercase prior to the compare.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR or size of dest

Returns: resultp (when the return code is OK)

Return values

>0	when dest greater than src
0	when strings the same
<0	when dest less than src
EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strcmp_s()

◆ strnatcmp_s

#define strnatcmp_s	(	dest,
		dmax,
		src,
		resultp
	)	_strnatcmp_s_chk(dest, dmax, src, 0, resultp, BOS(dest), BOS(src))

Natural order comparison of strings.

The longest run of numbers wins over alpha chars.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR or size of dest

Returns: *resultp, when the return code is OK: >0 when dest greater than src 0 when strings are the same <0 when dest less than src

Return values

EOK	when comparison is complete
ESUNTERM	when dest or src is unterminated, or dmax is too small.
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strcmp_s()

◆ strnatcasecmp_s

#define strnatcasecmp_s	(	dest,
		dmax,
		src,
		resultp
	)	_strnatcasecmp_s_chk(dest, dmax, src, 1, resultp, BOS(dest), BOS(src))

◆ strcasestr_s

#define strcasestr_s	(	dest,
		dmax,
		src,
		slen,
		substring
	)	_strcasestr_s_chk(dest, dmax, src, slen, substring, BOS(dest), BOS(src))

The strcasestr_s() function locates the first occurrence of the substring pointed to by src which would be located in the string pointed to by dest.

The comparison is case insensitive.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to be searched for the substring
[in]	dmax	restricted maximum length of dest string
[in]	src	pointer to the substring
[in]	slen	maximum length of src string
[out]	substring	returned pointer to the substring

Precondition: Neither dest nor src shall be a null pointer.; Neither dmax nor slen shall equal zero.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src

Return values

EOK	when successful operation, substring found.
ESNULLP	when dst/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOTFND	when substring not found

See also: strstr_s(), strprefix_s()

◆ strcmpfld_s

#define strcmpfld_s	(	dest,
		dmax,
		src,
		resultp
	)	_strcmpfld_s_chk(dest, dmax, src, resultp, BOS(dest))

Compares the character array pointed to by src to the character array pointed to by dest for dmax characters.

The null terminator does not stop the comparison.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to int result. greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: resultp (when the return code is OK)

Return values

>0	when dest greater than src
0	when the strings are the same
<0	when dest less than src
EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strcpyfld_s(), strcpyfldin_s(), strcpyfldout_s()

◆ strcpyfld_s

#define strcpyfld_s	(	dest,
		dmax,
		src,
		slen
	)	_strcpyfld_s_chk(dest, dmax, src, slen, BOS(dest))

◆ strcpyfldin_s

#define strcpyfldin_s	(	dest,
		dmax,
		src,
		slen
	)	_strcpyfldin_s_chk(dest, dmax, src, slen, BOS(dest))

◆ strcpyfldout_s

#define strcpyfldout_s	(	dest,
		dmax,
		src,
		slen
	)	_strcpyfldout_s_chk(dest, dmax, src, slen, BOS(dest))

◆ strcspn_s

#define strcspn_s	(	dest,
		dmax,
		src,
		slen,
		countp
	)	_strcspn_s_chk(dest, dmax, src, slen, countp, BOS(dest), BOS(src))

This function computes the prefix length of the string pointed to by dest which consists entirely of characters that are excluded from the string pointed to by src.

The scanning stops at the first null in dest or after dmax characters. The exclusion string is checked to the null or after slen characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to determine the prefix
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to exclusion string
[in]	slen	restricted maximum length of string src
[out]	countp	pointer to a count variable that will be updated with the dest substring length

Precondition: Neither dest nor src shall be a null pointer.; count shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Return values

EOK	when operation is successful
ESNULLP	when dest/src/count is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strspn_s(), strpbrk_s(), strstr_s()

◆ strfirstchar_s

#define strfirstchar_s	(	dest,
		dmax,
		c,
		firstp
	)	_strfirstchar_s_chk(dest, dmax, c, firstp, BOS(dest))

This function returns a pointer to the first occurrence of character c in dest.

The scanning stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string
[in]	c	character to locate
[out]	firstp	returned pointer to first occurrence of c

Precondition: dest and firstp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: pointer to first occurence of c in dest, NULL if not found

Return values

EOK	when pointer to first occurrence is returned
ESNULLP	when dest/firstp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strlastchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastdiff_s(), strlastsame_s(),

◆ strfirstdiff_s

#define strfirstdiff_s	(	dest,
		dmax,
		src,
		resultp
	)	_strfirstdiff_s_chk(dest, dmax, src, resultp, BOS(dest))

Returns the index of the first character that is different between dest and src.

Index is valid only for OK. The scanning stops at the first null in dest or src, or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to returned index to first difference

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: resultp as index to first difference, when the return code is OK

Return values

EOK	when index to first diff is returned in resultp
ESNODIFF	when no difference
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strfirstchar_s(), strfirstsame_s(), strlastchar_s(), strlastdiff_s(), strlastsame_s()

◆ strisalphanumeric_s

#define strisalphanumeric_s	(	dest,
		dmax
	)	_strisalphanumeric_s_chk(dest, dmax, BOS(dest))

This function checks if the entire string contains alphanumerics.

The scanning stops at the first null or after smax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when all chars in dest are alphanumeric; false when dest is not alphanumeric or an error occurred

See also: strisascii_s(), strisdigit_s(), strishex_s(), strislowercase_s(), strismixedcase_s(), strisuppercase_s()

◆ strisascii_s

#define strisascii_s	(	dest,
		dmax
	)	_strisascii_s_chk(dest, dmax, BOS(dest))

This function checks if the entire string contains ascii characters.

The scanning stops at the first null or at most dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dest shall be a zero terminated.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when string is ascii; false when string contains one or more non-ascii or an error occurred

See also: strisalphanumeric_s(), strisdigit_s(), strishex_s(), strislowercase_s(), strismixedcase_s(), strisuppercase_s()

◆ strisdigit_s

#define strisdigit_s	(	dest,
		dmax
	)	_strisdigit_s_chk(dest, dmax, BOS(dest))

This function checks that the entire string contains digits.

The scanning stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dest shall be a zero terminated.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when string is digit; false when string is not digit or an error occurred

See also: strisalphanumeric_s(), strisascii_s(), strishex_s(), strislowercase_s(), strismixedcase_s(), strisuppercase_s()

◆ strishex_s

#define strishex_s	(	dest,
		dmax
	)	_strishex_s_chk(dest, dmax, BOS(dest))

This function checks that the entire string contains hex characters.

The scanning stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dest shall be a zero terminated.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when string is hex; false when string is not hex or an error occurred

See also: strisalphanumeric_s(), strisascii_s(), strisdigit_s(), strislowercase_s(), strismixedcase_s(), strisuppercase_s()

◆ strislowercase_s

#define strislowercase_s	(	dest,
		dmax
	)	_strislowercase_s_chk(dest, dmax, BOS(dest))

This function checks if entire string is lowercase.

The scanning stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dest shall be a zero terminated.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when string is lowercase; false when string is not lowercase or an error occurred

See also: strisalphanumeric_s(), strisascii_s(), strisdigit_s(), strishex_s(), strismixedcase_s(), strisuppercase_s()

◆ strismixedcase_s

#define strismixedcase_s	(	dest,
		dmax
	)	_strismixedcase_s_chk(dest, dmax, BOS(dest))

This function checks that the entire string is mixed case.

The scanning stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when string is mixed case; false when string is not mixed case or error

See also: strisalphanumeric_s(), strisascii_s(), strisdigit_s(), strishex_s(), strislowercase_s(), strisuppercase_s()

◆ strispassword_s

#define strispassword_s	(	dest,
		dmax
	)	_strispassword_s_chk(dest, dmax, BOS(dest))

This function validates the make-up of a password string.

Password must have mininmum SAFE_STR_PASSWORD_MIN_LENGTH characters
Password can have maximum SAFE_STR_PASSWORD_MAX_LENGTH characters
Password must have at least SAFE_STR_MIN_LOWERCASE lower case characters
Password must have at least SAFE_STR_MIN_UPPERCASE upper case characters
Password must have at least SAFE_STR_MIN_NUMBERS numbers
Password must have at least SAFE_STR_MIN_SPECIALS special characters

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to password string
dmax	maximum length of password string

Precondition: dest shall not be a null pointer.; dmax > SAFE_STR_PASSWORD_MIN_LENGTH; dmax < SAFE_STR_PASSWORD_MAX_LENGTH; dest shall not be unterminated

Returns: true when string iss valid password; false when string does not meet requirements or an error occurred

See also: strzero_s()

◆ strisuppercase_s

#define strisuppercase_s	(	dest,
		dmax
	)	_strisuppercase_s_chk(dest, dmax, BOS(dest))

This function checks if entire string is uppercase The scanning stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: true when string is uppercase; false when string is not uppercase or an error occurred

See also: strisalphanumeric_s(), strisascii_s(), strisdigit_s(), strishex_s(), strislowercase_s(), strismixedcase_s(),

◆ strlastchar_s

#define strlastchar_s	(	dest,
		dmax,
		c,
		lastp
	)	_strlastchar_s_chk(dest, dmax, c, lastp, BOS(dest))

Returns a pointer to the last occurrence of character c in dest.

The scanning stops at null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string
[in]	c	character to locate
[out]	lastp	returned pointer to last occurrence of c

Precondition: dest and lastp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: pointer to last occurence of c, NULL if not found

Return values

EOK	when pointer to last occurrence is returned
ESNULLP	when dst/first is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strfirstchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastdiff_s(), strlastsame_s()

◆ strlastdiff_s

#define strlastdiff_s	(	dest,
		dmax,
		src,
		resultp
	)	_strlastdiff_s_chk(dest, dmax, src, resultp, BOS(dest))

Returns the index of the last character that is different between dest and src.

Index is valid only for EOK. The scanning stops at the first null in dest or src, or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to returned index to last difference

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: resultp as index to last difference, when the return code is OK

Return values

EOK	when index to last diff is returned in resultp
ESNODIFF	when no difference
ESNULLP	when dest/src/idx is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strfirstchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastchar_s(), strlastsame_s()

◆ strljustify_s

#define strljustify_s	(	dest,
		dmax
	)	_strljustify_s_chk(dest, dmax, BOS(dest))

Removes beginning whitespace from the string pointed to by dest by shifting the text left over writting the beginning whitespace, left justifying the text.

The left justified text is zero terminated. The text is shifted so the original pointer can continue to be used.

Remarks: EXTENSION TO ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string to left justify
[in]	dmax	restricted maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest; dest shall be zero terminated

Return values

EOK	when successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESUNTERM	when dest was not zero terminated

See also: strremovews_s(),

◆ strnterminate_s

#define strnterminate_s	(	dest,
		dmax
	)	_strnterminate_s_chk(dest, dmax, BOS(dest))

The strnterminate_s function will terminate the string if a null is not encountered before dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731-1, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string
dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: The function returns a terminated string. If a null is not encountered prior to dmax characters, the dmax character is set to zero terminating the string. The string length is also returned.

See also: strnlen_s()

◆ strpbrk_s

#define strpbrk_s	(	dest,
		dmax,
		src,
		slen,
		firstp
	)	_strpbrk_s_chk(dest, dmax, src, slen, firstp, BOS(dest), BOS(src))

Returns a pointer, first, to the first ocurrence of any character in src which is contained in dest.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string to compare against
dmax	restricted maximum length of string dest
src	pointer to the string
slen	restricted length of string src
firstp	returned pointer to first occurence

Precondition: Neither dest, src nor firstp shall be a null pointer.; Neither dmax nor slen shall not be 0.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and the size of dest/src

Returns: pointer to the first ocurrence of any character contained in src

Return values

EOK	when successful operation
ESNULLP	when dest/src/firstp is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically). when slen > size of src
ESLEWRNG	with –enable-error-dmax, when dmax != sizeof(dest) or slen > size of src

See also: strfirstchar_s(), strlastchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastdiff_s(), strlastsame_s()

◆ strfirstsame_s

#define strfirstsame_s	(	dest,
		dmax,
		src,
		resultp
	)	_strfirstsame_s_chk(dest, dmax, src, resultp, BOS(dest))

Returns the index of the first character that is the same between dest and src.

The scanning stops at the first null in dest or src, or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to returned index

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: index to first same char, when the return code is OK

Return values

EOK	when index to first same char is returned
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOTFND	when not found

See also: strfirstchar_s(), strfirstdiff_s(), strlastchar_s(), strlastdiff_s(), strlastsame_s()

◆ strlastsame_s

#define strlastsame_s	(	dest,
		dmax,
		src,
		resultp
	)	_strlastsame_s_chk(dest, dmax, src, resultp, BOS(dest))

Returns the index of the last character that is the same between dest and src.

The scanning stops at the first nul in dest or src, or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to returned index

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: index to last same char, when the return code is OK

Return values

EOK	when index to last same char is returned
ESNULLP	when dst/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOTFND	when not found

See also: strfirstchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastchar_s(), strlastdiff_s()

◆ strprefix_s

#define strprefix_s	(	dest,
		dmax,
		src
	)	_strprefix_s_chk(dest, dmax, src, BOS(dest))

Determines if the prefix pointed to by src is at the beginning of string pointed to by dest.

The prefix must be a complete match in dest. Useful for command or user input parsing. The scanning stops at the first null in dest or src, or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731-1, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

dest	pointer to string to compare against
dmax	restricted maximum length of dest
src	pointer to the prefix

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOTFND	when prefix not found in dest

See also: strspn_s(), strcspn_s(), strpbrk_s(), strstr_s()

◆ strremovews_s

#define strremovews_s	(	dest,
		dmax
	)	_strremovews_s_chk(dest, dmax, BOS(dest))

Removes beginning and trailing whitespace from the string pointed to by dest by shifting the text left over writting the beginning whitespace (space or tab).

The shifted-trimmed text is zero terminated. The text is shifted so the original pointer can continue to be used. This is useful when the memory was malloc'ed and will need to be freed.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string to left justify
[in]	dmax	restricted maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest; dest shall be zero terminated

Return values

EOK	when successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESUNTERM	when dest was not zero terminated

See also: strljustify_s(),

◆ strspn_s

#define strspn_s	(	dest,
		dmax,
		src,
		slen,
		countp
	)	_strspn_s_chk(dest, dmax, src, slen, countp, BOS(dest), BOS(src))

This function computes the prefix length of the string pointed to by dest which consists entirely of characters that are included from the string pointed to by src.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to determine the prefix
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to exclusion string
[in]	slen	restricted maximum length of string src
[out]	countp	pointer to a count variable that will be updated with the dest substring length

Precondition: Neither dest, src nor countp shall be a null pointer.; Neither dmax nor slen shall be 0.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/countp is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strcspn_s(), strpbrk_s(), strstr_s(), strprefix_s()

◆ strstr_s

#define strstr_s	(	dest,
		dmax,
		src,
		slen,
		substringp
	)	_strstr_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))

The strstr_s() function locates the first occurrence of the substring pointed to by src which would be located in the string pointed to by dest.

Remarks

EXTENSION TO

ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to be searched for the substring
[in]	dmax	restricted maximum length of dest string
[in]	src	pointer to the sub string
[in]	slen	the maximum number of characters to use from src
[out]	substringp	the returned substring pointer

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be 0.; slen shall not be 0, when *src != 0 and src != dest; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0, unless *src = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOTFND	when substring not found

See also: strprefix_s(), strspn_s(), strcspn_s(), strpbrk_s()

◆ strchr_s

#define strchr_s	(	dest,
		dmax,
		ch,
		resultp
	)	_strchr_s_chk(dest, dmax, ch, resultp, BOS(dest))

Finds the first occurrence of ch (after conversion to char as if by (char)ch) in the null-terminated byte string pointed to by dest (each character interpreted as unsigned char).

The terminating NUL character is considered to be a part of the string and can be found when searching for '\0'.

Remarks: IMPLEMENTED IN

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of dest
[in]	ch	character to search for
[out]	resultp	pointer to char* in dest

Precondition: Neither dest nor resultp shall be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; ch shall not be greater than 255

Return values

EOK	when successfully character found.
ESNULLP	when dest/resultp is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR, or ch > 255
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOTFND	when ch not found in dest

See also: memchr_s(), strspn_s(), strcspn_s(), strpbrk_s(), strstr_s()

◆ strrchr_s

#define strrchr_s	(	dest,
		dmax,
		ch,
		resultp
	)	_strrchr_s_chk(dest, dmax, ch, resultp, BOS(dest))

Finds the last occurrence of ch (after conversion to char as if by (char)ch) in the null-terminated byte string pointed to by dest (each character interpreted as unsigned char).

The terminating NUL character is considered to be a part of the string and can be found when searching for '\0'. Unlike strrchr() it honors dmax as maximal string length.

Remarks: IMPLEMENTED IN

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of dest
[in]	ch	character to search for
[out]	resultp	pointer to char* in dest

Precondition: Neither dest nor resultp shall be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; ch shall not be greater than 255.

Return values

EOK	when successfully character found.
ESNULLP	when dest/resultp is a NULL pointer
ESZEROL	when dmax = 0 or strnlen_s = 0
ESLEMAX	when dmax > RSIZE_MAX_STR or ch > 255
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOTFND	when ch not found in dest

See also: memrchr_s(), strchr_s(), memchr_s(), strspn_s(), strstr_s()

◆ strtolowercase_s

#define strtolowercase_s	(	dest,
		dmax
	)	_strtolowercase_s_chk(dest, dmax, BOS(dest))

Converts all uppercase characters to lowercase, leaving all other characters unchanged.

The conversion stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string
[in]	dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Return values

EOK	when successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strtouppercase_s()

◆ strtouppercase_s

#define strtouppercase_s	(	dest,
		dmax
	)	_strtouppercase_s_chk(dest, dmax, BOS(dest))

Converts all lowercase characters to uppercase, leaving all other characters unchanged.

The conversion stops at the first null or after dmax characters.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string
[in]	dmax	maximum length of string

Precondition: dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR.

Return values

EOK	when successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

ALSO SEE strtolowercase_s()

◆ strlwr_s

#define strlwr_s	(	str,
		slen
	)	strtolowercase_s((str), (slen))

◆ strupr_s

#define strupr_s	(	str,
		slen
	)	strtouppercase_s((str), (slen))

◆ strzero_s

#define strzero_s	(	dest,
		dmax
	)	_strzero_s_chk(dest, dmax, BOS(dest))

Nulls maximal dmax characters of dest.

This function can be used to clear strings that contained sensitive data, until the terminating NULL character. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to string that will be nulled.
[in]	dmax	restricted maximum length of dest

Return values

EOK	when successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strispassword_s()

◆ strcoll_s

#define strcoll_s	(	dest,
		dmax,
		src,
		resultp
	)	_strcoll_s_chk(dest, dmax, src, resultp, BOS(dest))

Compares two null-terminated byte strings according to the current locale as defined by the LC_COLLATE category.

Collation order is the dictionary order: the position of the letter in the national alphabet (its equivalence class) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single collation units. For example, "ch" in Czech follows "h" and precedes "i", and "dzs" in Hungarian follows "dz" and precedes "g".

Remarks: EXTENSION TO ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to compare against
[in]	dmax	restricted maximum length of string dest
[in]	src	pointer to the string to be compared to dest
[out]	resultp	pointer to result indicator, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: indicator (when the return code is OK)

Return values

>0	when dest greater than src
0	when strings the same
<0	when dest less than src
EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: wcscoll_s(), strcmp_s(), strcasecmp_s()

◆ strset_s

#define strset_s	(	dest,
		dmax,
		value
	)	_strset_s_chk(dest, dmax, value, BOS(dest))

Sets maximal dmax characters of dest to a character value, but not the final NULL character.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Remarks

EXTENSION TO

ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces
Implemented in the Windows secure API as _strset_s()

Parameters

[out]	dest	string that will be set.
[in]	dmax	restricted maximum length of dest
[in]	value	character value to write

Precondition: dest shall not be a null pointer, and shall be null-terminated.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; dmax shall not equal zero.; value shall not be greater than 255

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when value > 255 or dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: strzero_s(), strnset_s(), strispassword_s()

◆ strnset_s

#define strnset_s	(	dest,
		dmax,
		value,
		n
	)	_strnset_s_chk(dest, dmax, value, n, BOS(dest))

Sets maximal n characters of dest to a character value, but not the final NULL character.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Remarks

EXTENSION TO

ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces
Implemented in the Windows secure API as _strnset_s()

Parameters

[out]	dest	string that will be set.
[in]	dmax	restricted maximum length of dest
[in]	value	character value to write
[in]	n	number of characters to be written

Precondition: dest shall not be a null pointer, and shall be null-terminated.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; dmax shall not equal zero.; n shall not be greater than dmax; value shall not be greater than 255

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when value > 255 or dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOSPC	when n > dmax

See also: strzero_s(), strset_s(), wcsnset_s(), strispassword_s()

◆ mbstowcs_s

#define mbstowcs_s	(	retvalp,
		dest,
		dmax,
		src,
		len
	)	_mbstowcs_s_chk(retvalp, dest, dmax, src, len, BOS(dest))

The mbstowcs_s function converts a null-terminated multibyte character sequence from the current LC_CTYPE locale to wchar, which begins in the conversion state described by *ps, from the array whose first element is pointed to by *src to its wide character representation.

If dest is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dest. No more than len wide characters are written to the destination array. Each multibyte character is converted as if by a call to mbrtowc. mbstowcs_s clobbers the destination array from the terminating null and until dmax. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

The conversion stops if:

The multibyte NUL character was converted and stored.
An invalid multibyte character (according to the current C locale) was encountered.
the next wide character to be stored would exceed len. This condition is not checked if dest==NULL.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.6.5.1 The mbstowcs_s function (p: 611-612) http://en.cppreference.com/w/c/string/multibyte/mbstowcs
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retvalp	pointer to a `size_t` object where the result will be stored
[out]	dest	NULL or pointer to wide character array for the result
[in]	dmax	restricted maximum length of `dest`
[in]	src	string that will be converted to `dest`
[in]	len	maximal number of wide characters to be written to `dest` (exclusive the final L'\0' when needed)

Precondition: retvalp and src shall not be a null pointer.; dmax and len shall not be greater than RSIZE_MAX_WSTR, unless dest is null.; dmax shall not equal zero, unless dest is null.; dmax shall be greater than wcsnlen_s(src, dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then mbstowcs_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retval or src are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_WSTR, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax and dest != NULL
ESOVRLP	when src and dest overlap
ESNOSPC	when there is no NUL character in the first dmax multibyte characters in the src array and len is greater than dmax (unless dest is null)

See also: mbsrtowc_s()

◆ mbsrtowcs_s

#define mbsrtowcs_s	(	retvalp,
		dest,
		dmax,
		srcp,
		len,
		ps
	)	_mbsrtowcs_s_chk(retvalp, dest, dmax, srcp, len, ps, BOS(dest))

Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer.

The restartable mbsrtowcs_s function converts a null-terminated multibyte character sequence from the current LC_CTYPE locale to wchar, which begins in the conversion state described by *ps, from the array whose first element is pointed to by *srcp to its wide character representation. If dest is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dest. No more than len wide characters are written to the destination array. Each multibyte character is converted as if by a call to mbrtowc. mbsrtowcs_s clobbers the destination array from the terminating null and until dmax. In extension to mbstowc_s you can re-use the state via ps. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

The conversion stops if:

The multibyte NUL character was converted and stored. *srcp is set to NULL and *ps represents the initial shift state.
An invalid multibyte character (according to the current C locale) was encountered. *srcp is set to point at the beginning of the first unconverted multibyte character.
the next wide character to be stored would exceed len. *srcp is set to point at the beginning of the first unconverted multibyte character. This condition is not checked if dest==NULL.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.3.2.1 The mbsrtowcs_s function (p: 648-649) http://en.cppreference.com/w/c/string/multibyte/mbsrtowcs
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retvalp	pointer to a `size_t` object where the result will be stored
[out]	dest	pointer to wide character array where the results will be stored
[in]	dmax	restricted maximum length of `dest`
[in]	srcp	pointer to the string that will be copied to `dest`
[in]	len	maximal number of wide characters to be copied to `dest`
[in]	ps	pointer to the conversion state object

Precondition: retvalp, ps, srcp, or *srcp shall not be a null pointer.; dmax and len shall not be greater than RSIZE_MAX_WSTR (unless dest is null).; dmax shall not equal zero.; dmax shall be greater than wcsnlen_s(*srcp, dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.; On the msvcrt with a NULL dest pointer, the retvalp length is limited by the src len. In other libc's len is ignored.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then mbsrtowcs_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp, ps, srcp or *srcp are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_WSTR, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax and dest != NULL
ESOVRLP	when *srcp and dest overlap
ESNOSPC	when there is no NUL character in the first dmax multibyte characters in the *srcp array and len is greater than dmax (unless dest is null)

See also: mbstowc_s()

◆ wcsrtombs_s

#define wcsrtombs_s	(	retvalp,
		dest,
		dmax,
		srcp,
		len,
		ps
	)	_wcsrtombs_s_chk(retvalp, dest, dmax, srcp, len, ps, BOS(dest))

Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer.

The restartable wcsrtombs_s function converts a sequence of wide characters from the array whose first element is pointed to by *srcp to to its narrow multibyte representation from the current LC_CTYPE locale that begins in the conversion state described by *ps. If dest is not null, converted characters are stored in the successive elements of dest. No more than len bytes written to the destination array. Each wide character is converted as if by a call to wcrtomb. wcsrtombs_s clobbers the destination array from the terminating null and until dmax. In extension to wcstombs_s you can re-use the state via ps.

The conversion stops if:

The wide NUL character L'\0' was converted and stored. The bytes stored in this case are the unshift sequence (if necessary) followed by '\0', *srcp is set to NULL and *ps represents the initial shift state.
A wchar_t was found that does not correspond to a valid character in the current LC_CTYPE locale. *srcp is set to point at the first unconverted wide character.
the next multibyte character to be stored would exceed len. *srcp is set to point at the beginning of the first unconverted wide character. This condition is not checked if dst==NULL.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled. Also in the error cases for srcp = NULL, *srcp = NULL, ESNOSPC and EILSEQ.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.3.2.2 The wcsrtombs_s function (p: 649-650) http://en.cppreference.com/w/c/string/wide/wcsrtombs
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retvalp	pointer to a `size_t` object where the result will be stored
[out]	dest	pointer to character array where the result will be stored
[in]	dmax	restricted maximum length of `dest`
[in]	srcp	pointer to the wide string that will be copied to `dest`
[in]	len	maximum number of bytes to be written to `dest`
[in]	ps	pointer to the conversion state object

Precondition: retvalp, ps, srcp, or *srcp shall not be a null pointer.; dmax and len shall not be greater than RSIZE_MAX_STR (unless dest is null).; dmax shall not equal zero (unless dest is null).; dmax shall be greater than len.; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.; On the msvcrt with a NULL dest pointer, the retvalp length is limited by the srcp len. In other libc's len is ignored.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcsrtombs_s nulls dest. Then the number of bytes excluding terminating zero that were, or would be written to dest, is stored in *retvalp.

Note: Under the Windows sec_api the *retvalp result is +1.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp, ps, srcp or *srcp are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
EOVERFLOW	when dmax or len > size of dest (optionally, when the compiler knows the object_size statically), unless dest is NULL
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when *srcp and dest overlap
ESNOSPC	when there is no NUL character in the first dmax multibyte characters in the *srcp array and len is greater than dmax (unless dest is null)
EILSEQ	if returned by wctomb()

See also: wcrtomb_s(), wcstombs_s()

◆ wcstombs_s

#define wcstombs_s	(	retvalp,
		dest,
		dmax,
		src,
		len
	)	_wcstombs_s_chk(retvalp, dest, dmax, src, len, BOS(dest))

The wcstombs_s function converts a sequence of wide characters from the array whose first element is pointed to by src to to its narrow multibyte representation from the current LC_CTYPE locale.

If dest is not null, converted characters are stored in the successive elements of dest. No more than len bytes are written to the destination array. Each wide character is converted as if by a call to wcrtomb. wcstombs_s clobbers the destination array from the terminating null and until dmax.

The conversion stops if:

The wide NUL character L'\0' was converted and stored. The bytes stored in this case are the unshift sequence (if necessary) followed by '\0'.
A wchar_t was found that does not correspond to a valid character in the current LC_CTYPE locale.
the next multibyte character to be stored would exceed len. This condition is not checked if dest==NULL.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled. Also in the error cases for src = NULL, ESNOSPC and EILSEQ.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.6.5.2 The wcstombs_s function (p: 612-613) http://en.cppreference.com/w/c/string/multibyte/wcstombs
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retvalp	the number of characters converted
[out]	dest	buffer for the resulting converted multibyte character string
[in]	dmax	The size in bytes of dest
[in]	src	wide string that will be converted to `dest`
[in]	len	number of bytes to be stored in `dest`, not including the terminating NUL character.

Precondition: retvalp and src shall not be a null pointer.; dmax and len shall not be greater than RSIZE_MAX_STR (unless dest is null).; dmax shall not equal zero (unless dest is null).; dmax shall be greater than len.; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcstombs_s nulls dest. Then the number of bytes excluding terminating zero that were, or would be written to dest, is stored in *retvalp.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp or src are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
EOVERFLOW	when dmax or len > size of dest (optionally, when the compiler knows the object_size statically), unless dest is NULL
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when src and dest overlap
ESNOSPC	when there is no NUL character in the first dmax multibyte characters in the src array and len is greater than dmax (unless dest is null)
EILSEQ	if returned by wcstombs()

See also: mbstowc_s()

◆ wcrtomb_s

#define wcrtomb_s	(	retvalp,
		dest,
		dmax,
		wc,
		ps
	)	_wcrtomb_s_chk(retvalp, dest, dmax, wc, ps, BOS(dest))

Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer.

The restartable wcrtomb_s function converts a single wide character to its narrow multibyte representation from the current LC_CTYPE locale that begins in the conversion state described by *ps. If dest is not null, the converted multibyte characters are stored in dest. Max. MB_CUR_MAX will be written to dest.

If dest is a null pointer, the call is equivalent to wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) with internal variables retval and buf (whose size is greater than MB_CUR_MAX).

If wc is the null wide character L'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.

If the environment macro STDC_ISO_10646 is defined, the values of type wchar_t are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

If the environment macro STDC_MB_MIGHT_NEQ_WC is defined, then for members of the basic character set multibyte-character encoding might not equal wide-character encoding (non-ASCII-based systems, such as EBCDIC-based systems, may use Unicode for their wide character encoding and still be conforming). ASCII-based systems with STDC_ISO_10646 defined leave STDC_MB_MIGHT_NEQ_WC undefined.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.3.1.1 The wcrtomb_s function (p: 647-648) http://en.cppreference.com/w/c/string/wide/wcrtomb
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retvalp	pointer to a `size_t` object where the result will be stored
[out]	dest	pointer to bytes where the result will be stored
[in]	dmax	restricted maximum length of `dest`
[in]	wc	the wide character to convert
[in]	ps	pointer to the conversion state object

Precondition: retvalp and ps shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR and size of dest (unless dest is null).; dmax shall not equal zero (unless dest is null).; dmax must be zero if dest is null.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: Returns zero on success and non-zero on failure, in which case, dest[0] is set to '\0' (unless dest is null or dmax is invalid) and *retvalp is set to (size_t)-1 (unless retvalp is null).

Return values

EOK	on successful conversion.
ESNULLP	when retvalp or ps are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically), unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
ESLEWRNG	when dmax != size of dest and –enable-error-dmax and dest != NULL
ESNOSPC	when dmax is smaller than the number of required bytes

See also: wctomb_s()

◆ wctomb_s

#define wctomb_s	(	retvalp,
		dest,
		dmax,
		wc
	)	_wctomb_s_chk(retvalp, dest, dmax, wc, BOS(dest))

The wctomb_s function converts a single wide character to its narrow multibyte representation from the current LC_CTYPE locale.

If dest is not null, the converted multibyte characters are stored in dest. Max. MB_CUR_MAX will be written to dest.

If dest is a null pointer, the call is equivalent to wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) with internal variables retval and buf (whose size is greater than MB_CUR_MAX).

If the environment macro STDC_ISO_10646 is defined, the values of type wchar_t are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.

If the environment macro STDC_MB_MIGHT_NEQ_WC is defined, then for members of the basic character set multibyte-character encoding might not equal wide-character encoding (non-ASCII-based systems, such as EBCDIC-based systems, may use Unicode for their wide character encoding and still be conforming). ASCII-based systems with STDC_ISO_10646 defined leave STDC_MB_MIGHT_NEQ_WC undefined.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled. Also in the error cases for ESNOSPC and EILSEQ.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.6.4.1 The wctomb_s function (p: 610-611) http://en.cppreference.com/w/c/string/multibyte/wctomb
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retvalp	pointer to a `size_t` object where the result will be stored
[out]	dest	pointer to bytes where the result will be stored
[in]	dmax	restricted maximum length of `dest`
[in]	wc	the wide character to convert

Precondition: retvalp shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR and size of dest (unless dest is null).; dmax shall not equal zero (unless dest is null).; dmax must be zero if dest is null.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: Returns zero on success and non-zero on failure, in which case, dest[0] is set to '\0' (unless dest is null or dmax is invalid) and *retvalp is set to (size_t)-1 (unless retvalp is null).

Return values

EOK	on successful conversion.
ESNULLP	when retvalp is a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOSPC	when dmax is smaller than the number of required bytes
EILSEQ	if returned by wctomb()

See also: wcrtomb_s()

◆ wcsnlen_s

#define wcsnlen_s	(	str,
		smax
	)	_wcsnlen_s_chk(str, smax, BOS(str))

The wcsnlen_s function computes the length of the wide string pointed to by str, providing limited support for non-zero terminated strings.

Remarks: SPECIFIED IN ISO/IEC TR 24731-1, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

str	pointer to wide string
smax	maximum length of wide string, incl. the final NUL

Precondition: str shall not be a null pointer.; smax shall not equal zero.; smax shall not be greater than RSIZE_MAX_WSTR and size of str (inc. final NUL).

Note: On mingw with MINGW_HAS_SECURE_API this API is forceinline'd and the native wcsnlen_s with the msvcrt has a different smax limit: INT_MAX.; Unlike specified in the C11 spec the runtime-constraint handlers are called.

Returns: The function returns the wide string length, excluding the terminating NUL character. If str is NULL, then wcsnlen_s returns 0. Otherwise, the wcsnlen_s function returns the number of wide characters that precede the terminating NUL character. If there is no NUL character in the first smax characters of str then wcsnlen_s returns smax. At most the first smax characters of str are accessed by wcsnlen_s.

See also: strnlen_s(), strnterminate_s()

◆ wcscpy_s

#define wcscpy_s	(	dest,
		dmax,
		src
	)	_wcscpy_s_chk(dest, dmax, src, BOS(dest))

The wcscpy_s function copies the string pointed to by src (including the terminating NUL character) into the array pointed to by dest.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written by wcscpy_s in the array of dmax characters pointed to by dest are nulled when wcscpy_s returns.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.2.1.1 The wcscpy_s function (p: 639) http://en.cppreference.com/w/c/string/wide/wcscpy
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to wide string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the wide string that will be copied to dest

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.; dmax shall not equal zero.; dmax shall be greater than wcsnlen_s(src, dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcscpy_s nulls dest.

Return values

EOK	when successful operation, the wide characters in src were copied into dest and the result is zero terminated.
-ESNULLP	when dest or src is a NULL pointer
-ESZEROL	when dmax = 0
-ESLEMAX	when dmax > RSIZE_MAX_WSTR
-ESOVRLP	when buffers overlap
-ESNOSPC	when dest < src

See also: wcsncpy(), wmemcpy(), wmemmove(), strncpy_s()

◆ wcsncpy_s

#define wcsncpy_s	(	dest,
		dmax,
		src,
		slen
	)	_wcsncpy_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))

The wcsncpy_s function copies the wide string pointed to by src (including the terminating NUL character) into the wide string pointed to by dest.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written by wcsncpy_s in the array of dmax characters pointed to by dest are nulled when wcsncpy_s returns.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.2.1.2 The wcsncpy_s function (p: 639) http://en.cppreference.com/w/c/string/wide/wcsncpy
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to wide string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the wide string that will be copied to dest
[in]	slen	maximum number of wide characters to copy

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be greater than RSIZE_MAX_WSTR.; dmax shall not equal zero.; If slen is either greater than or equal to dmax, then dmax should be more than wcsnlen_s(src,dmax) to avoid truncation.; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest and dmax are valid, then wcsncpy_s nulls dest.

Return values

EOK	successful operation, when slen == 0 or the wide characters in src were copied into dest and the result is zero terminated.
ESNULLP	when dest/src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when buffers overlap
ESNOSPC	when src > dest

See also: wcscpy_s(), strncpy_s(), wmemcpy_s(), wmemmove_s()

◆ wcscat_s

#define wcscat_s	(	dest,
		dmax,
		src
	)	_wcscat_s_chk(dest, dmax, src, BOS(dest))

The wcscat_s function appends a copy of the wide string pointed to by src (including the terminating NUL character) to the end of the wide string pointed to by dest.

The initial wide character from src overwrites the NUL character at the end of dest.

All elements following the terminating null wide character (if any) written by wcscat_s in the array of dmax characters pointed to by dest take unspeciﬁed values when wcscat_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.2.2.1 The wcscat_s function (p: 642-643) http://en.cppreference.com/w/c/string/wide/wcscat
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to wide string that will be extended by src if dmax allows. The wide string is zero terminated. If the resulting concatenated wide string is less than dmax, the remaining slack space is nulled.
[in]	dmax	restricted maximum wchar_t length of the resulting dest, including the null
[in]	src	pointer to the wide string that will be concatenaed to string dest

Precondition: Neither dest nor src shall be a null pointer; dmax shall not equal zero; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest; dmax shall be greater than wcsnlen_s(src,m).; Copying shall not take place between objects that overlap

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcscat_s nulls dest.

Return values

EOK	when successful operation, all the wide characters from src were appended to dest and the result in dest is zero terminated.
ESNULLP	when dest or src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESUNTERM	when dest not terminated in the first dmax wide characters
ESOVRLP	when src overlaps with dest

See also: wcscat_s(), strcpy_s(), strncpy_s()

◆ wcsncat_s

#define wcsncat_s	(	dest,
		dmax,
		src,
		slen
	)	_wcsncat_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))

The wcsncat_s function appends a copy of the wide string pointed to by src (including the terminating null wide character) to the end of the wide string pointed to by dest.

The initial character from src overwrites the null wide character at the end of dest.

All elements following the terminating null wide character (if any) written by wcsncat_s in the array of dmax wide characters pointed to by dest take unspeciﬁed values when wcsncat_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.2.2.2 The wcsncat_s function (p: 643-644) http://en.cppreference.com/w/c/string/wide/wcsncat
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	dest	pointer to wide string that will be extended by src if dmax allows. The string is zero terminated. If the resulting concatenated wide string is less than dmax, the remaining slack space is nulled.
[in]	dmax	restricted maximum length of the resulting dest, including the null
[in]	src	pointer to the wide string that will be concatenaed to string dest
[in]	slen	maximum wide characters to append

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.; dmax shall be greater than wcsnlen_s(src,slen).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.; The Windows MSVCRT sec_api EINVAL and ERANGE works ok, ESLEMAX dmax/slen>MAX not, ESOVRLP partially. When dest>src Windows appends the result, when dest<src ERANGE or EINVAL is returned.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcsncat_s nulls dest.

Return values

EOK	successful operation, when slen == 0 or all the wide characters are copied from src and dest is zero terminated. As special case, analog to msvcrt: when slen == 0 and dmax is big enough for dest, also return EOK, but clear dest.
ESNULLP	when dest/src is NULL pointer and slen > 0
ESZEROL	when dmax = 0 and slen > 0
ESLEMAX	when dmax/slen > RSIZE_MAX_WSTR and slen > 0
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESUNTERM	when dest not terminated and slen > 0
ESOVRLP	when src overlaps with dest and slen > 0

See also: wcscat_s(), strncat_s()

◆ wcstok_s

#define wcstok_s	(	dest,
		dmaxp,
		delim,
		ptr
	)	_wcstok_s_chk(dest, dmaxp, delim, ptr, BOS(dest))

A sequence of calls to the wcstok_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 wcstok_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 wcstok_s function returns a null pointer. If such a character is found, it is the start of the first token.

The wcstok_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 NUL character, which terminates the current token.

In all cases, the wcstok_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 NUL character (if any).

delim uses a STRTOK_DELIM_MAX_LEN of 16.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.2.3.1 The wcstok_s function (p: 645-646) http://en.cppreference.com/w/c/string/wide/wcstok
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 wide string to tokenize
[out]	dmaxp	pointer to the restricted maximum length of dest
[in]	delim	pointer to wide 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.; dmaxp shall not be a null pointer.; *dmaxp 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 *dmaxp shall not be greater than RSIZE_MAX_WSTR and the size of dest. 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. wchar_t* wcstok_s(wchar_t *str, const wchar_t *delim, wchar_t **next_token); C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.

Returns: The wcstok_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 wide 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_WSTR EOVERFLOW when *dmax > size of dest if dest != NULL ESUNTERM when unterminated string C11 just returns EINVAL

Remarks: Example to demonstrate usage of wcstok_s() to tokenize a string
// Approach1: sequential wcstok_s() calls

str1 = L",.:*one,two;three,;four*.*.five-six***"; // String to tokenize

len = 38;

str2 = L",.;*"; // String of delimiters

p2tok = wcstok_s(str1, &len, str2, &p2str);

// token: one, remaining: two;three,;four*.*.five-six***, len: 30

p2tok = wcstok_s(NULL, &len, str2, &p2str);

// token: two, remaining: three,;four*.*.five-six***, len: 26

p2tok = wcstok_s(NULL, &len, str2, &p2str);

// token: three, remaining: ;four*.*.five-six***, len: 20

p2tok = wcstok_s(NULL, &len, str2, &p2str);

// token: four, remaining .*.five-six***, len: 14

p2tok = wcstok_s(NULL, &len, str2, &p2str);

// token: five-six, remaining: **, len: 2

p2tok = wcstok_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 = wcstok_s(NULL, &len, str2, &p2str);

printf(" token -- remaining -- len=0 \n", p2tok, p2str, (int)len );

}

◆ swprintf_s

#define swprintf_s	(	dest,
		dmax,
		...
	)	_swprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)

◆ vswprintf_s

#define vswprintf_s	(	dest,
		dmax,
		fmt,
		ap
	)	_vswprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

◆ vsnwprintf_s

#define vsnwprintf_s	(	dest,
		dmax,
		fmt,
		ap
	)	_vsnwprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

The truncating vsnwprintf_s function composes a wide string with same test that would be printed if format was used on wprintf.

Instead of being printed, the content is stored in dest. dest will be terminated with a NUL character. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written by vsnwprintf_s in the array of dmax wide characters pointed to by dest are nulled when vsnwprintf_s returns.

Note: POSIX specifies that errno is set on error. However, the safeclib extended ES* errors do not set errno, only when the underlying system vswprintf or vsnwprintf call fails, errno is set.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.1.8 The vsnwprintf_s function (p: 634-635) http://en.cppreference.com/w/c/io/vfwprintf

Parameters

[out]	dest	pointer to wide string that will be written into.
[in]	dmax	restricted maximum length of dest
[in]	fmt	format-control wide string.
[in]	ap	optional arguments

Precondition: Neither dest nor fmt shall be a null pointer.; dmax shall not be greater than RSIZE_MAX_WSTR.; dmax shall not equal zero.; dmax shall be greater than wcsnlen_s(dest, dmax).; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.; While narrow strings provide snprintf, which makes it possible to determine the required output buffer size, there is no equivalent for wide strings (until C11's snwprintf_s), and in order to determine the buffer size, the program may need to call swprintf, check the result value, and reallocate a larger buffer, trying again until successful.; snwprintf_s, unlike swprintf_s, will truncate the result to fit within the array pointed to by buffer, even though truncation is treated as an error by most bounds-checked functions.

Returns: On success the total number of wide characters written is returned.; On failure a negative number is returned.; If the buffer dest is too small for the formatted text, including the terminating null, then the buffer is set to an empty string by placing a null wide character at dest[0], and the invalid parameter handler is invoked. Unlike vsnwprintf, vswprintf_s guarantees that the buffer will be null-terminated unless the buffer size is zero.

Return values

-ESNULLP	when dest/fmt is NULL pointer
-ESZEROL	when dmax = 0
-ESLEMAX	when dmax > RSIZE_MAX_WSTR
-EOVERFLOW	when `dmax` > size of dest
-EINVAL	when fmt contains n
-1	on some other error. errno is set then

See also: vswprintf_s(), snwprintf_s(), vsnprintf_s()

◆ wcsstr_s

#define wcsstr_s	(	dest,
		dmax,
		src,
		slen,
		substringp
	)	_wcsstr_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))

The wcsstr_s() function locates the first occurrence of the wide substring pointed to by src which would be located in the wide string pointed to by dest.

Remarks

EXTENSION TO

ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	wide string to be searched for the substring
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the wide sub string
[in]	slen	the maximum number of wide characters to use from src
[out]	substringp	the returned substring pointer

Precondition: Neither dest nor src shall be a null pointer.; dmax/ shall not be 0; slen shall not be 0, when *src != 0 and src != dest; Neither dmax nor slen shall be greater than RSIZE_MAX_WSTR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substringp is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOTFND	when substring not found

See also: wcsstr(), strstr_s(), memcmp32_s()

◆ wcscmp_s

#define wcscmp_s	(	dest,
		dmax,
		src,
		smax,
		resultp
	)	_wcscmp_s_chk(dest, dmax, src, smax, resultp, BOS(dest), BOS(src))

Compares wide string src to wide string dest.

Remarks: EXTENSION TO ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	wide string to compare against
[in]	dmax	restricted maximum length of wide string dest
[in]	src	wide string to be compared to dest
[in]	smax	restricted maximum length of wide string src
[out]	resultp	pointer to result diff, greater than 0, equal to 0 or less than 0, if the dest is greater than, equal to or less than src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax/smax shall not be 0; dmax/smax shall not be greater than RSIZE_MAX_WSTR and size of dest/src

Returns: *resultp, when the return code is OK: >0 when dest greater than src 0 when wide strings the same <0 when dest less than src

Return values

EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/smax > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strcmp_s(), wcsncmp_s(), wcsicmp_s()

◆ wcsncmp_s

#define wcsncmp_s	(	dest,
		dmax,
		src,
		smax,
		count,
		resultp
	)	_wcsncmp_s_chk(dest, dmax, src, smax, count, resultp, BOS(dest), BOS(src))

Compares at most count wide characters of wide string src with wide string dest, and returns if difference in the last parameter.

Remarks: EXTENSION TO ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	wide string to compare against
[in]	dmax	restricted maximum length of wide string dest
[in]	src	wide string to be compared to dest
[in]	smax	restricted maximum length of wide string src
[in]	count	maximum number of wide characters to compare
[out]	resultp	pointer to result diff, greater than 0, equal to 0 or less than 0, if the dest is greater than, equal to or less than src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax/smax shall not be 0; dmax/smax shall not be greater than RSIZE_MAX_WSTR and size of dest/src.

Returns: *resultp, when the return code is OK: >0 when dest greater than src 0 when wide strings the same <0 when dest less than src

Return values

EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/smax > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strcmp_s(), wcscmp_s()

◆ wcsicmp_s

#define wcsicmp_s	(	dest,
		dmax,
		src,
		smax,
		resultp
	)	_wcsicmp_s_chk(dest, dmax, src, smax, resultp, BOS(dest), BOS(src))

Compares two wide strings case-folded, via wcsfc_s(), i.e.

case-folded and normalized, and returns if difference in the last parameter. The two strings may overlap.

Parameters

[in]	dest	wide string to compare against
[in]	dmax	restricted maximum length of wide string dest
[in]	src	wide string to be compared to dest
[in]	smax	restricted maximum length of wide string src
[out]	resultp	pointer to result diff, greater than 0, equal to 0 or less than 0, if the dest is greater than, equal to or less than src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax/smax shall not be 0; dmax/smax shall not be greater than RSIZE_MAX_WSTR and size of dest/src

Returns: *resultp, when the return code is OK: >0 when dest greater than src 0 when wide strings the same <0 when dest less than src

Return values

EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/smax > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strcmp_s(), wcscmp_s(), wcsncmp_s(), wcsfc_s()

◆ wcsnatcmp_s

#define wcsnatcmp_s	(	dest,
		dmax,
		src,
		smax,
		resultp
	)	_wcsnatcmp_s_chk(dest, dmax, src, smax, 0, resultp, BOS(dest), BOS(src))

◆ wcsnaticmp_s

#define wcsnaticmp_s	(	dest,
		dmax,
		src,
		smax,
		resultp
	)	_wcsnatcmp_s_chk(dest, dmax, src, smax, 1, resultp, BOS(dest), BOS(src))

Natural order comparison of strings.

The longest run of numbers wins over alpha chars.

Remarks: EXTENSION TO ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to wide string to compare against
[in]	dmax	restricted maximum length of wide string dest
[in]	src	pointer to the wide string to be compared to dest
[in]	smax	restricted maximum length of wide string src
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax/smax shall not be 0; dmax/smax shall not be greater than RSIZE_MAX_WSTR and size of dest/src

Returns: resultp (when the return code is OK) >0 when dest greater than src 0 when strings are the same <0 when dest less than src

Return values

EOK	when comparison is complete
ESUNTERM	when dest or src is unterminated, or dmax is too small.
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/smax > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: strnatcmp_s() wcscmp_s()

◆ wcsset_s

#define wcsset_s	(	dest,
		dmax,
		value
	)	_wcsset_s_chk(dest, dmax, value, BOS(dest))

Sets maximal dmax wide characters of dest to a wide character value, but not the final NULL character.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax wide characters pointed to by dest are nulled.

Remarks

EXTENSION TO

ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces
Implemented in the Windows secure API as _wcsset_s()

Parameters

[out]	dest	wide string that will be set.
[in]	dmax	restricted maximum length of dest
[in]	value	wide character value to write

Precondition: dest shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.; value shall not be greater than _UNICODE_MAX

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR or value > _UNICODE_MAX
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: wcsnset_s(), wmemset_s(), strzero_s(), strnset_s(), strispassword_s()

◆ wcsnset_s

#define wcsnset_s	(	dest,
		dmax,
		value,
		n
	)	_wcsnset_s_chk(dest, dmax, value, n, BOS(dest))

Sets maximal n wide characters of dest to a wide character value, but not the final NULL character.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax wide characters pointed to by dest are nulled.

Remarks

EXTENSION TO

ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces
Implemented in the Windows secure API as _wcsnset_s()

Parameters

[out]	dest	wide string that will be set.
[in]	dmax	restricted maximum length of dest
[in]	value	wide character value to write
[in]	n	number of wide characters to be written

Precondition: dest shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.; value shall not be greater than _UNICODE_MAX; n shall not be greater than dmax

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR or value > _UNICODE_MAX
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOSPC	when n > dmax

See also: wcsset_s(), wmemset_s(), strzero_s(), strnset_s(), strispassword_s()

◆ wcscoll_s

#define wcscoll_s	(	dest,
		dmax,
		src,
		smax,
		resultp
	)	_wcscoll_s_chk(dest, dmax, src, smax, resultp, BOS(dest), BOS(src))

Compares two null-terminated wide strings according to the current locale as defined by the LC_COLLATE category.

Collation order is the dictionary order: the position of the letter in the national alphabet (its equivalence class) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single collation units. For example, "ch" in Czech follows "h" and precedes "i", and "dzs" in Hungarian follows "dz" and precedes "g".

Remarks: EXTENSION TO ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	wide string to compare against
[in]	dmax	restricted maximum length of dest
[in]	src	wide string to be compared to dest
[in]	smax	restricted maximum length of src
[out]	resultp	pointer to result indicator, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax/smax shall not be 0; dmax/smax shall not be greater than RSIZE_MAX_WSTR and size of dest/src

Returns: *resultp, when the return code is OK: >0 when dest greater than src 0 when strings the same <0 when dest less than src

Return values

EOK	when comparison is complete
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax/smax > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: wcscmp_s(), strcoll_s(), strcasecmp_s()

◆ wcslwr_s

#define wcslwr_s	(	src,
		slen
	)	_wcslwr_s_chk(src, slen, BOS(src))

Scans the string converting uppercase characters to simple lowercase, leaving all other characters unchanged.

The scanning stops at the first null or after slen characters. The conversion is determined by the LC_CTYPE category setting of the locale. Other characters are not affected. It only performs simple case folding via towlower(), it does not do full multi-char folding and does not obey the special casing rules for context. See wcsfc_s() instead. Thus the length of buffer stays the same. It returns a pointer to the altered string. Because the modification is done in place, the pointer returned is the same as the pointer passed as the input argument.

Remarks

IMPLEMENTED IN

Microsoft Windows Secure API
Novell NDK
Nokia openc s60.com

Parameters

[out]	src	wide string
[in]	slen	maximum length of string

Precondition: src shall not be a null pointer.; slen shall not be greater than RSIZE_MAX_WSTR and size of dest.

Return values

EOK	on successful operation or slen = 0
ESNULLP	when src is NULL pointer
ESLEMAX	when slen > RSIZE_MAX_WSTR
EOVERFLOW	when slen > size of src (optionally, when the compiler knows the object_size statically)

See also: wcsfc_s(), strtolowercase_s(), strlwr_s(), wcsupr_s()

◆ wcsupr_s

#define wcsupr_s	(	src,
		slen
	)	_wcsupr_s_chk(src, slen, BOS(src))

Scans the string converting lowercase characters to uppercase, leaving all other characters unchanged.

The scanning stops at the first null or after slen characters. The conversion is determined by the LC_CTYPE category setting of the locale. Other characters are not affected. It converts only single chars via towupper(). It returns a pointer to the altered string. Because the modification is done in place, the pointer returned is the same as the pointer passed as the input argument.

Remarks

IMPLEMENTED IN

Microsoft Windows Secure API
Novell NDK
Nokia openc s60.com

Parameters

[out]	src	wide string
[in]	slen	maximum length of string

Precondition: src shall not be a null pointer.; slen shall not be greater than RSIZE_MAX_WSTR and size of dest.

Return values

EOK	on successful operation or slen = 0
ESNULLP	when src is NULL pointer
ESLEMAX	when slen > RSIZE_MAX_WSTR
EOVERFLOW	when slen > size of src (optionally, when the compiler knows the object_size statically)

See also: strtouppercase_s(), strlwr_s(), wcslwr_s()

◆ towfc_s

#define towfc_s	(	dest,
		dmax,
		src
	)	_towfc_s_chk(dest, dmax, src, BOS(dest))

towfc_s() converts a wide character to fully fold-cased (lowercased with possible expansions), according to the Unicode 10.0 CaseFolding table.

Even in most the unsuccessul cases, just not with with ESNULLP and ESZEROL dest is being written to.

As of Unicode 10.0 there are no possible results as surrogate pairs with sizeof(wchar_t)==2, all results are below U+10000.

Parameters

[out]	dest	wide string buffer to store result
[in]	dmax	maximum size of dest, should be 4. (3 + NULL)
[in]	src	wide character to convert to lowercase

Precondition: dest shall not be a null pointer.; dmax shall be bigger than 3.; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.

Return values

>=0	on successful operation, returns the number of converted wide characters: 0-3
-ESNULLP	when dest is NULL pointer
-ESZEROL	when dmax = 0
-ESLEMIN	when dmax < 4
-ESLEMAX	when dmax > RSIZE_MAX_WSTR
-EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
-ESLEWRNG	when dmax != size of dest and –enable-error-dmax
-ESNOTFND	when no mapping for src was found, iswfc is wrong.

See also: iswfc(), wcsfc_s(), towlower()

◆ wcsfc_s

#define wcsfc_s	(	dest,
		dmax,
		src,
		lenp
	)	_wcsfc_s_chk(dest, dmax, src, lenp, BOS(dest))

Converts the wide string via full case-folding NFD normalized to lowercase.

The conversion stops at the first null or after dmax characters. The conversion is determined by the LC_CTYPE category setting of the locale. Other characters are not affected. fold-case performs full case folding, i.e. if iswfc() of a character > 1, the length of dest might be greater than the length of src (max 4 per char), the conversion is done via towfc_s() and Unicode 10.0, the Unicode special-casing rules are obeyed, and composed characters are normalized to NFD via wcsnorm_decompose_s() and wcsnorm_reorder_s(). If not, the conversion is per character done via normal towlower(). Note that decomposition creates larger strings, typically 2-3 chars more.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

SpecialCasing checks for conditional boundary context at the begin or end of certain characters (final greek sigma), and locale sensitive rules for the Lithuanian and the Turkish/Azeri I-dot.

Composed characters are checked for the left-hand-side of the Decomposition_Mapping Unicode property, which means the codepoint will be normalized to NFD if any codepoint is composed. Technically only FCD as all FC expansions are already properly ordered, and all mangled marks will not be reordered, as the have the same Combining Class.

Parameters

[out]	dest	wide string to hold the result (~130% larger than src)
[in]	dmax	maximum result buffer size
[in]	src	wide string
[out]	lenp	pointer to length of the result, may be NULL

Precondition: dest and src shall not be null pointers.; dmax shall not be smaller than 5 and big enough for dest.; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.

Return values

EOK	on successful operation
ESNULLP	when dest or src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR or a cp > 0x10ffff
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOSPC	when dmax is too small for the decomposition. *lenp is still written, to know how much space is needed.
ESNOTFND	Internal error as returned by towfc_s() for multi-char foldings. happens only when the internal implementations of iswfc() and towfc_s() are mismatched.

See also: iswfc(), towfc_s(), towupper(), wcslwr_s(), wcsupr_s()

◆ wcsnorm_decompose_s

#define wcsnorm_decompose_s	(	dest,
		dmax,
		src,
		lenp,
		iscompat
	)	_wcsnorm_decompose_s_chk(dest, dmax, src, lenp, iscompat, BOS(dest))

Converts the wide string to the canonical NFD normalization, as defined in the latest Unicode standard.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Composed characters are checked for the left-hand-size of the Decomposition_Mapping Unicode property, which means the codepoint will be normalized if the sequence is composed. This is equivalent to all 1963 combining mark characters, plus some remaining 869 non-mark and non-hangul normalizables. Hangul has some special normalization logic.

This function is used by wcsnorm_s() to do the argument checking, overlap checking and to do the first of three passes for NFC.

Parameters

[out]	dest	wide string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	wide string
[out]	lenp	pointer to length of the result, may be NULL
[in]	iscompat	do NFKD, and not NFD (with `--enable-norm-compat`)

Precondition: dest and src shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcsnorm_s nulls dest.

Return values

EOK	on success
ESNULLP	when dest or src is NULL pointer
ESZEROL	when dmax = 0
ESLEMIN	when dmax < 5 or 19 with a compat mode
ESLEMAX	when dmax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when buffers overlap
ESNOSPC	when dmax too small for the result buffer
EOF	on some normalization error

See also: wcsfc_s(), wcsnorm_s(), wcsnorm_compose_s(), wcsnorm_reorder_s(), ICU, gnulib/libunistring, utf8proc

◆ wcsnorm_reorder_s

#define wcsnorm_reorder_s	(	dest,
		dmax,
		src,
		len
	)	_wcsnorm_reorder_s_chk(dest, dmax, src, len, BOS(dest))

Reorder all decomposed sequences in a wide string to NFD, as defined in the latest Unicode standard.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Parameters

[out]	dest	wide string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	wide string to be converted
[in]	len	length of src

Precondition: dest and src shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcsnorm_reorder_s nulls dest.

Return values

EOK	on success
ESNOSPC	when dmax too small for the result buffer
EOF	on some normalization error

See also: wcsnorm_s(), wcsnorm_decompose_s(), ICU, gnulib/libunistring, utf8proc

◆ wcsnorm_compose_s

#define wcsnorm_compose_s	(	dest,
		dmax,
		src,
		lenp,
		iscontig
	)	_wcsnorm_compose_s_chk(dest, dmax, src, lenp, iscontig, BOS(dest))

Combine all decomposed sequences in a wide string to NFC, as defined in the latest Unicode standard.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Parameters

[out]	dest	wide string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	wide string to be converted
[out]	lenp	pointer to length of p and the result length.
[in]	iscontig	if true, the result will only be a fast FCC

Precondition: dest, src and lenp shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcsnorm_reorder_s nulls dest.

Return values

EOK	on success
ESNOSPC	when dmax too small for the result buffer
ESNULLP	when dest, src or lenp are NULL
EOF	on some normalization error

See also: wcsnorm_s(), wcsnorm_decompose_s(), ICU, gnulib/libunistring, utf8proc

◆ wcsnorm_s

#define wcsnorm_s	(	dest,
		dmax,
		src,
		mode,
		lenp
	)	_wcsnorm_s_chk(dest, dmax, src, mode, lenp, BOS(dest))

Converts the wide string to the canonical NFC or NFD normalization, as defined in the latest Unicode standard.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Decomposed characters are checked for the left-hand-size and then right-hand-side of the Decomposition_Mapping Unicode property, which means the codepoint will be normalized if the sequence is composed or decomposed (NFD or NFKD). This is equivalent to all 1963 combining mark characters, plus some remaining 869 non-mark and non-hangul normalizables. Hangul has some special normalization logic.

The compat tables for NFKC or NFKD are too large for a libc, and mostly unused. As default we only provide the smaller canonical conversions, but it can be enabled with --enable-norm-compat. The compat modes also don't roundtrip.

Parameters

[out]	dest	wide string to hold the result
[in]	dmax	maximum length of string
[in]	src	wide string
[in]	mode	convert to nfc or just nfd. experimentally to fast modes FCD or FCC. optionally to compat modes NFKD, NFKC with `–enable-norm-compat`

See also: enum wcsnorm_mode.

Parameters

[out] lenp pointer to length of the result, may be NULL

Precondition: dest and src shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_WSTR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcsnorm_s nulls dest.

Return values

EOK	on success
ESNULLP	when dest or src is NULL pointer
ESZEROL	when dmax = 0
ESLEMIN	when dmax < 5
ESLEMAX	when dmax > RSIZE_MAX_WSTR
ESOVRLP	when buffers overlap
ESNOSPC	when dmax too small for the result buffer
EOF	any other normalization error

See also: wcsfc_s(), ICU, gnulib/libunistring, utf8proc

Function Documentation

◆ abort_handler_s()

EXTERN void abort_handler_s	(	const char *restrict	msg,
		void *restrict	ptr,
		errno_t	error
	)

This function writes a message on the standard error stream in an implementation-defined format.

The message shall include the string pointed to by msg. The abort_handler_s function then calls the abort function.

Remarks: SPECIFIED IN ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	msg	Pointer to the message describing the error
[in]	ptr	Pointer to aassociated data. Can be NULL.
[in]	error	The error code encountered.

See also: ignore_handler_s()

◆ ignore_handler_s()

EXTERN void ignore_handler_s	(	const char *restrict	msg,
		void *restrict	ptr,
		errno_t	error
	)

This function simply returns to the caller.

Remarks: SPECIFIED IN ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	msg	Pointer to the message describing the error
[in]	ptr	Pointer to aassociated data. Can be NULL.
[in]	error	The error code encountered.

See also: abort_handler_s()

◆ set_str_constraint_handler_s()

EXTERN constraint_handler_t set_str_constraint_handler_s ( constraint_handler_t handler )

The set_str_constraint_handler_s function sets the runtime-constraint handler to be handler.

The runtime-constraint handler is the function to be called when a library function detects a runtime-constraint violation. Only the most recent handler registered with set_str_constraint_handler_s is called when a runtime-constraint violation occurs. When the handler is called, it is passed the following arguments in the following order:

A pointer to a character string describing the runtime-constraint violation.
A null pointer or a pointer to an implementation defined object.
If the function calling the handler has a return type declared as errno_t, the return value of the function is passed. Otherwise, a positive value of type errno_t is passed. The implementation has a default constraint handler that is used if no calls to the set_constraint_handler_s function have been made. The behavior of the default handler is implementation-defined, and it may cause the program to exit or abort. If the handler argument to set_constraint_handler_s is a null pointer, the implementation default handler becomes the current constraint handler.

Remarks: SPECIFIED IN ISO/IEC JTC1 SC22 WG14 N1172, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

See also: set_str_constraint_handler_s()

◆ thrd_set_str_constraint_handler_s()

EXTERN constraint_handler_t thrd_set_str_constraint_handler_s ( constraint_handler_t handler )

The thrd_set_str_constraint_handler_s function sets the runtime-constraint handler to a thread-local handler.

The thrd_set_str_constraint_handler_s function behaves the same way as the set_str_constraint_handler_s function except that it sets the runtime-constraint handler to the handler only for the calling thread and for any threads that are yet to be created by the calling thread. The function has no effect on other threads in the program. The remaining effects of the two functions are identical, as are their return values.

Remarks: SPECIFIED IN ISO/IEC JTC1 SC22 WG14 N2809 https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2809.pdf

See also: thrd_set_mem_constraint_handler_s()

◆ _strcat_s_chk()

EXTERN errno_t _strcat_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		const size_t	destbos
	)

◆ _strcpy_s_chk()

EXTERN errno_t _strcpy_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		const size_t	destbos
	)

◆ _strncat_s_chk()

EXTERN errno_t _strncat_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	slen,
		const size_t	destbos,
		const size_t	srcbos
	)		&&

◆ BOS_ATTR() [1/6]

EXTERN errno_t empty dest or dmax BOS_ATTR	(	(slen\|\|dest\|\|dmax) &&_BOS_OVR(dest, dmax)	,
		"dest overflow"
	)

◆ _strncpy_s_chk()

EXTERN errno_t _strncpy_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	slen,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _strnlen_s_chk()

EXTERN rsize_t _strnlen_s_chk	(	const char *	str,
		rsize_t	smax,
		size_t	strbos
	)

◆ _strtok_s_chk()

EXTERN char * _strtok_s_chk	(	char *restrict	dest,
		rsize_t *restrict	dmaxp,
		const char *restrict	delim,
		char **restrict	ptr,
		const size_t	destbos
	)

◆ BOS_ATTR() [2/6]

EXTERN char *dmaxp BOS_ATTR	(	dest &&	_BOS_NULLdmaxp,
		"empty dmax"
	)

◆ sprintf_s()

EXTERN int sprintf_s	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	fmt,
			...
	)

◆ BOS_CHK()

EXTERN int BOS_CHK ( dest )

◆ _vsprintf_s_chk()

EXTERN int _vsprintf_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const char *restrict	fmt,
		va_list	ap
	)

◆ snprintf_s()

EXTERN int snprintf_s	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	fmt,
			...
	)

◆ _vsnprintf_s_chk()

EXTERN int _vsnprintf_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const char *restrict	fmt,
		va_list	ap
	)

◆ sscanf_s()

EXTERN int sscanf_s	(	const char *restrict	buffer,
		const char *restrict	fmt,
			...
	)

◆ BOS_NULL() [1/11]

EXTERN int BOS_NULL ( buffer )

◆ fscanf_s()

EXTERN int fscanf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
			...
	)

◆ BOS_NULL() [2/11]

EXTERN int BOS_NULL ( stream )

◆ scanf_s()

EXTERN int scanf_s	(	const char *restrict	fmt,
			...
	)

◆ BOS_FMT()

EXTERN int BOS_FMT ( fmt )

◆ vscanf_s()

EXTERN int vscanf_s	(	const char *restrict	fmt,
		va_list	ap
	)

The vscanf_s function reads a formatted string from stdin, and writes to a list of arguments.

Reaching the end of the io buffer is equivalent to reaching the end-of-file condition for fscanf.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.11 The vscanf_s function (p: 599) http://en.cppreference.com/w/c/io/vfscanf

Parameters

[in]	fmt	format-control string.
[out]	ap	arguments to write to

Precondition: fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a c into a single character) and except that the following errors are detected at runtime and call the currently installed constraint handler function. (not yet)

Warning: The current implementation just does some basic argument checks and then calls the native vsscanf() libc function. Thus the s null pointer check and the two-arg versions of c, s, and %[ are not yet implemented.

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error

See also: vfscanf_s(), scanf_s(), vsscanf_s()

◆ vfscanf_s()

EXTERN int vfscanf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
		va_list	ap
	)

The vfscanf_s function reads a formatted string from a buffered FILE stream, and writes to a list of arguments.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.9 The vfscanf_s function (p: 597-598) http://en.cppreference.com/w/c/io/vfscanf

Parameters

[in]	stream	pointer to a FILE stream to read from
[in]	fmt	format-control string.
[out]	ap	arguments to write to

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a c into a single character) and except that the following errors are detected at runtime and call the currently installed constraint handler function. (not yet)

Warning: The current implementation just does some basic argument checks and then calls the native vsscanf() libc function. Thus the s null pointer check and the two-arg versions of c, s, and %[ are not yet implemented.

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error

See also: vvfscanf_s(), fwscanf_s(), scanf_s()

◆ vsscanf_s()

EXTERN int vsscanf_s	(	const char *restrict	buffer,
		const char *restrict	fmt,
		va_list	ap
	)

The vsscanf_s function reads a formatted string, and writes to a list of arguments.

Reaching the end of the string is equivalent to reaching the end-of-file condition for fscanf.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.14 The vsscanf_s function (p: 602) http://en.cppreference.com/w/c/io/vfscanf

Parameters

[in]	buffer	pointer to a null-terminated string to read from
[in]	fmt	format-control string.
[out]	ap	arguments to write to

Precondition: Neither buffer nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a c into a single character) and except that the following errors are detected at runtime and call the currently installed constraint handler function. (not yet)

Warning: The current implementation just does some basic argument checks and then calls the native vsscanf() libc function. Thus the s null pointer check and the two-arg versions of c, s, and %[ are not yet implemented.

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error

See also: vvsscanf_s(), swscanf_s(), vsnprintf_s()

◆ printf_s()

EXTERN int printf_s	(	const char *restrict	fmt,
			...
	)

◆ fprintf_s()

EXTERN int fprintf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
			...
	)

◆ vprintf_s()

EXTERN int vprintf_s	(	const char *restrict	fmt,
		va_list	ap
	)

The vprintf_s function composes a string via the format string and writes it to a FILE buffer.

Note: POSIX specifies that errno is set on error. However, the safeclib extended ES* errors do not set errno, only when the underlying system vprintf call fails, errno is set.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.10 The vprintf_s function (p: 599-599) http://en.cppreference.com/w/c/io/vfprintf

Parameters

[in]	fmt	format-control string
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; fmt shall not contain the conversion specifier n.; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.

Returns: On success the total number of characters written is returned.; On failure a negative number is returned.

Return values

-ESNULLP	when fmt is NULL pointer
-EINVAL	when fmt contains n
-1	on some other error. errno is set then.

◆ vfprintf_s()

EXTERN int vfprintf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
		va_list	ap
	)

The vfprintf_s function composes a string via the format string and writes it to a FILE buffer.

Note: POSIX specifies that errno is set on error. However, the safeclib extended ES* errors do not set errno, only when the underlying system vfprintf call fails, errno is set.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.5.3.8 The vfprintf_s function (p: 597) http://en.cppreference.com/w/c/io/vfprintf

Parameters

[out]	stream	output file stream to write to
[in]	fmt	format-control string.
[in]	ap	optional arguments

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n.; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.

Returns: On success the total number of characters written is returned.; On failure a negative number is returned.

Return values

-ESNULLP	when stream or fmt is NULL pointer
-EINVAL	when fmt contains n
-1	on some other error. errno is set then.

◆ _strerror_s_chk()

EXTERN errno_t _strerror_s_chk	(	char *	dest,
		rsize_t	dmax,
		errno_t	errnum,
		const size_t	destbos
	)

◆ strerrorlen_s()

EXTERN size_t strerrorlen_s ( errno_t errnum )

The strerrorlen_s function returns the untruncated length of the textual description of the system error code errnum, identical to the description that would be printed by perror().

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.7.4.2 The strerrorlen_s function (p: 622) http://en.cppreference.com/w/c/byte/strerror
ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in] errnum integer value referring to an error code

Returns: The length of the error message or 0

See also: strerror_s()

◆ _stpcpy_s_chk()

EXTERN char * _stpcpy_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		errno_t *restrict	errp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _stpncpy_s_chk()

EXTERN char * _stpncpy_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	slen,
		errno_t *restrict	errp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ BOS_NULL() [3/11]

EXTERN char slen BOS_NULL ( errp )

◆ _strcmp_s_chk()

EXTERN errno_t _strcmp_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _strcasecmp_s_chk()

EXTERN errno_t _strcasecmp_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		int *	resultp,
		const size_t	destbos
	)

◆ _strnatcmp_s_chk()

EXTERN errno_t _strnatcmp_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		const int	fold_case,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _strcasestr_s_chk()

EXTERN errno_t _strcasestr_s_chk	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		char **	substring,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ BOS_NULL() [4/11]

EXTERN errno_t slen BOS_NULL ( substring )

◆ _strcmpfld_s_chk()

EXTERN errno_t _strcmpfld_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		int *	resultp,
		const size_t	destbos
	)

◆ _strcpyfld_s_chk()

EXTERN errno_t _strcpyfld_s_chk	(	char *	dest,
		const rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		const size_t	destbos
	)

◆ BOS_OVR2_BUTZERO()

EXTERN errno_t slen BOS_OVR2_BUTZERO	(	src	,
		slen
	)

◆ _strcpyfldin_s_chk()

EXTERN errno_t _strcpyfldin_s_chk	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		const size_t	destbos
	)

◆ _strcpyfldout_s_chk()

EXTERN errno_t _strcpyfldout_s_chk	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		const size_t	destbos
	)

◆ _strcspn_s_chk()

EXTERN errno_t _strcspn_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		rsize_t *	countp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ BOS_NULL() [5/11]

EXTERN errno_t slen BOS_NULL ( countp )

◆ _strfirstchar_s_chk()

EXTERN errno_t _strfirstchar_s_chk	(	char *	dest,
		rsize_t	dmax,
		char	c,
		char **	firstp,
		const size_t	destbos
	)

◆ _strfirstdiff_s_chk()

EXTERN errno_t _strfirstdiff_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	resultp,
		const size_t	destbos
	)

◆ _strisalphanumeric_s_chk()

EXTERN bool _strisalphanumeric_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strisascii_s_chk()

EXTERN bool _strisascii_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strisdigit_s_chk()

EXTERN bool _strisdigit_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strishex_s_chk()

EXTERN bool _strishex_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strislowercase_s_chk()

EXTERN bool _strislowercase_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strismixedcase_s_chk()

EXTERN bool _strismixedcase_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strispassword_s_chk()

EXTERN bool _strispassword_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strisuppercase_s_chk()

EXTERN bool _strisuppercase_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strlastchar_s_chk()

EXTERN errno_t _strlastchar_s_chk	(	char *	dest,
		rsize_t	dmax,
		char	c,
		char **	lastp,
		const size_t	destbos
	)

◆ _strlastdiff_s_chk()

EXTERN errno_t _strlastdiff_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	resultp,
		const size_t	destbos
	)

◆ _strljustify_s_chk()

EXTERN errno_t _strljustify_s_chk	(	char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strnterminate_s_chk()

EXTERN rsize_t _strnterminate_s_chk	(	char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strpbrk_s_chk()

EXTERN errno_t _strpbrk_s_chk	(	char *	dest,
		rsize_t	dmax,
		char *	src,
		rsize_t	slen,
		char **	firstp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ BOS_NULL() [6/11]

EXTERN errno_t slen BOS_NULL ( firstp )

◆ _strfirstsame_s_chk()

EXTERN errno_t _strfirstsame_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	resultp,
		const size_t	destbos
	)

◆ _strlastsame_s_chk()

EXTERN errno_t _strlastsame_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	resultp,
		const size_t	destbos
	)

◆ _strprefix_s_chk()

EXTERN errno_t _strprefix_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		const size_t	destbos
	)

◆ _strremovews_s_chk()

EXTERN errno_t _strremovews_s_chk	(	char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strspn_s_chk()

EXTERN errno_t _strspn_s_chk	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		rsize_t *	countp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _strstr_s_chk()

EXTERN errno_t _strstr_s_chk	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		char **	substringp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ BOS_NULL() [7/11]

EXTERN errno_t slen BOS_NULL ( substringp )

◆ _strchr_s_chk()

EXTERN errno_t _strchr_s_chk	(	const char *restrict	dest,
		rsize_t	dmax,
		const int	ch,
		char **restrict	resultp,
		const size_t	destbos
	)

◆ BOS_NULL() [8/11]

EXTERN errno_t smax BOS_NULL ( resultp )

◆ _strrchr_s_chk()

EXTERN errno_t _strrchr_s_chk	(	const char *restrict	dest,
		rsize_t	dmax,
		const int	ch,
		char **restrict	resultp,
		const size_t	destbos
	)

◆ _strtolowercase_s_chk()

EXTERN errno_t _strtolowercase_s_chk	(	char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strtouppercase_s_chk()

EXTERN errno_t _strtouppercase_s_chk	(	char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strzero_s_chk()

EXTERN errno_t _strzero_s_chk	(	char *	dest,
		rsize_t	dmax,
		const size_t	destbos
	)

◆ _strcoll_s_chk()

EXTERN errno_t _strcoll_s_chk	(	const char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		int *	resultp,
		const size_t	destbos
	)

◆ _strset_s_chk()

EXTERN errno_t _strset_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		int	value,
		const size_t	destbos
	)

◆ _strnset_s_chk()

EXTERN errno_t _strnset_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		int	value,
		rsize_t	n,
		const size_t	destbos
	)

◆ VAL_OVR2() [1/2]

EXTERN errno_t n VAL_OVR2	(	value	,
		255
	)

◆ _mbstowcs_s_chk()

EXTERN errno_t _mbstowcs_s_chk	(	size_t *restrict	retvalp,
		wchar_t *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	len,
		const size_t	destbos
	)		&&

◆ BOS_ATTR() [3/6]

EXTERN errno_t empty dmax BOS_ATTR	(	!	_BOS_NULLdest) &&_BOSW_OVR(dest, dmax,
		"dest overflow"
	)		&& == *srcp

◆ BOS_CHK2()

EXTERN errno_t empty dmax dest overlap BOS_CHK2	(	src	,
		len
	)

◆ _mbsrtowcs_s_chk()

EXTERN errno_t _mbsrtowcs_s_chk	(	size_t *restrict	retvalp,
		wchar_t *restrict	dest,
		rsize_t	dmax,
		const char **restrict	srcp,
		rsize_t	len,
		mbstate_t *restrict	ps,
		const size_t	destbos
	)		&&

◆ BOS_ATTR() [4/6]

EXTERN errno_t len BOS_ATTR	(	dmax &&	len,
		dmax	,
		"len	overflow,
		dmax"
	)

◆ _wcsrtombs_s_chk()

EXTERN errno_t _wcsrtombs_s_chk	(	size_t *restrict	retvalp,
		char *restrict	dest,
		rsize_t	dmax,
		const wchar_t **restrict	srcp,
		rsize_t	len,
		mbstate_t *restrict	ps,
		const size_t	destbos
	)		&&

◆ BOS_ATTR() [5/6]

EXTERN errno_t empty dmax BOS_ATTR	(	!	_BOS_NULLdest) &&_BOS_OVR(dest, dmax,
		"dest overflow"
	)		&&

◆ BOS_NULL() [9/11]

EXTERN errno_t empty dmax dest overlap BOS_NULL ( srcp )

◆ _wcstombs_s_chk()

EXTERN errno_t _wcstombs_s_chk	(	size_t *restrict	retvalp,
		char *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	len,
		const size_t	destbos
	)

◆ _wcrtomb_s_chk()

EXTERN errno_t _wcrtomb_s_chk	(	size_t *restrict	retvalp,
		char *restrict	dest,
		rsize_t	dmax,
		wchar_t	wc,
		mbstate_t *restrict	ps,
		const size_t	destbos
	)

◆ _wctomb_s_chk()

EXTERN errno_t _wctomb_s_chk	(	int *restrict	retvalp,
		char *restrict	dest,
		rsize_t	dmax,
		wchar_t	wc,
		const size_t	destbos
	)		&&

◆ VAL_OVR2() [2/2]

EXTERN errno_t dest overflow or empty VAL_OVR2	(	wc	,
		0x10ffff
	)

◆ _wcsnlen_s_chk()

EXTERN size_t _wcsnlen_s_chk	(	const wchar_t *	str,
		size_t	smax,
		size_t	srcbos
	)

◆ _wcscpy_s_chk()

EXTERN errno_t _wcscpy_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		const size_t	destbos
	)

◆ _wcsncpy_s_chk()

EXTERN errno_t _wcsncpy_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	slen,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcscat_s_chk()

EXTERN errno_t _wcscat_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		const size_t	destbos
	)

◆ _wcsncat_s_chk()

EXTERN errno_t _wcsncat_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	slen,
		const size_t	destbos,
		const size_t	srcbos
	)		&&

◆ BOS_ATTR() [6/6]

EXTERN errno_t dmax empty dest or dmax BOS_ATTR	(	slen &&	_BOSW_OVR(src, slen)\|\|_BOS_NULL(src),
		"src overflow or empty"
	)

◆ _wcstok_s_chk()

EXTERN wchar_t * _wcstok_s_chk	(	wchar_t *restrict	dest,
		rsize_t *restrict	dmaxp,
		const wchar_t *restrict	delim,
		wchar_t **restrict	ptr,
		const size_t	destbos
	)

◆ BOS_NULL() [10/11]

EXTERN wchar_t *dmaxp BOS_NULL ( delim )

◆ _swprintf_s_chk()

EXTERN int _swprintf_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const wchar_t *restrict	fmt,
			...
	)

◆ BOSW_CHK()

EXTERN int BOSW_CHK ( dest )

◆ _vswprintf_s_chk()

EXTERN int _vswprintf_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const wchar_t *restrict	fmt,
		va_list	ap
	)

◆ snwprintf_s()

EXTERN int snwprintf_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	fmt,
			...
	)

◆ _vsnwprintf_s_chk()

EXTERN int _vsnwprintf_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const wchar_t *restrict	fmt,
		va_list	ap
	)

◆ wprintf_s()

EXTERN int wprintf_s	(	const wchar_t *restrict	fmt,
			...
	)

◆ vwprintf_s()

EXTERN int vwprintf_s	(	const wchar_t *restrict	fmt,
		va_list	ap
	)

The vwprintf_s function prints formatted output to stdout as wide string.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.1.11 The vwprintf_s function (p: 636) http://en.cppreference.com/w/c/io/vfwprintf

Parameters

[in]	fmt	format-control wide string.
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer (not yet); No encoding error shall occur.

Returns: On success the total number of wide characters written is returned.; On failure a negative number is returned, and possibly errno set to EINVAL or EOVERFLOW.

Return values

-ESNULLP	when fmt is NULL pointer
-EINVAL	when fmt contains n
-1	some other error. errno: EINVAL or EOVERFLOW

See also: vwfprintf_s(), wprintf_s()

◆ fwprintf_s()

EXTERN int fwprintf_s	(	FILE *restrict	stream,
		const wchar_t *restrict	fmt,
			...
	)

◆ vfwprintf_s()

EXTERN int vfwprintf_s	(	FILE *restrict	stream,
		const wchar_t *restrict	fmt,
		va_list	ap
	)

The vfwprintf_s function prints formatted output to a wide stream.

Note: POSIX specifies that errno is set on error. However, the safeclib extended ES* errors do not set errno, only when the underlying system vfwprintf call fails, errno is set.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.1.6 The vfwprintf_s function (p: 632) http://en.cppreference.com/w/c/io/vfwprintf

Parameters

[in]	stream	output wide stream to write to
[in]	fmt	format-control wide string.
[in]	ap	optional arguments

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer (not yet); No encoding error shall occur.

Returns: On success the total number of wide characters written is returned.; On failure a negative number is returned, and possibly errno set to EINVAL or EOVERFLOW.

Return values

-ESNULLP	when stream or fmt is a NULL pointer
-EINVAL	when fmt contains n
-1	some other error. errno: EINVAL or EOVERFLOW

See also: vfwscanf_s(), fwprintf_s()

◆ swscanf_s()

EXTERN int swscanf_s	(	const wchar_t *restrict	src,
		const wchar_t *restrict	fmt,
			...
	)

◆ BOS_NULL() [11/11]

EXTERN int BOS_NULL ( src )

◆ vswscanf_s()

EXTERN int vswscanf_s	(	const wchar_t *restrict	src,
		const wchar_t *restrict	fmt,
		va_list	ap
	)

The vswscanf_s function reads a formatted wide string.

Reaching the end of the string is equivalent to reaching the end-of-file condition for fwscanf.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.1.10 The vswscanf_s function (p: 635-636) http://en.cppreference.com/w/c/io/vfwscanf

Parameters

[in]	src	pointer to a null-terminated wide string to read from
[in]	fmt	format-control wide string.
[in]	ap	arguments to write to

Precondition: Neither src nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function. (not yet)

Warning: The current implementation just does some basic argument checks and then calls the native vsscanf() libc function. Thus the s null pointer check and the two-arg versions of c, s, and %[ are not yet implemented.

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error

See also: vswscanf_s(), snwprintf_s(), vsnprintf_s()

◆ wscanf_s()

EXTERN int wscanf_s	(	const wchar_t *restrict	fmt,
			...
	)

◆ vwscanf_s()

EXTERN int vwscanf_s	(	const wchar_t *restrict	fmt,
		va_list	ap
	)

The vwscanf_s function reads a formatted wide string from stdin.

Reaching the end of the stdin buffer is equivalent to reaching the end-of-file condition for vwscanf.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.1.12 The vwscanf_s function (p: 637) http://en.cppreference.com/w/c/io/vwscanf

Parameters

[in]	fmt	format-control wide string.
[out]	ap	arguments to write to

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function. (not yet)

Warning: The current implementation just does some basic argument checks and then calls the native vsscanf() libc function. Thus the s null pointer check and the two-arg versions of c, s, and %[ are not yet implemented.

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

int	>0 on success, the number of arguments assigned
EOF	on error

See also: vswscanf_s(), wscanf_s(), vvwscanf_s(), vfwprintf_s()

◆ fwscanf_s()

EXTERN int fwscanf_s	(	FILE *restrict	stream,
		const wchar_t *restrict	fmt,
			...
	)

◆ vfwscanf_s()

EXTERN int vfwscanf_s	(	FILE *restrict	stream,
		const wchar_t *restrict	fmt,
		va_list	ap
	)

The vfwscanf_s function reads a formatted wide string.

Reaching the end of the string is equivalent to reaching the end-of-file condition for fwscanf.

Remarks

SPECIFIED IN

C11 standard (ISO/IEC 9899:2011): K.3.9.1.7 The vfwscanf_s function (p: 632-633) http://en.cppreference.com/w/c/io/vfwscanf

Parameters

[in]	stream	pointer to a FILE stream to read from
[in]	fmt	format-control wide string.
[out]	ap	arguments to write to

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n; None of the arguments corresponding to s is a null pointer. (not yet); No encoding error shall occur.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function. (not yet)

Warning: The current implementation just does some basic argument checks and then calls the native vsscanf() libc function. Thus the s null pointer check and the two-arg versions of c, s, and %[ are not yet implemented.

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Todo:: When an argument is not assigned to, it should be zero'd (not yet).

Return values

int	>0 on success, the number of arguments assigned
EOF	on error

See also: vswscanf_s(), fwscanf_s(), vfwprintf_s()

◆ _wcsstr_s_chk()

EXTERN errno_t _wcsstr_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	slen,
		wchar_t **restrict	substringp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcscmp_s_chk()

EXTERN errno_t _wcscmp_s_chk	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcsncmp_s_chk()

EXTERN errno_t _wcsncmp_s_chk	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		rsize_t	count,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcsicmp_s_chk()

EXTERN errno_t _wcsicmp_s_chk	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcsnatcmp_s_chk()

EXTERN errno_t _wcsnatcmp_s_chk	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		const int	fold_case,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcsset_s_chk()

EXTERN errno_t _wcsset_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t	value,
		const size_t	destbos
	)

◆ _wcsnset_s_chk()

EXTERN errno_t _wcsnset_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t	value,
		size_t	n,
		const size_t	destbos
	)

◆ _wcscoll_s_chk()

EXTERN errno_t _wcscoll_s_chk	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos
	)

◆ _wcslwr_s_chk()

EXTERN errno_t _wcslwr_s_chk	(	wchar_t *restrict	src,
		rsize_t	slen,
		const size_t	srcbos
	)

◆ _wcsupr_s_chk()

EXTERN errno_t _wcsupr_s_chk	(	wchar_t *restrict	src,
		rsize_t	slen,
		const size_t	srcbos
	)

◆ iswfc()

EXTERN int iswfc ( const uint32_t wc )

◆ _towfc_s_chk()

EXTERN int EXTERN int _towfc_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const uint32_t	src,
		const size_t	destbos
	)

Variable Documentation

◆ dmax

EXTERN errno_t dmax

◆ slen

EXTERN errno_t slen

◆ smax

EXTERN size_t smax

◆ dest

EXTERN errno_t empty* dest

◆ !dmax

EXTERN errno_t dmax !dmax

Macros

Functions

Variables

Macro Definition Documentation

◆ EXTERN

◆ SAFECLIB_UNICODE_VERSION

◆ RSIZE_MIN_STR

◆ RSIZE_MAX_WSTR

◆ SAFE_STR_MIN_LOWERCASE

◆ SAFE_STR_MIN_UPPERCASE

◆ SAFE_STR_MIN_NUMBERS

◆ SAFE_STR_MIN_SPECIALS

◆ SAFE_STR_PASSWORD_MIN_LENGTH

◆ SAFE_STR_PASSWORD_MAX_LENGTH

◆ sl_default_handler

◆ strcat_s

◆ strcpy_s

◆ strncat_s

◆ strncpy_s

◆ strnlen_s

◆ strtok_s

◆ vsprintf_s

◆ vsnprintf_s

◆ strerror_s

◆ stpcpy_s

◆ stpncpy_s

◆ strcmp_s

◆ strcasecmp_s

◆ strnatcmp_s

◆ strnatcasecmp_s

◆ strcasestr_s

◆ strcmpfld_s

◆ strcpyfld_s

◆ strcpyfldin_s

◆ strcpyfldout_s

◆ strcspn_s

◆ strfirstchar_s

◆ strfirstdiff_s

◆ strisalphanumeric_s

◆ strisascii_s

◆ strisdigit_s

◆ strishex_s

◆ strislowercase_s

◆ strismixedcase_s

◆ strispassword_s

◆ strisuppercase_s

◆ strlastchar_s

◆ strlastdiff_s

◆ strljustify_s

◆ strnterminate_s

◆ strpbrk_s

◆ strfirstsame_s

◆ strlastsame_s

◆ strprefix_s

◆ strremovews_s

◆ strspn_s

◆ strstr_s

◆ strchr_s

◆ strrchr_s

◆ strtolowercase_s

◆ strtouppercase_s

◆ strlwr_s

◆ strupr_s

◆ strzero_s

◆ strcoll_s

◆ strset_s

◆ strnset_s

◆ mbstowcs_s

◆ mbsrtowcs_s

◆ wcsrtombs_s

◆ wcstombs_s

◆ wcrtomb_s

◆ wctomb_s

◆ wcsnlen_s

◆ wcscpy_s

◆ wcsncpy_s

◆ wcscat_s

◆ wcsncat_s

◆ wcstok_s

◆ swprintf_s