WCSRTOMBS

NAME

wcsrtombs - convert a wide character string to a multibyte string

SYNOPSIS

#include <wchar.h>

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

DESCRIPTION

If fIdestfP is not a NULL pointer, the fBwcsrtombsfP function converts the wide-character string fI*srcfP to a multibyte string starting at fIdestfP. At most fIlenfP bytes are written to fIdestfP. The shift state fI*psfP is updated. The conversion is effectively performed by repeatedly calling wcrtomb(fIdestfP,fI*srcfP,fIpsfP), as long as this call succeeds, and then incrementing fIdestfP by the number of bytes written and fI*srcfP by one. The conversion can stop for three reasons:

1. A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case fI*srcfP is left pointing to the invalid wide character, (size_t)(-1) is returned, and errno is set to fBEILSEQfP.

2. The length limit forces a stop. In this case fI*srcfP is left pointing to the next wide character to be converted, and the number of bytes written to fIdestfP is returned.

3. The wide-character string has been completely converted, including the terminating L' ' (which has the side effect of bringing back fI*psfP to the initial state). In this case fI*srcfP is set to NULL, and the number of bytes written to fIdestfP, excluding the terminating ' ' byte, is returned.

If fIdestfP is NULL, fIlenfP is ignored, and the conversion proceeds as above, except that the converted bytes are not written out to memory, and that no length limit exists.

In both of the above cases, if fIpsfP is a NULL pointer, a static anonymous state only known to the wcsrtombs function is used instead.

The programmer must ensure that there is room for at least fIlenfP bytes at fIdestfP.

RETURN VALUE

The fBwcsrtombsfP function returns the number of bytes that make up the converted part of multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted, (size_t)(-1) is returned, and errno set to fBEILSEQfP.

CONFORMING TO

ISO/ANSI C, UNIX98

NOTES

The behaviour of fBwcsrtombsfP depends on the LC_CTYPE category of the current locale.

Passing NULL as fIpsfP is not multi-thread safe.