wctomb_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for wctomb_s.c:

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

Function Documentation

wctomb_s()

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