safe_str_lib.h File Reference

#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:

Macros
#define	EXTERN   extern
#define	RSIZE_MIN_STR   (1)
	The shortest string is a null string!! More...
#define	RSIZE_MAX_WSTR   (RSIZE_MAX_STR / sizeof(wchar_t))
	wide chars More...
#define	SAFE_STR_MIN_LOWERCASE   (2)
	The makeup of a password. More...
#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 null character) to the end of the string pointed to by dest. The initial character from src overwrites the null character at the end of dest. More...
#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 null character) into the array pointed to by dest. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null 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. More...
#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 null character) to the end of the string pointed to by dest. The initial character from src overwrites the null character at the end of dest. More...
#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 null character are not copied) from the array pointed to by src to the array pointed to by dest. If no null character was copied from src, then dest[n] is set to a null character, thus guaranteeing null termination. More...
#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. More...
#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. More...
#define	sprintf_s(dest, dmax, ...)   _sprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)
	The sprintf_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. More...
#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. More...
#define	snprintf_s(dest, dmax, ...)   _snprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)
	The truncating snprintf_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. It is guaranteed that dest will be null-terminated. More...
#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. More...
#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 "...". More...
#define	strcmp_s(dest, dmax, src, resultp)   _strcmp_s_chk(dest, dmax, src, resultp, BOS(dest), BOS(src))
	Compares string src to string dest. More...
#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. More...
#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. More...
#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. The comparison is case insensitive. More...
#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. More...
#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. 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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#define	strispassword_s(dest, dmax)   _strispassword_s_chk(dest, dmax, BOS(dest))
	This function validates the make-up of a password string. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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). More...
#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. More...
#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. More...
#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 null character is considered to be a part of the string and can be found when searching for '\0'. More...
#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 null 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. More...
#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. More...
#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. More...
#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. 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 null character (if any) written in the array of dmax characters pointed to by dest are nulled. More...
#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. More...
#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 null character (if any) written in the array of dmax characters pointed to by dest are nulled. More...
#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 null character (if any) written in the array of dmax characters pointed to by dest are nulled. More...
#define	mbstowcs_s(retvalp, dest, dmax, src, len)   _mbstowcs_s_chk(retvalp, dest, dmax, src, len, BOS(dest))
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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-null terminated strings. More...
#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 null character) into the array pointed to by dest. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by wcscpy_s in the array of dmax characters pointed to by dest are nulled when wcscpy_s returns. More...
#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 null character) into the wide string pointed to by dest. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by wcsncpy_s in the array of dmax characters pointed to by dest are nulled when wcsncpy_s returns. More...
#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 null character) to the end of the wide string pointed to by dest. The initial wide character from src overwrites the null character at the end of dest. More...
#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. More...
#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. More...
#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	snwprintf_s(dest, dmax, ...)   _snwprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)
	The truncating snwprintf_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. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by snwprintf_s in the array of dmax wide characters pointed to by dest are nulled when snwprintf_s returns. More...
#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 null character. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by vsnwprintf_s in the array of dmax wide characters pointed to by dest are nulled when vsnwprintf_s returns. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. The longest run of numbers wins over alpha chars. More...
#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 null character (if any) written in the array of dmax wide characters pointed to by dest are nulled. More...
#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 null character (if any) written in the array of dmax wide characters pointed to by dest are nulled. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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. More...
#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, latest 10.0. The conversion stops at the first null or after dmax characters. More...
#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, latest 10.0. The conversion stops at the first null or after dmax characters. More...
#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, latest 10.0. The conversion stops at the first null or after dmax characters. More...
#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, latest 10.0. The conversion stops at the first null or after dmax characters. More...

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. More...
EXTERN void	ignore_handler_s (const char *restrict msg, void *restrict ptr, errno_t error)
	This function simply returns to the caller. More...
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. More...
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_chk (char *restrict dest, const rsize_t dmax, const size_t destbos, 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_chk (char *restrict dest, rsize_t dmax, const size_t destbos, 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. More...
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. More...
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. More...
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. More...
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. More...
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(). More...
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_chk (wchar_t *restrict dest, rsize_t dmax, const size_t destbos, const wchar_t *restrict fmt,...) __attribute_format_wprintf(4
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. More...
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. More...
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. More...
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. More...
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. More...
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

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 null character) to the end of the string pointed to by dest. The initial character from src overwrites the null character at the end of dest.

All elements following the terminating null character (if any) written by strcat_s in the array of dmax characters pointed to by dest take unspecified 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 null 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 null character) into the array pointed to by dest. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null 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 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 != 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 null character) to the end of the string pointed to by dest. The initial character from src overwrites the null character at the end of dest.

All elements following the terminating null character (if any) written by strncat_s in the array of dmax characters pointed to by dest take unspecified 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 null 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 null 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 null character are not copied) from the array pointed to by src to the array pointed to by dest. If no null character was copied from src, then dest[n] is set to a null character, thus guaranteeing null termination.

All elements following the terminating null character (if any) written by strncpy_s in the array of dmax characters pointed to by dest take unspecified values when strncpy_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.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 nulls dest.

Return values

EOK	successful operation, when slen == 0 or the characters in src were copied to dest and the result is null 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 null character. If str is NULL, then strnlen_s returns 0. Otherwise, the strnlen_s function returns the number of characters that precede the terminating null character. If there is no null 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 reflect the number of elements that remain in relation to ptr. Subsequent calls in the sequence have a null first argument and the objects pointed to by dmax and ptr are required to have the values stored by the previous call in the sequence, which are then updated. The separator string pointed to by delim may be different from call to call.

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

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

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

delim uses a STRTOK_DELIM_MAX_LEN of 16.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.7.3.1 The strtok_s function (p: 620-621) http://en.cppreference.com/w/c/string/byte/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 );
 }

sprintf_s

#define sprintf_s	(		dest,
			dmax,
			...
	)		_sprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)

The sprintf_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.6 The sprintf_s function (p: 595-596) http://en.cppreference.com/w/c/io/fprintf

Parameters

[out]	dest	storage location for output buffer.
[in]	dmax	maximum number of characters to store in buffer.
[in]	fmt	format-control string.
[in]	...	optional arguments

Precondition

fmt shall not be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR or the sizeof(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.

Returns

If no runtime-constraint violation occurred, the sprintf_s function returns the number of characters written in the array, not counting the terminating null character. If an error occurred, sprintf_s returns a negative value. (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 -ESNULLP when dest is NULL and dmax > 0 -ESZEROL when dmax = 0 and dest is not NULL -ESLEMAX when dmax > RSIZE_MAX_STR or dmax > size of dest -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
-1	if an encoding error or a runtime constraint violation in the libc function vsnprintf occured.

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. sprintf_s does not set errno.

See also

vsprintf_s(), snprintf_s()

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 -ESNULLP when dest is NULL and dmax > 0 -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
-1	if an encoding error or a runtime constraint violation in the libc function vsnprintf occured.

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()

snprintf_s

#define snprintf_s	(		dest,
			dmax,
			...
	)		_snprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)

The truncating snprintf_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. 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.6 The snprintf_s function (p: 594-595) http://en.cppreference.com/w/c/io/fprintf

Parameters

[out]	dest	pointer to string that will be written into.
[in]	dmax	restricted maximum length of dest
[in]	fmt	format-control string.
[in]	...	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 size of dest.

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

If the buffer dest is too small for the formatted text, including the terminating null, then the buffer is truncated and null terminated.

Return values

Number	of characters not including the terminating null character, or a negative error number if a runtime constraints violation or an encoding error occurred.
-ESNULLP	when dest/fmt is NULL pointer
-ESZEROL	when dmax == 0
-ESLEMAX	when dmax > RSIZE_MAX_STR
-EOVERFLOW	when dmax > size of dest
-EINVAL	when fmt contains n

See also

sprintf_s(), vsnprintf_s(), snwprintf_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. (not yet)

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 null terminated.

Return values

-ESNULLP	when dest/fmt is NULL pointer
-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 null 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()

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 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 != 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 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)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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))

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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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 null 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-null 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 null

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 null).

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 null 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 null character. If there is no null 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 null character) into the array pointed to by dest. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null 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 null 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 null character) into the wide string pointed to by dest. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null 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 null 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 null character) to the end of the wide string pointed to by dest. The initial wide character from src overwrites the null 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 unspecified 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 null 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 null 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 unspecified 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 null 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 null 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 reflect 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 null character, which terminates the current token.

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

delim uses a STRTOK_DELIM_MAX_LEN of 16.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.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)

snwprintf_s

#define snwprintf_s	(		dest,
			dmax,
			...
	)		_snwprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)

The truncating snwprintf_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. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by snwprintf_s in the array of dmax wide characters pointed to by dest are nulled when snwprintf_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 snwprintf_s function (p: 634-635) http://en.cppreference.com/w/c/io/fwprintf
• only included in safeclib with –enable-unsafe

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]	...	optional arguments

Precondition

Neither dest nor fmt 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(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 snwprintf_s, swprintf_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(), swprintf_s(), vsnprintf_s()

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 null character. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null 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 null 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 null 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 null 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, latest 10.0. 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, latest 10.0. 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, latest 10.0. 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
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, latest 10.0. 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:

1. A pointer to a character string describing the runtime-constraint violation.
2. A null pointer or a pointer to an implementation defined object.
3. 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()

_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_chk()

EXTERN int _sprintf_s_chk	(	char *restrict	dest,
		const rsize_t	dmax,
		const size_t	destbos,
		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_chk()

EXTERN int _snprintf_s_chk	(	char *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		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/10]

EXTERN int BOS_NULL

(

buffer

)

fscanf_s()

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

BOS_NULL() [2/10]

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/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()

_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() [3/10]

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() [4/10]

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() [5/10]

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() [6/10]

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() [7/10]

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() [8/10]

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() [9/10]

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_chk()

EXTERN int _snwprintf_s_chk	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		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() [10/10]

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