wcrtomb_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for wcrtomb_s.c:

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

Function Documentation

wcrtomb_s()

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