wcsrtombs(), wcsnrtombs(), wcsrtombs_l(), wcsnrtombs_l() -- convert wide character string to multibyte string (restartable)

SYNOPSIS

#include <wchar.h>

size_t wcsrtombs(char *dst, const wchar_t **src, size_t len, mbstate_t *ps);

size_t wcsnrtombs(char *dst, const wchar_t **src, size_t nwc, size_t len, mbstate_t *ps);

#include <locale.h>

size_t wcsrtombs_l(char *dst, const wchar_t **src, size_t len, mbstate_t *ps, locale_t locale);

size_t wcsnrtombs_l(char *dst, const wchar_t **src, size_t nwc, size_t len, mbstate_t *ps, locale_t locale);

The wcsrtombs() class of functions convert a sequence of wide characters, beginning in the specified conversion state, from the array indirectly pointed to by src into a sequence of corresponding characters. If dst is not a null pointer, the converted characters are 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 early in either of the following cases:

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

When the next character would exceed the limit of len total bytes stored into 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 the specified state pointer is null, the wcsrtombs() function uses its own internal mbstate_t object, which is initialized at program startup to the initial conversion state. Otherwise, the specified mbstate_t object is used to completely describe the current conversion state of the associated character sequence.

The behavior of this function is affected by the LC_CTYPE category of the current locale.

The wcsnrtombs() function behaves identically to wcsrtombs(), except that conversion stops after reading at most nwc characters from the buffer pointed to by src.

wcsrtombs_l() and wcsnrtombs_l() behaves in the same way as wcsrtombs() and wcsnrtombs() without the _l suffix, but use the specified locale rather than the global or per-thread locale. A locale_t is returned by newlocale().

PARAMETERS

dst: Is the destination buffer used to receive converted characters. This can be a null pointer if no conversion is desired.
src: Points to the string to be converted. If dst is not null, the referenced pointer is updated as described in the DESCRIPTION section.
nwc: Stop after processing nwc characters from the src characters.
len: Is the maximum number of bytes characters to write to dst, if dst is not null.
ps: Is the conversion state. If this is null, an internal mbstate_t object is used.
locale: Is a locale_t perhaps returned by newlocale() or LC_GLOBAL_LOCALE or 0 for the current thread locale set with uselocale().

RETURN VALUES

If the input conversion encounters a code that does not correspond to a valid character, an encoding error occurs. In this case, the wcsrtombs() class of functions set errno to EILSEQ and returns -1; the conversion state is undefined. Otherwise, it returns the number of bytes successfully converted, not including the terminating null (if any).

CONFORMANCE

wcsrtombs() conforms to ANSI/ISO 9899:1990 'ISO C90'.

wcsrtombs_l() conforms to ANSI/ISO 9899:1999 'ISO C99'.

wcsnrtombs() and wcsnrtombs_l() are BSD UNIX extensions.

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The function wcsrtombs() and wcsnrtombs() are MT-Safe as long as no thread calls setlocale() while these functions are executing.

The function wcsrtombs_l() wcsnrtombs_l() are MT-Safe as long as no thread calls freelocale() on locale while these functions are executing.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

wcsrtombs(), wcsnrtombs(), wcsrtombs_l(), wcsnrtombs_l()
convert wide character string to multibyte string (restartable)

Function