wcsrtombs_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for wcsrtombs_s.c:

Functions
EXPORT errno_t	wcsrtombs_s (size_t *restrict retval, char *restrict dest, rsize_t dmax, const wchar_t **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

wcsrtombs_s()

EXPORT errno_t wcsrtombs_s	(	size_t *restrict	retval,
		char *restrict	dest,
		rsize_t	dmax,
		const wchar_t **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 wcsrtombs_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 that begins in the conversion state described by *ps. If dest is not null, converted characters are stored in the successive elements of dest. No more than len bytes written to the destination array. Each wide character is converted as if by a call to wcrtomb. wcsrtombs_s clobbers the destination array from the terminating null and until dmax. In extension to wcstombs_s you can re-use the state via ps.

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', *src is set to NULL and *ps represents the initial shift state.
• A wchar_t was found that does not correspond to a valid character in the current LC_CTYPE locale. *src is set to point at the first unconverted wide character.
• the next multibyte character to be stored would exceed len. *src is set to point at the beginning of the first unconverted wide character. 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, *src = NULL, ESNOSPC and EILSEQ.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.9.3.2.2 The wcsrtombs_s function (p: 649-650) http://en.cppreference.com/w/c/string/wide/wcsrtombs
• 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 character array where the result will be stored
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the wide string that will be copied to dest
[in]	len	number of bytes available in 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_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 wcsrtombs_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, ps, src 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 wctomb()

See also

wcrtomb_s(), wcstombs_s()