wcstombs_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for wcstombs_s.c:

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

Function Documentation

wcstombs_s()

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

Parameters

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