snwprintf_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for snwprintf_s.c:

Macros
#define	__STDC_WANT_LIB_EXT1__   1

Functions
EXPORT 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...

Macro Definition Documentation

__STDC_WANT_LIB_EXT1__

#define __STDC_WANT_LIB_EXT1__   1

Function Documentation

snwprintf_s()

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