mbsrtowcs_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for mbsrtowcs_s.c:

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

Function Documentation

mbsrtowcs_s()

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