Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

wcsrtombs(3C)

Name

wcsrtombs, wcsnrtombs - convert a wide-character string to a character string (restartable)

wcsrtombs_s - wide-character string operations with additional safety checks

Synopsis

#include <wchar.h>

size_t wcsrtombs(char *restrict dst,
     const wchar_t **restrict src, size_t len,
     mbstate_t *restrict ps);
size_t wcsnrtombs(char *restrict dst,
     const wchar_t **restrict src, size_t nwc, size_t len,
     mbstate_t *restrict ps);
#define __STDC_WANT_LIB_EXT1__ 1
#include <wchar.h>

errno_t wcsrtombs_s(size_t *restrict retval, char *restrict dst,
    rsize_t dstmax, const wchar_t **restrict src, rsize_t len,
    mbstate_t *restrict ps);

Description

The wcsrtombs() function converts a sequence of wide-characters from the array indirectly pointed to by src into a sequence of corresponding characters, beginning in the conversion state described by the object pointed to by ps. If dst is not a null pointer, the converted characters are then stored into the array pointed to by dst. Conversion continues up to and including a terminating null wide-character, which is also stored. Conversion stops earlier in the following cases:

  • When a code is reached that does not correspond to a valid character.

  • When the next character would exceed the limit of len total bytes to be stored in the array pointed to by dst (and dst is not a null pointer).

Each conversion takes place as if by a call to the wcrtomb() function.

If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if conversion stopped due to reaching a terminating null wide-character) or the address just past the last wide-character converted (if any). If conversion stopped due to reaching a terminating null wide-character, the resulting state described is the initial conversion state.

If ps is a null pointer, the wcsrtombs() function uses its own internal mbstate_t object, which is initialized at program startup to the initial conversion state. Otherwise, the mbstate_t object pointed to by ps is used to completely describe the current conversion state of the associated character sequence. Solaris will behave as if no function defined in the Solaris Reference Manual calls these functions.

The wcsnrtombs() function is equivalent to the wcsrtombs() function, except that the conversion is limited to the first nwc wide characters.

The behavior of these functions are affected by the LC_CTYPE category of the current locale. See environ(7).

The wcsrtombs_s() function is part of the C11 bounds checking interfaces specified in the C11 standard, Annex K. It is similar to the wcsrtombs() function, but with differing parameters and return type in order to provide additional safety checks in the form of explicit runtime-constraints as defined by the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.

Return Values

If conversion stops because a code is reached that does not correspond to a valid character, an encoding error occurs. In this case, these functions store the value of the macro EILSEQ in errno and returns (size_t)-1; the conversion state is undefined. Otherwise, these functions return the number of bytes in the resulting character sequence, not including the terminating null (if any).

If neither a runtime-constraint violation nor encoding error (the result of a failed conversion) occurred, wcsrtombs_s() returns zero, otherwise, it returns a non-zero value.

Errors

The wcsrtombs() function will fail if:

EINVAL

The ps argument points to an object that contains an invalid conversion state.

EILSEQ

A wide-character code does not correspond to a valid character.

The wcsrtombs_s() function will fail if:

EINVAL

Null pointer is passed or source and destination overlaps.

ERANGE

size argument is not a valid value.

EOVERFLOW

Destination array is too small

EILSEQ

Illegal byte sequence.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
See the 'Notes' section
Standard

See Also

mbsinit(3C), setlocale(3C), wcrtomb(3C), attributes(7), environ(7), standards(7)

Notes

If ps is not a null pointer, wcsrtombs() and wcsnrtombs() use the mbstate_t object pointed to by ps and the function can be used safely in multithreaded applications. If ps is a null pointer, wcsrtombs() and wcsnrtombs() use their internal mbstate_t object and the functions are Unsafe in multithreaded applications.

The wcsrtombs() function can be used safely in multithreaded applications.

The wcsrtombs_s() function cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.