safe_str_lib.h File Reference

#include "safe_config.h"
#include "safe_lib_errno.h"
#include "safe_types.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 )
#define	RSIZE_MAX_WSTR   ( RSIZE_MAX_STR/sizeof(wchar_t) )
#define	SAFE_STR_MIN_LOWERCASE   ( 2 )
#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	strlwr_s(str, slen)   strtolowercase_s((str), (slen))
#define	strupr_s(str, slen)   strtouppercase_s((str), (slen))

Typedefs
typedef enum wcsnorm_mode	wcsnorm_mode_t

Enumerations
enum	wcsnorm_mode {   WCSNORM_NFD = 0, WCSNORM_NFC = 1, WCSNORM_FCD = 2, WCSNORM_FCC = 3,   WCSNORM_NFKD = 4, WCSNORM_NFKC = 5 }

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 (char *restrict dest, rsize_t dmax, const char *restrict src)
	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. More...
EXTERN errno_t	strcpy_s (char *restrict dest, rsize_t dmax, const char *restrict src)
	The strcpy_s function copies the string pointed to by src (including the terminating null character) into the array pointed to by dest. More...
EXTERN errno_t	strncat_s (char *restrict dest, rsize_t dmax, const char *restrict src, rsize_t slen)
	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. More...
EXTERN errno_t	strncpy_s (char *restrict dest, rsize_t dmax, const char *restrict src, rsize_t slen)
	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. More...
EXTERN rsize_t	strnlen_s (const char *s, rsize_t smax)
	The strnlen_s function computes the length of the string pointed to by dest. More...
EXTERN char *	strtok_s (char *restrict s1, rsize_t *restrict s1max, const char *restrict src, char **restrict ptr)
	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. More...
EXTERN int	sprintf_s (char *restrict dest, rsize_t dmax, const char *restrict fmt,...)
	The sprintf_s function composes a string with same test that would be printed if format was used on printf. More...
EXTERN int	vsprintf_s (char *restrict dest, rsize_t dmax, const char *restrict fmt, va_list ap)
	The vsprintf_s function composes a string with same test that would be printed if format was used on printf. More...
EXTERN int	snprintf_s (char *restrict dest, rsize_t dmax, const char *restrict fmt,...)
	The truncating snprintf_s function composes a string with same test that would be printed if format was used on printf. More...
EXTERN int	vsnprintf_s (char *restrict dest, rsize_t dmax, const char *restrict fmt, va_list ap)
	The truncating vsnprintf_s function composes a string with same test that would be printed if format was used on printf. More...
EXTERN int	sscanf_s (const char *restrict buffer, const char *restrict fmt,...)
	The sscanf_s function reads a formatted string, and writes to a list of arguments. More...
EXTERN int	fscanf_s (FILE *restrict stream, const char *restrict format,...)
	The fscanf_s function reads a formatted string from a buffered FILE stream, and writes to a list of arguments. More...
EXTERN int	scanf_s (const char *restrict format,...)
	The scanf_s function reads a formatted string from stdin, and writes to a list of arguments. More...
EXTERN int	vscanf_s (const char *restrict format, va_list vlist)
	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 format, va_list vlist)
	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 buffer, const char *restrict format, va_list vlist)
	The vsscanf_s function reads a formatted string, and writes to a list of arguments. More...
EXTERN int	printf_s (const char *restrict format,...)
	The printf_s function composes a string via the format string and writes it to a FILE buffer. More...
EXTERN int	fprintf_s (FILE *restrict stream, const char *restrict format,...)
	The fprintf_s function composes a string via the format string and writes it to a FILE buffer. More...
EXTERN int	vprintf_s (const char *restrict format, va_list arg)
	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 format, va_list arg)
	The vfprintf_s function composes a string via the format string and writes it to a FILE buffer. More...
EXTERN errno_t	strerror_s (char *dest, rsize_t dmax, errno_t errnum)
	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(). More...
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 (const char *dest, rsize_t dmax, const char *src, int *indicator)
	Compares string src to string dest. More...
EXTERN errno_t	strcasecmp_s (const char *dest, rsize_t dmax, const char *src, int *indicator)
	Case insensitive string comparison by converting to uppercase prior to the compare. More...
EXTERN errno_t	strcasestr_s (char *dest, rsize_t dmax, const char *src, rsize_t slen, char **substring)
	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. More...
EXTERN errno_t	strcmpfld_s (const char *dest, rsize_t dmax, const char *src, int *indicator)
	Compares the character array pointed to by src to the character array pointed to by dest for dmax characters. More...
EXTERN errno_t	strcpyfld_s (char *dest, rsize_t dmax, const char *src, rsize_t slen)
	The strcpyfld_s function copies slen characters from the character array pointed to by src into the character array pointed to by dest. More...
EXTERN errno_t	strcpyfldin_s (char *dest, rsize_t dmax, const char *src, rsize_t slen)
	The strcpyfldin_s function copies at most slen characters from the null terminated string pointed to by src into the fixed character array pointed to by dest. More...
EXTERN errno_t	strcpyfldout_s (char *dest, rsize_t dmax, const char *src, rsize_t slen)
	The strcpyfldout_s function copies slen characters from the character array pointed to by src into the string pointed to by dest. More...
EXTERN errno_t	strcspn_s (const char *dest, rsize_t dmax, const char *src, rsize_t slen, rsize_t *count)
	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. More...
EXTERN errno_t	strfirstchar_s (char *dest, rsize_t dmax, char c, char **first)
	This function returns a pointer to the first occurrence of character c in dest. More...
EXTERN errno_t	strfirstdiff_s (const char *dest, rsize_t dmax, const char *src, rsize_t *index)
	Returns the index of the first character that is different between dest and src. More...
EXTERN bool	strisalphanumeric_s (const char *str, rsize_t slen)
	This function checks if the entire string contains alphanumerics. More...
EXTERN bool	strisascii_s (const char *str, rsize_t slen)
	This function checks if the entire string contains ascii characters. More...
EXTERN bool	strisdigit_s (const char *str, rsize_t slen)
	This function checks that the entire string contains digits. More...
EXTERN bool	strishex_s (const char *str, rsize_t slen)
	This function checks that the entire string contains hex characters. More...
EXTERN bool	strislowercase_s (const char *str, rsize_t slen)
	This function checks if entire string is lowercase. More...
EXTERN bool	strismixedcase_s (const char *str, rsize_t slen)
	This function checks that the entire string is mixed case. More...
EXTERN bool	strispassword_s (const char *str, rsize_t slen)
	This function validates the make-up of a password string. More...
EXTERN bool	strisuppercase_s (const char *str, rsize_t slen)
	This function checks if entire string is uppercase The scanning stops at the first null or after dmax characters. More...
EXTERN errno_t	strlastchar_s (char *str, rsize_t smax, char c, char **first)
	Returns a pointer to the last occurrence of character c in dest. More...
EXTERN errno_t	strlastdiff_s (const char *dest, rsize_t dmax, const char *src, rsize_t *index)
	Returns the index of the last character that is different between dest and src. More...
EXTERN errno_t	strljustify_s (char *dest, rsize_t dmax)
	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...
EXTERN rsize_t	strnterminate_s (char *s, rsize_t smax)
	The strnterminate_s function will terminate the string if a null is not encountered before dmax characters. More...
EXTERN errno_t	strpbrk_s (char *dest, rsize_t dmax, char *src, rsize_t slen, char **first)
	Returns a pointer, first, to the first ocurrence of any character in src which is contained in dest. More...
EXTERN errno_t	strfirstsame_s (const char *dest, rsize_t dmax, const char *src, rsize_t *index)
	Returns the index of the first character that is the same between dest and src. More...
EXTERN errno_t	strlastsame_s (const char *dest, rsize_t dmax, const char *src, rsize_t *index)
	Returns the index of the last character that is the same between dest and src. More...
EXTERN errno_t	strprefix_s (const char *dest, rsize_t dmax, const char *src)
	Determines if the prefix pointed to by src is at the beginning of string pointed to by dest. More...
EXTERN errno_t	strremovews_s (char *dest, rsize_t dmax)
	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...
EXTERN errno_t	strspn_s (const char *dest, rsize_t dmax, const char *src, rsize_t slen, rsize_t *count)
	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...
EXTERN errno_t	strstr_s (char *dest, rsize_t dmax, const char *src, rsize_t slen, char **substring)
	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...
EXTERN errno_t	strchr_s (const char *restrict dest, rsize_t dmax, const int ch, char **result)
	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). More...
EXTERN errno_t	strrchr_s (const char *restrict dest, rsize_t dmax, const int ch, char **result)
	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). More...
EXTERN errno_t	strtolowercase_s (char *restrict str, rsize_t slen)
	Scans the string converting uppercase characters to lowercase, leaving all other characters unchanged. More...
EXTERN errno_t	strtouppercase_s (char *str, rsize_t slen)
	Scans the string converting lowercase characters to uppercase, leaving all other characters unchanged. More...
EXTERN errno_t	strzero_s (char *dest, rsize_t dmax)
	Nulls maximal dmax characters of dest. More...
EXTERN errno_t	strcoll_s (const char *restrict dest, rsize_t dmax, const char *restrict src, int *indicator)
	Compares two null-terminated byte strings according to the current locale as defined by the LC_COLLATE category. More...
EXTERN errno_t	strset_s (char *restrict dest, rsize_t dmax, int value)
	Sets maximal dmax characters of dest to a character value, but not the final NULL character. More...
EXTERN errno_t	strnset_s (char *restrict dest, rsize_t dmax, int value, rsize_t n)
	Sets maximal n characters of dest to a character value, but not the final NULL character. More...
EXTERN errno_t	mbstowcs_s (size_t *restrict retval, wchar_t *restrict dest, rsize_t dmax, const char *restrict src, rsize_t len)
EXTERN errno_t	mbsrtowcs_s (size_t *restrict retval, wchar_t *restrict dest, rsize_t dmax, const char **restrict src, rsize_t len, mbstate_t *restrict ps)
	Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer. More...
EXTERN errno_t	wcsrtombs_s (size_t *restrict retval, char *restrict dest, rsize_t dmax, const wchar_t **restrict src, rsize_t len, mbstate_t *restrict ps)
	Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer. More...
EXTERN errno_t	wcstombs_s (size_t *restrict retval, char *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t len)
	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. More...
EXTERN errno_t	wcrtomb_s (size_t *restrict retval, char *restrict dest, rsize_t dmax, wchar_t wc, mbstate_t *restrict ps)
	Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer. More...
EXTERN errno_t	wctomb_s (int *restrict retval, char *restrict dest, rsize_t dmax, wchar_t wc)
	The wctomb_s function converts a single wide character to its narrow multibyte representation from the current LC_CTYPE locale. More...
EXTERN size_t	wcsnlen_s (const wchar_t *dest, size_t dmax)
	The wcsnlen_s function computes the length of the wide string pointed to by dest. More...
EXTERN errno_t	wcscpy_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src)
	The wcscpy_s function copies the string pointed to by src (including the terminating null character) into the array pointed to by dest. More...
EXTERN errno_t	wcsncpy_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t slen)
	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. More...
EXTERN errno_t	wcscat_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src)
	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. More...
EXTERN errno_t	wcsncat_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t slen)
	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. More...
EXTERN wchar_t *	wcstok_s (wchar_t *restrict dest, rsize_t *restrict dmax, const wchar_t *restrict delim, wchar_t **restrict ptr)
	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. More...
EXTERN int	swprintf_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict fmt,...)
	The swprintf_s function composes a wide string with same test that would be printed if format was used on wprintf. More...
EXTERN int	vswprintf_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict fmt, va_list ap)
	The vswprintf_s function composes a wide string with same test that would be printed if format was used on wprintf. More...
EXTERN int	snwprintf_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict fmt,...)
	The truncating snwprintf_s function composes a wide string with same test that would be printed if format was used on wprintf. More...
EXTERN int	vsnwprintf_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict fmt, va_list ap)
	The truncating vsnwprintf_s function composes a wide string with same test that would be printed if format was used on wprintf. More...
EXTERN int	wprintf_s (const wchar_t *restrict fmt,...)
	The wprintf_s function prints formatted output to stdout as wide string. More...
EXTERN int	vwprintf_s (const wchar_t *restrict fmt, va_list ap)
	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,...)
	The fwprintf_s function prints formatted output to a wide stream. More...
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. More...
EXTERN int	swscanf_s (const wchar_t *restrict buffer, const wchar_t *restrict fmt,...)
	The swscanf_s function reads a formatted wide string. More...
EXTERN int	vswscanf_s (const wchar_t *restrict buffer, const wchar_t *restrict fmt, va_list ap)
	The vswscanf_s function reads a formatted wide string. More...
EXTERN int	wscanf_s (const wchar_t *restrict fmt,...)
	The wscanf_s function reads a formatted wide string from stdin. More...
EXTERN int	vwscanf_s (const wchar_t *restrict fmt, va_list ap)
	The vwscanf_s function reads a formatted wide string from stdin. More...
EXTERN int	fwscanf_s (FILE *restrict stream, const wchar_t *restrict fmt,...)
	The fwscanf_s function reads a formatted wide string. More...
EXTERN int	vfwscanf_s (FILE *restrict stream, const wchar_t *restrict fmt, va_list ap)
	The vfwscanf_s function reads a formatted wide string. More...
EXTERN errno_t	wcsstr_s (wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t slen, wchar_t **restrict substring)
	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...
EXTERN errno_t	wcscmp_s (const wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t smax, int *diff)
	Compares wide string src to wide string dest. More...
EXTERN errno_t	wcsncmp_s (const wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t smax, rsize_t count, int *diff)
	Compares at most count wide characters of wide string src with wide string dest. More...
EXTERN errno_t	wcsicmp_s (const wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t smax, int *diff)
	Compares two wide strings case-folded, via wcsfc_s(), i.e. More...
EXTERN errno_t	wcsset_s (wchar_t *restrict dest, rsize_t dmax, wchar_t value)
	Sets maximal dmax wide characters of dest to a wide character value, but not the final NULL character. More...
EXTERN errno_t	wcsnset_s (wchar_t *restrict dest, rsize_t dmax, wchar_t value, size_t n)
	Sets maximal n wide characters of dest to a wide character value, but not the final NULL character. More...
EXTERN errno_t	wcscoll_s (const wchar_t *restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t smax, int *indicator)
	Compares two null-terminated wide strings according to the current locale as defined by the LC_COLLATE category. More...
EXTERN errno_t	wcslwr_s (wchar_t *restrict src, rsize_t slen)
	Scans the string converting uppercase characters to simple lowercase, leaving all other characters unchanged. More...
EXTERN errno_t	wcsupr_s (wchar_t *restrict src, rsize_t slen)
	Scans the string converting lowercase characters to uppercase, leaving all other characters unchanged. More...
EXTERN int	iswfc (wint_t wc)
EXTERN int	towfc_s (wchar_t *restrict dest, rsize_t dmax, const wint_t src)
	towfc_s() converts a wide character to fully fold-cased (lowercased with possible expansions), according to the Unicode 10.0 CaseFolding table. More...
EXTERN errno_t	wcsfc_s (wchar_t *restrict dest, rsize_t dmax, wchar_t *restrict src, rsize_t *restrict lenp)
	Converts the wide string via full case-folding NFD normalized to lowercase. More...
EXTERN errno_t	wcsnorm_decompose_s (wchar_t *restrict dest, rsize_t dmax, wchar_t *restrict src, rsize_t *restrict lenp, bool iscompat)
	Converts the wide string to the canonical NFD normalization, as defined in the latest Unicode standard, latest 10.0. More...
EXTERN errno_t	wcsnorm_reorder_s (wchar_t *restrict dest, rsize_t dmax, wchar_t *restrict src, rsize_t len)
	Reorder all decomposed sequences in a wide string to NFD, as defined in the latest Unicode standard, latest 10.0. More...
EXTERN errno_t	wcsnorm_compose_s (wchar_t *restrict dest, rsize_t dmax, wchar_t *restrict src, rsize_t *restrict lenp, bool iscontig)
	Combine all decomposed sequences in a wide string to NFC, as defined in the latest Unicode standard, latest 10.0. More...
EXTERN errno_t	wcsnorm_s (wchar_t *restrict dest, rsize_t dmax, wchar_t *restrict src, wcsnorm_mode_t mode, rsize_t *restrict lenp)
	Converts the wide string to the canonical NFC or NFD normalization, as defined in the latest Unicode standard, latest 10.0. More...

Macro Definition Documentation

EXTERN

#define EXTERN   extern

RSIZE_MIN_STR

#define RSIZE_MIN_STR   ( 1 )

RSIZE_MAX_WSTR

#define RSIZE_MAX_WSTR   ( RSIZE_MAX_STR/sizeof(wchar_t) )

SAFE_STR_MIN_LOWERCASE

#define SAFE_STR_MIN_LOWERCASE   ( 2 )

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

strlwr_s

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

strupr_s

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

Typedef Documentation

wcsnorm_mode_t

typedef enum wcsnorm_mode wcsnorm_mode_t

Enumeration Type Documentation

wcsnorm_mode

enum wcsnorm_mode

Enumerator
WCSNORM_NFD
WCSNORM_NFC
WCSNORM_FCD
WCSNORM_FCC
WCSNORM_NFKD
WCSNORM_NFKC

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

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

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 ofdest.

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 is cleared with NULL bytes.

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 not equal zero

dmax shall not be greater than RSIZE_MAX_STR

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.

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

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

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.

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 not be greater than RSIZE_MAX_STR.

dmax shall not equal zero.

dmax shall be greater than strnlen_s(src, dmax).

Copying shall not take place between objects that overlap.

Note

C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns

If there is a runtime-constraint violation, then if dest is not a null pointer and destmax is greater than zero and not greater than RSIZE_MAX_STR, 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
ESOVRLP	when strings overlap
ESNOSPC	when dest < src

See also

strcat_s(), strncat_s(), strncpy_s()

strncat_s()

EXTERN errno_t strncat_s	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	slen
	)

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.

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

dmax shall not equal zero

dmax shall not be greater than RSIZE_MAX_STR

dmax shall be greater than strnlen_s(src,m).

Copying shall not takeplace 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 strncat_s sets dest[0] to the null character.

Return values

EOK	successful operation, all the characters from src null terminated.
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
ESUNTERM	when dest not terminated
ESOVRLP	when src overlaps with dest

strncpy_s()

EXTERN errno_t strncpy_s	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	slen
	)

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.

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.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): 7.21.2.4 The strncpy function (p: 326-327) 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

Neither dmax nor slen shall be equal to zero.

Neither dmax nor slen shall be equal zero.

Neither dmax nor slen shall be greater than RSIZE_MAX_STR.

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, then if dest is not a null pointer and dmax greater than RSIZE_MAX_STR, then strncpy_s nulls dest.

Return values

EOK	successful operation, the characters in src were copied to dest and the result is null terminated.
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
ESOVRLP	when strings overlap
ESNOSPC	when dest < src

See also

strcat_s(), strncat_s(), strcpy_s(), wcsncpy_s()

strnlen_s()

EXTERN rsize_t strnlen_s	(	const char *	dest,
		rsize_t	dmax
	)

The strnlen_s function computes the length of the string pointed to by dest.

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

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.

Returns

The function returns the string length, excluding the terminating null character. If dest 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 dmax characters of dest then strnlen_s returns dmax. At most the first dmax characters of dest are accessed by strnlen_s.

See also

strnterminate_s()

strtok_s()

EXTERN char* strtok_s	(	char *restrict	dest,
		rsize_t *restrict	dmax,
		const char *restrict	delim,
		char **restrict	ptr
	)

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/strok
• 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]	dmax	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. 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 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()

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

The sprintf_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.

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

Neither dest nor fmt shall be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR.

dmax shall not equal zero.

dmax shall be greater than strnlen_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.

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 encoding error occurred, sprintf_s returns a negative value. If any other runtime- constraint violation in vsnprintf occurred, sprintf_s returns zero.

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 character at dest[0], and the invalid parameter handler is invoked. Unlike _snprintf, sprintf_s guarantees that the buffer will be null-terminated unless the buffer size is zero.

errno: ESNULLP when dest/fmt is NULL pointer ESZEROL when dmax = 0 ESLEMAX when dmax > RSIZE_MAX_STR ESNOSPC when return value exceeds dmax EINVAL when fmt contains n

Return values

-1	if an encoding error occurred or the return buffer size exceeds dmax.
0	on some other error in vsnprintf().

vsprintf_s()

EXTERN int vsprintf_s	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	fmt,
		va_list	ap
	)

The vsprintf_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. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by vsprintf_s in the array of dmax characters pointed to by dest are nulled when vsprintf_s returns.

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

Neither dest nor fmt shall be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR.

dmax shall not equal zero.

dmax shall be greater than strnlen_s(dest, dmax).

fmt shall not contain the conversion specifier n

None of the arguments corresponding to s is a null pointer

No encoding error shall occur.

Note

C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns

On success the total number of characters written is returned.

On failure a negative 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 character at dest[0], and the invalid parameter handler is invoked. Unlike vsnprintf, vsprintf_s guarantees that the buffer will be null-terminated unless the buffer size is zero.

errno: ESNULLP when dest/fmt is NULL pointer ESZEROL when dmax = 0 ESLEMAX when dmax > RSIZE_MAX_STR ESNOSPC when return value exceeds dmax EINVAL when fmt contains n

Return values

-1	if an encoding error occurred or the return buffer size exceeds dmax.
0	on some other error in vsnprintf().

See also

sprintf_s(), vsnprintf_s()

snprintf_s()

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

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. More than dmax - 1 characters might be written, so this variant is unsafe! Always use sprintf_s instead. The resulting character string will be terminated with a null character, unless dmax is zero. 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. Warning: Unlike the safe variant sprintf_s, snprintf_s does not guarantee that the buffer will be null-terminated unless the buffer size is zero.

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
• only included in safeclib with –enable-unsafe

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

Neither dest nor fmt shall be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR.

dmax shall not equal zero.

dmax shall be greater than strnlen_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.

Returns

Number of characters not including the terminating null character (which is always written as long as buffer is not a null pointer and dmax is not zero and not greater than RSIZE_MAX_STR), which would have been written to dest if dmax was ignored, or a negative value if a runtime constraints violation or an encoding error occurred.

Return values

-ESNULLP	when dest/fmt is NULL pointer
-ESZEROL	when dmax = 0
-ESLEMAX	when dmax > RSIZE_MAX_STR
-EINVAL	when fmt contains n

See also

sprintf_s(), vsnprintf_s()

vsnprintf_s()

EXTERN int vsnprintf_s	(	char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	fmt,
		va_list	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. Warning: Unlike the safe variant vsprintf_s, vsnprintf_s does not guarantee that the buffer will be null-terminated unless the buffer size is zero. More than dmax - 1 characters might be written!

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
• only included in safeclib with –enable-unsafe

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

Neither dest nor fmt shall be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR.

dmax shall not equal zero.

dmax shall be greater than strnlen_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_STR.

Returns

On success the total number of 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 character at dest[0], and the invalid parameter handler is invoked. Unlike vsnprintf, vsprintf_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_STR
-EINVAL	when fmt contains n

See also

sprintf_s(), vsprintf_s()

sscanf_s()

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

The sscanf_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.7 The sscanf_s function (p: 596) http://en.cppreference.com/w/c/io/fscanf

Parameters

[in]	buffer	pointer to a null-terminated string to read from
[in]	fmt	format-control string.
[out]	...	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.

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

vsscanf_s(), swscanf_s(), vsnprintf_s()

fscanf_s()

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

The fscanf_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.2 The fscanf_s function (p: 592-593) http://en.cppreference.com/w/c/io/fscanf

Parameters

[in]	stream	pointer to a FILE stream to read from
[in]	fmt	format-control string.
[out]	...	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.

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(), fwscanf_s(), scanf_s()

scanf_s()

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

The scanf_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.4 The scanf_s function (p: 594) http://en.cppreference.com/w/c/io/fscanf

Parameters

[in]	fmt	format-control string.
[out]	...	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.

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

vsscanf_s(), swscanf_s(), vsnprintf_s()

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.

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.

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.

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

The printf_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.3 The printf_s function (p: 593-594) http://en.cppreference.com/w/c/io/fprintf

Parameters

[in]	fmt	format-control string
[in]	...	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.

fprintf_s()

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

The fprintf_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.1 The fprintf_s function (p: 591) http://en.cppreference.com/w/c/io/fprintf

Parameters

[out]	stream	output file stream to write to
[in]	fmt	format-control string.
[in]	...	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.

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

EXTERN errno_t strerror_s	(	char *	dest,
		rsize_t	dmax,
		errno_t	errnum
	)

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 bufsz-1 bytes are written, the buffer is always null-terminated. If the message had to be truncated to fit the buffer and bufsz is greater than 3, then only bufsz-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 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.

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
ESLEMIN	when the result would be longer than 4 and dmax < 4

See also

strerrorlen_s()

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

EXTERN errno_t strcmp_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		int *	indicator
	)

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]	indicator	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.

indicator shall not be a null pointer.

dmax shall not be 0

dmax shall not be greater than RSIZE_MAX_STR

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/indicator is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

strcasecmp_s()

strcasecmp_s()

EXTERN errno_t strcasecmp_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		int *	indicator
	)

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]	indicator	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.

indicator shall not be a null pointer.

dmax shall not be 0

dmax shall not be greater than RSIZE_MAX_STR

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/indicator is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

strcmp_s()

strcasestr_s()

EXTERN errno_t strcasestr_s	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		char **	substring
	)

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 sub string
[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.

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
ESNOTFND	when substring not found

See also

strstr_s(), strprefix_s()

strcmpfld_s()

EXTERN errno_t strcmpfld_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		int *	indicator
	)

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]	indicator	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.

indicator shall not be a null pointer.

dmax shall not be 0

dmax shall not be greater than RSIZE_MAX_STR

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/indicator is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

strcpyfld_s(), strcpyfldin_s(), strcpyfldout_s()

strcpyfld_s()

EXTERN errno_t strcpyfld_s	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen
	)

The strcpyfld_s function copies slen characters from the character array pointed to by src into the character array pointed to by dest.

The copy operation does not stop on the null character as the function copies slen 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

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

Precondition

Neither dest nor src shall be a null pointer.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_STR.

slen shall not equal zero.

slen shall not exceed dmax

Copying shall not take place between objects that overlap.

Returns

If there is a runtime-constraint violation, then if dest is not a null pointer and destmax is greater than zero and not greater than RSIZE_MAX_STR, then strcpyfld_s nulls dest.

Return values

EOK	when successful operation
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESOVRLP	when strings overlap
ESNOSPC	when dmax < slen

See also

strcpyfldin_s(), strcpyfldout_s()

strcpyfldin_s()

EXTERN errno_t strcpyfldin_s	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen
	)

The strcpyfldin_s function copies at most slen characters from the null terminated string pointed to by src into the fixed character array pointed to by dest.

The copy operation stops on the null character if encountered and then continues to fill the field with nulls up to 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

[out]	dest	pointer to string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the null terminated string that will be copied into the character array pointed to by dest
[in]	slen	maximum length of src

Precondition

Neither dest nor src shall be a null pointer.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_STR.

slen shall not equal zero.

slen shall not exceed dmax

Copying shall not take place between objects that overlap.

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 strcpyfldin_s nulls dest

Return values

EOK	when successful operation
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESOVRLP	when strings overlap
ESNOSPC	when dmax < slen

See also

strcpyfld_s(), strcpyfldout_s(),

strcpyfldout_s()

EXTERN errno_t strcpyfldout_s	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen
	)

The strcpyfldout_s function copies slen characters from the character array pointed to by src into the string pointed to by dest.

A null is included to properly termiante the dest string. The copy operation does not stop on the null character as function copies 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 that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the character array to be copied to dest and null terminated.
[in]	slen	the maximum number of characters that will be copied from the src field into the dest string.

Precondition

Neither dest nor src shall be a null pointer.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_STR.

slen shall not equal zero.

slen shall not exceed dmax

Copying shall not take place between objects that overlap.

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 strcpyfldout_s nulls dest

Return values

EOK	when successful operation
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESOVRLP	when strings overlap
ESNOSPC	when dmax < slen

See also

strcpyfld_s(), strcpyfldin_s()

strcspn_s()

EXTERN errno_t strcspn_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		rsize_t *	count
	)

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]	count	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

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

See also

strspn_s(), strpbrk_s(), strstr_s()

strfirstchar_s()

EXTERN errno_t strfirstchar_s	(	char *	dest,
		rsize_t	dmax,
		char	c,
		char **	first
	)

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]	first	returned pointer to first occurrence of c

Precondition

dest shall not be a null pointer.

first shall not be a null pointer.

dmax shall not be 0

dmax shall not be greater than RSIZE_MAX_STR

Returns

pointer to first occurence of c, NULL if not found

Return values

EOK	when pointer to first occurrence is returned
ESNULLP	when dst/first is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

strlastchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastdiff_s(), strlastsame_s(),

strfirstdiff_s()

EXTERN errno_t strfirstdiff_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	index
	)

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]	index	pointer to returned index to first difference

Precondition

Neither dest nor src shall be a null pointer.

indicator shall not be a null pointer.

dmax shall not be 0.

dmax shall not be greater than RSIZE_MAX_STR.

Returns

index to first difference, when the return code is OK

Return values

EOK	when index to first diff is returned
ESNODIFF	when no difference
ESNULLP	when dest/src/index is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

strfirstchar_s(), strfirstsame_s(), strlastchar_s(), strlastdiff_s(), strlastsame_s()

strisalphanumeric_s()

EXTERN bool strisalphanumeric_s	(	const char *	dest,
		rsize_t	dmax
	)

This function checks if the entire string contains alphanumerics.

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.

Returns

true when dest is 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()

EXTERN bool strisascii_s	(	const char *	dest,
		rsize_t	dmax
	)

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.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_STR.

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

EXTERN bool strisdigit_s	(	const char *	dest,
		rsize_t	dmax
	)

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.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_STR..

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

EXTERN bool strishex_s	(	const char *	dest,
		rsize_t	dmax
	)

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.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_STR.

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

EXTERN bool strislowercase_s	(	const char *	dest,
		rsize_t	dmax
	)

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.

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

EXTERN bool strismixedcase_s	(	const char *	dest,
		rsize_t	dmax
	)

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.

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

EXTERN bool strispassword_s	(	const char *	dest,
		rsize_t	dmax
	)

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 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 has valid password makeup

false when string does not meet requirements or an error occurred

See also

strzero_s()

strisuppercase_s()

EXTERN bool strisuppercase_s	(	const char *	dest,
		rsize_t	dmax
	)

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.

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

EXTERN errno_t strlastchar_s	(	char *	dest,
		rsize_t	dmax,
		char	c,
		char **	last
	)

Returns a pointer to the last 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]	last	returned pointer to first occurrence of c

Precondition

dest shall not be a null pointer.

last shall not be a null pointer.

dmax shall not be 0

dmax shall not be greater than RSIZE_MAX_STR

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

See also

strfirstchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastdiff_s(), strlastsame_s()

strlastdiff_s()

EXTERN errno_t strlastdiff_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	index
	)

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]	index	pointer to returned index to last difference

Precondition

Neither dest nor src shall be a null pointer.

indicator shall not be a null pointer.

dmax shall not be 0.

dmax shall not be greater than RSIZE_MAX_STR.

Returns

index to last difference, when the return code is OK

Return values

EOK	when index to last diff is returned
ESNODIFF	when no difference
ESNULLP	when dest/src/index is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

strfirstchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastchar_s(), strlastsame_s()

strljustify_s()

EXTERN errno_t strljustify_s	(	char *	dest,
		rsize_t	dmax
	)

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

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
ESUNTERM	when dest was not null terminated

See also

strremovews_s(),

strnterminate_s()

EXTERN rsize_t strnterminate_s	(	char *	dest,
		rsize_t	dmax
	)

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.

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

EXTERN errno_t strpbrk_s	(	char *	dest,
		rsize_t	dmax,
		char *	src,
		rsize_t	slen,
		char **	first
	)

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
first	returned pointer to first occurence

Precondition

Neither dest nor src shall be a null pointer.

Neither dmax nor slen shall not be 0.

Neither dmax nor slen shall not be greater than RSIZE_MAX_STR.

Returns

pointer to the first ocurrence of any character contained in src

Return values

EOK	when successful operation
ESNULLP	when dest/src/first is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR

See also

strfirstchar_s(), strlastchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastdiff_s(), strlastsame_s()

strfirstsame_s()

EXTERN errno_t strfirstsame_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	index
	)

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

The scanning stops at the fisrt 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]	index	pointer to returned index

Precondition

Neither dest nor src shall be a null pointer.

indicator shall not be a null pointer.

dmax shall not be 0.

dmax shall not be greater than RSIZE_MAX_STR.

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 dst/src/index is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESNOTFND	when not found

See also

strfirstchar_s(), strfirstdiff_s(), strlastchar_s(), strlastdiff_s(), strlastsame_s()

strlastsame_s()

EXTERN errno_t strlastsame_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t *	index
	)

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]	index	pointer to returned index

Precondition

Neither dest nor src shall be a null pointer.

indicator shall not be a null pointer.

dmax shall not be 0.

dmax shall not be greater than RSIZE_MAX_STR.

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/index is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESNOTFND	when not found

See also

strfirstchar_s(), strfirstdiff_s(), strfirstsame_s(), strlastchar_s(), strlastdiff_s()

strprefix_s()

EXTERN errno_t strprefix_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src
	)

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.

Neither dmax nor slen shall not be 0.

Neither dmax nor slen shall not be greater than RSIZE_MAX_STR.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
ESNOTFND	when prefix not found in dest

See also

strspn_s(), strcspn_s(), strpbrk_s(), strstr_s()

strremovews_s()

EXTERN errno_t strremovews_s	(	char *	dest,
		rsize_t	dmax
	)

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

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
ESUNTERM	when dest was not null terminated

See also

strljustify_s(),

strspn_s()

EXTERN errno_t strspn_s	(	const char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		rsize_t *	count
	)

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]	count	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.

Neither dmax nor slen shall not be 0.

Neither dmax nor slen shall not be greater than RSIZE_MAX_STR.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR

See also

strcspn_s(), strpbrk_s(), strstr_s(), strprefix_s()

strstr_s()

EXTERN errno_t strstr_s	(	char *	dest,
		rsize_t	dmax,
		const char *	src,
		rsize_t	slen,
		char **	substring
	)

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]	substring	the returned substring pointer

Precondition

Neither dest nor src shall be a null pointer.

Neither dmax nor slen shall not be 0.

Neither dmax nor slen shall not be greater than RSIZE_MAX_STR.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
ESNOTFND	when substring not found

See also

strprefix_s(), strspn_s(), strcspn_s(), strpbrk_s()

strchr_s()

EXTERN errno_t strchr_s	(	const char *restrict	dest,
		rsize_t	dmax,
		const int	ch,
		char **	result
	)

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]	result	pointer to char* in dest

Precondition

Neither dest nor result shall be a null pointer.

dmax shall not be 0.

dmax shall not be greater than RSIZE_MAX_STR.

ch shall not be greater than 255

Return values

EOK	when successfully character found.
ESNULLP	when dest/result is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESLEMAX	when ch > 255
ESNOTFND	when ch not found in dest

See also

memchr_s(), strspn_s(), strcspn_s(), strpbrk_s(), strstr_s()

strrchr_s()

EXTERN errno_t strrchr_s	(	const char *restrict	dest,
		rsize_t	dmax,
		const int	ch,
		char **	result
	)

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]	result	pointer to char* in dest

Precondition

Neither dest nor result shall be a null pointer.

dmax shall not be 0.

dmax shall not be greater than RSIZE_MAX_STR.

ch shall not be greater than 255

Return values

EOK	when successfully character found.
ESNULLP	when dest/result is a NULL pointer
ESZEROL	when dmax = 0 or strnlen_s = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
ESLEMAX	when ch > 255
ESNOTFND	when ch not found in dest

See also

memrchr_s(), strchr_s(), memchr_s(), strspn_s(), strstr_s()

strtolowercase_s()

EXTERN errno_t strtolowercase_s	(	char *restrict	dest,
		rsize_t	dmax
	)

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

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

[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

See also

strtouppercase_s()

strtouppercase_s()

EXTERN errno_t strtouppercase_s	(	char *	dest,
		rsize_t	dmax
	)

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

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

[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

ALSO SEE strtolowercase_s()

strzero_s()

EXTERN errno_t strzero_s	(	char *	dest,
		rsize_t	dmax
	)

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

See also

strispassword_s()

strcoll_s()

EXTERN errno_t strcoll_s	(	const char *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		int *	indicator
	)

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]	indicator	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.

indicator shall not be a null pointer.

dmax shall not be 0

dmax shall not be greater than RSIZE_MAX_STR

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/indicator is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR

See also

wcscoll_s(), strcmp_s(), strcasecmp_s()

strset_s()

EXTERN errno_t strset_s	(	char *restrict	dest,
		rsize_t	dmax,
		int	value
	)

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.

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 dmax > RSIZE_MAX_STR or value > 255

See also

strzero_s(), strnset_s(), strispassword_s()

strnset_s()

EXTERN errno_t strnset_s	(	char *restrict	dest,
		rsize_t	dmax,
		int	value,
		rsize_t	n
	)

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.

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 dmax > RSIZE_MAX_STR or value > 255
ESNOSPC	when n > dmax

See also

strzero_s(), strset_s(), wcsnset_s(), strispassword_s()

mbstowcs_s()

EXTERN errno_t mbstowcs_s	(	size_t *restrict	retval,
		wchar_t *restrict	dest,
		rsize_t	dmax,
		const char *restrict	src,
		rsize_t	len
	)

mbsrtowcs_s()

EXTERN errno_t mbsrtowcs_s	(	size_t *restrict	retval,
		wchar_t *restrict	dest,
		rsize_t	dmax,
		const char **restrict	src,
		rsize_t	len,
		mbstate_t *restrict	ps
	)

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 *src to its wide character representation. If dest is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dest. No more than len wide characters are written to the destination array. Each multibyte character is converted as if by a call to mbrtowc. 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. *src is set to NULL and *ps represents the initial shift state.
• An invalid multibyte character (according to the current C locale) was encountered. *src is set to point at the beginning of the first unconverted multibyte character.
• the next wide character to be stored would exceed len. *src 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/byte/mbsrtowcs
• ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retval	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]	src	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

retval, ps, src, or *src shall not be a null pointer.

dmax and len shall not be greater than RSIZE_MAX_WSTR (unless dest is null).

dmax shall not equal zero.

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 mbsrtowcs_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retval, ps, src or *src are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_WSTR, unless dest is NULL
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)

See also

mbstowc_s()

wcsrtombs_s()

EXTERN errno_t wcsrtombs_s	(	size_t *restrict	retval,
		char *restrict	dest,
		rsize_t	dmax,
		const wchar_t **restrict	src,
		rsize_t	len,
		mbstate_t *restrict	ps
	)

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 *src 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', *src 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. *src is set to point at the first unconverted wide character.
• the next multibyte character to be stored would exceed len. *src 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 src = NULL, *src = 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]	retval	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]	src	pointer to the wide string that will be copied to dest
[in]	len	number of bytes available in dest
[in]	ps	pointer to the conversion state object

Precondition

retval, ps, src, or *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 wcsrtombs_s nulls dest. Then the number of bytes excluding terminating zero that were, or would be written to dest, is stored in *retval.

Return values

EOK	on successful conversion.
ESNULLP	when retval, ps, src or *src are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
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 wctomb()

See also

wcrtomb_s(), wcstombs_s()

wcstombs_s()

EXTERN errno_t wcstombs_s	(	size_t *restrict	retval,
		char *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	len
	)

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 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 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/byte/wcstombs
• ISO/IEC TR 24731, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[out]	retval	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

retval 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 *retval.

Return values

EOK	on successful conversion.
ESNULLP	when retval or src are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
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()

EXTERN errno_t wcrtomb_s	(	size_t *restrict	retval,
		char *restrict	dest,
		rsize_t	dmax,
		wchar_t	wc,
		mbstate_t *restrict	ps
	)

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]	retval	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

retval and ps shall not be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR (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 zero or greater than RSIZE_MAX_STR) and *retval is set to (size_t)-1 (unless retval is null).

Return values

EOK	on successful conversion.
ESNULLP	when retval or ps are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
ESNOSPC	when dmax is smaller than the number of required bytes

See also

wctomb_s()

wctomb_s()

EXTERN errno_t wctomb_s	(	int *restrict	retval,
		char *restrict	dest,
		rsize_t	dmax,
		wchar_t	wc
	)

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]	retval	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

retval shall not be a null pointer.

dmax shall not be greater than RSIZE_MAX_STR (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 zero or greater than RSIZE_MAX_STR) and *retval is set to (size_t)-1 (unless retval is null).

Return values

EOK	on successful conversion.
ESNULLP	when retval is a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
ESNOSPC	when dmax is smaller than the number of required bytes
EILSEQ	if returned by wctomb()

See also

wcrtomb_s()

wcsnlen_s()

EXTERN size_t wcsnlen_s	(	const wchar_t *	dest,
		rsize_t	dmax
	)

The wcsnlen_s function computes the length of the wide string pointed to by dest.

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

dest	pointer to wide string
dmax	maximum length of wide string

Precondition

dest shall not be a null pointer.

dmax shall not equal zero.

dmax shall not be greater than RSIZE_MAX_WSTR.

Returns

The function returns the wide string length, excluding the terminating null character. If dest 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 dmax characters of dest then wcsnlen_s returns dmax. At most the first dmax characters of dest are accessed by wcsnlen_s.

See also

strnlen_s(), strnterminate_s()

wcscpy_s()

EXTERN errno_t wcscpy_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src
	)

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.

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

EXTERN errno_t wcsncpy_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	slen
	)

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 is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then wcsncpy_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

wcscpy_s(), strncpy_s(), wmemcpy_s(), wmemmove_s()

wcscat_s()

EXTERN errno_t wcscat_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src
	)

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.7.2.1 The wcscat_s function (p: 617-618) 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 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

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

EXTERN errno_t wcsncat_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	slen
	)

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.7.2.2 The wcsncat_s function (p: 618-620) 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

dmax shall be greater than wcsnlen_s(src,m).

Copying shall not takeplace 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 wcsncat_s sets dest[0] to the 0 wide character.

Return values

EOK	successful operation, all the wide characters from src null terminated.
ESNULLP	when dest/src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_WSTR
ESUNTERM	when dest not terminated
ESOVRLP	when src overlaps with dest

See also

wcscat_s(), strncat_s()

wcstok_s()

EXTERN wchar_t* wcstok_s	(	wchar_t *restrict	dest,
		rsize_t *restrict	dmax,
		const wchar_t *restrict	delim,
		wchar_t **restrict	ptr
	)

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.7.3.1 The wcstok_s function (p: 620-621) http://en.cppreference.com/w/c/string/byte/strok
• 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]	dmax	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_WSTR. 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 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()

EXTERN int swprintf_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	fmt,
			...
	)

The swprintf_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 swprintf_s in the array of dmax wide characters pointed to by dest are nulled when swprintf_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 call fails, errno is set.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.9.1.4 The swprintf_s function (p: 630-631) http://en.cppreference.com/w/c/io/fwprintf

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.

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 swprintf_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.

Returns

If no runtime-constraint violation occurred, the swprintf_s function returns the number of wide characters written in the array, not counting the terminating null wide character. If an encoding error occurred or if n or more wide characters are requested to be written, swprintf_s returns a negative value. If any other runtime-constraint violation occurred, swprintf_s returns zero, and sets errno.

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.

errno: ESNULLP when dest/fmt is NULL pointer ESZEROL when dmax = 0 ESLEMAX when dmax > RSIZE_MAX_WSTR ESNOSPC when return value exceeds dmax EINVAL when fmt contains n

Return values

-1	if an encoding error occurred or if n or more wide characters are requested to be written.
0	on some other error

See also

vswprintf_s(), snwprintf_s(), vsnprintf_s()

vswprintf_s()

EXTERN int vswprintf_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	fmt,
		va_list	ap
	)

The vswprintf_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 vswprintf_s in the array of dmax wide characters pointed to by dest are nulled when vswprintf_s returns.

Remarks

SPECIFIED IN

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

Returns

If no runtime-constraint violation occurred, the vswprintf_s function returns the number of wide characters written in the array, not counting the terminating null wide character. If an encoding error occurred or if n or more wide characters are requested to be written, vswprintf_s returns a negative value. If any other runtime-constraint violation occurred, vswprintf_s returns zero.

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 vsnprintf, vswprintf_s guarantees that the buffer will be null-terminated unless the buffer size is zero.

errno: ESNULLP when dest/fmt is NULL pointer ESZEROL when dmax = 0 ESLEMAX when dmax > RSIZE_MAX_WSTR ESNOSPC when return value exceeds dmax EINVAL when fmt contains n EINVAL or EOVERFLOW if returned by vswprintf

Return values

-1	if an encoding error occurred or if n or more wide characters are requested to be written.
0	on some other error.

See also

sprintf_s(), vsnprintf_s()

snwprintf_s()

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

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. Warning: Unlike the safe variant swprintf_s, snwprintf_s does not guarantee that the buffer will be null-terminated unless the buffer size is zero.

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.

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
-ESNOSPC	when return value exceeds dmax
-EINVAL	when fmt contains n
-1	on some other error. errno is set then

See also

vswprintf_s(), swprintf_s(), vsnprintf_s()

vsnwprintf_s()

EXTERN int vsnwprintf_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	fmt,
		va_list	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. 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. Warning: Unlike the safe variant vswprintf_s, vsnwprintf_s does not guarantee that the buffer will be null-terminated unless the buffer size is zero.

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
• 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]	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

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

See also

vswprintf_s(), snwprintf_s(), vsnprintf_s()

wprintf_s()

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

The wprintf_s function prints formatted output to stdout as wide string.

Note

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

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.9.1.13 The wprintf_s function (p: 637-638) http://en.cppreference.com/w/c/io/fwprintf

Parameters

[in]	fmt	format-control wide string.
[in]	...	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(), fwprintf_s()

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

The fwprintf_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 fwprintf_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]	...	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()

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	buffer,
		const wchar_t *restrict	fmt,
			...
	)

The swscanf_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.5 The swscanf_s function (p: 631) http://en.cppreference.com/w/c/io/fwscanf

Parameters

[in]	buffer	pointer to a null-terminated wide string to read from
[in]	fmt	format-control wide string.
[out]	...	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 lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function.

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

vswscanf_s()

EXTERN int vswscanf_s	(	const wchar_t *restrict	buffer,
		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]	buffer	pointer to a null-terminated wide string to read from
[in]	fmt	format-control wide string.
[in]	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 lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function.

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

The wscanf_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 wscanf.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.9.1.14 The wscanf_s function (p: 638) http://en.cppreference.com/w/c/io/wscanf

Parameters

[in]	fmt	format-control wide string.
[out]	...	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 lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed constraint handler function.

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(), fwscanf_s(), vfwscanf_s(), vfwprintf_s()

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.

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(), wscanf_s(), vvwscanf_s(), vfwprintf_s()

fwscanf_s()

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

The fwscanf_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 fwscanf_s function (p: 632-633) http://en.cppreference.com/w/c/io/fwscanf

Parameters

[in]	stream	pointer to a FILE stream to read from
[in]	fmt	format-control wide string.
[out]	...	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) Note it currently even crashes with a NULL pointer.

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.

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(), wscanf_s(), vfwscanf_s(), vfwprintf_s()

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.

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

>	0 on success, the number of arguments assigned
EOF	on error

See also

vswscanf_s(), fwscanf_s(), vfwprintf_s()

wcsstr_s()

EXTERN errno_t wcsstr_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	slen,
		wchar_t **restrict	substring
	)

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]	substring	the returned substring pointer

Precondition

Neither dest nor src shall be a null pointer.

Neither dmax nor slen shall not be 0.

Neither dmax nor slen shall not be greater than RSIZE_MAX_WSTR.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
ESNOTFND	when substring not found

See also

wcsstr(), strstr_s(), memcmp32_s()

wcscmp_s()

EXTERN errno_t wcscmp_s	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		int *	diff
	)

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]	diff	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.

diff shall not be a null pointer.

dmax/smax shall not be 0

dmax/smax shall not be greater than RSIZE_MAX_WSTR

Return values

EOK	when comparison is complete
ESNULLP	when dest/src/diff is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR

See also

strcmp_s(), wcsncmp_s(), wcsicmp_s()

wcsncmp_s()

EXTERN errno_t wcsncmp_s	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		rsize_t	count,
		int *	diff
	)

Compares at most count wide characters of wide string src with 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
[in]	count	maximum number of wide characters to compare
[out]	diff	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.

diff shall not be a null pointer.

dmax/smax shall not be 0

dmax/smax shall not be greater than RSIZE_MAX_WSTR

Returns

diff (when the return code is OK)

Return values

>0	when dest greater than src
0	when wide strings the same
<0	when dest less than src
EOK	when comparison is complete
ESNULLP	when dest/src/diff is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR

See also

strcmp_s(), wcscmp_s()

wcsicmp_s()

EXTERN errno_t wcsicmp_s	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		int *	diff
	)

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]	diff	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.

diff shall not be a null pointer.

dmax/smax shall not be 0

dmax/smax shall not be greater than RSIZE_MAX_WSTR

Return values

EOK	when comparison is complete
ESNULLP	when dest/src/diff is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR

See also

strcmp_s(), wcscmp_s(), wcsncmp_s(), wcsfc_s()

wcsset_s()

EXTERN errno_t wcsset_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t	value
	)

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

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR

See also

wcsnset_s(), wmemset_s(), strzero_s(), strnset_s(), strispassword_s()

wcsnset_s()

EXTERN errno_t wcsnset_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t	value,
		rsize_t	n
	)

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

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR or value > max wchar_t
ESNOSPC	when n > dmax

See also

wcsset_s(), wmemset_s(), strzero_s(), strnset_s(), strispassword_s()

wcscoll_s()

EXTERN errno_t wcscoll_s	(	const wchar_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	smax,
		int *	indicator
	)

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]	indicator	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.

indicator shall not be a null pointer.

dmax/smax shall not be 0

dmax/smax shall not be greater than RSIZE_MAX_WSTR

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/indicator is NULL pointer
ESZEROL	when dmax/smax = 0
ESLEMAX	when dmax/smax > RSIZE_MAX_WSTR

See also

wcscmp_s(), strcoll_s(), strcasecmp_s()

wcslwr_s()

EXTERN errno_t wcslwr_s	(	wchar_t *restrict	src,
		rsize_t	slen
	)

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. 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 equal zero.

slen shall not be greater than RSIZE_MAX_WSTR.

Return values

EOK	on successful operation
ESNULLP	when src is NULL pointer
ESZEROL	when slen = 0
ESLEMAX	when slen > RSIZE_MAX_WSTR

See also

wcsfc_s(), strtolowercase_s(), strlwr_s(), wcsupr_s()

wcsupr_s()

EXTERN errno_t wcsupr_s	(	wchar_t *restrict	src,
		rsize_t	slen
	)

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 equal zero.

slen shall not be greater than RSIZE_MAX_WSTR.

Return values

EOK	on successful operation
ESNULLP	when src is NULL pointer
ESZEROL	when slen = 0
ESLEMAX	when slen > RSIZE_MAX_WSTR

See also

strtouppercase_s(), strlwr_s(), wcslwr_s()

iswfc()

EXTERN int iswfc

(

wint_t

wc

)

towfc_s()

EXTERN int towfc_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		const wint_t	src
	)

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+FFFF.

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.

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
-ESNOTFND	when no mapping for src was found, iswfc is wrong.

See also

iswfc(), wcsfc_s(), towlower()

wcsfc_s()

EXTERN errno_t wcsfc_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t *restrict	src,
		rsize_t *restrict	lenp
	)

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.

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

EXTERN errno_t wcsnorm_decompose_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t *restrict	src,
		rsize_t *restrict	lenp,
		bool	iscompat
	)

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.

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

EXTERN errno_t wcsnorm_reorder_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t *restrict	p,
		rsize_t	len
	)

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]	p	wide string to be converted
[in]	len	length of p

Precondition

dest and p 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()

EXTERN errno_t wcsnorm_compose_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t *restrict	p,
		rsize_t *restrict	lenp,
		bool	iscontig
	)

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]	p	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, p 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()

EXTERN errno_t wcsnorm_s	(	wchar_t *restrict	dest,
		rsize_t	dmax,
		wchar_t *restrict	src,
		wcsnorm_mode_t	mode,
		rsize_t *restrict	lenp
	)

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