%PAGEREF%(MinGW)

NAME
wcsrtombs - convert a wide character to a multibyte sequence

SYNOPSIS
#include <wchar.h>

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

DESCRIPTION
The wcsrtombs() function converts a sequence of wide characters from the array which is indirectly pointed to by src, to a corresponding multibyte character sequence in the codeset which is associated with the LC_CTYPE category of the active process locale, beginning in the conversion state which is represented by the mbstate_t object at *ps; each wide character is converted, as if by calling the wcrtomb(3) function.

Conversion continues until:

    •   A wide character which is invalid in its own context is encountered.

    •   A wide character which does not have a valid representation within the target multibyte codeset is encountered.

    •   The NUL wide character is encountered, while in the initial conversion state.

    •   The dst argument is not a NULL pointer, and a wide character is encountered for which the converted length would cause the aggregate length of the converted multibyte character string to exceed the limit specified by the len argument.

If dst is not a NULL pointer, the multibyte character string resulting from successful conversion, up to a maximum of len bytes, is stored in the multibyte array starting at dst. If the conversion is NUL terminated, the wide character string reference pointed to by src is replaced by a NULL pointer; otherwise it is updated to point to the address immediately following that of the last wide character converted.

If dst is a NULL pointer, the aggregate count of bytes required to represent the conversion is accumulated, until any one of the preceding termination conditions is encountered; the len argument, and the termination condition which is dependent upon it, is ignored, and the conversion is not stored.

If ps is a NULL pointer, the wcsrtombs() function uses a static internal mbstate_t object, which is known only to, and visible only within the scope of execution of, the wcsrtombs() function itself.

Following a successful conversion, the mbstate_t object at *ps, or the internal mbstate_t object if appropriate, is reset to the initial conversion state.

RETURN VALUE
When conversion is successful, and dst is not a NULL pointer, the wcsrtombs() function returns the number of bytes stored at dst, to represent the resulting multibyte character sequence, excluding the terminating NUL, (if any).

Conversely, when conversion is successful, but dst is a NULL pointer, the wcsrtombs() function returns the number of bytes which would be required to store the entire multibyte character string resulting from the successful conversion, excluding the terminating NUL.

ERROR CONDITIONS
If conversion is unsuccessful, errno is set to EILSEQ, the wcsrtombs() function returns (size_t)(-1), and the conversion state is unspecified.

STANDARDS CONFORMANCE
Except in respect of its extended provision for handling of surrogate pairs, and to the extent that it may be affected by limitations of the underlying MS-Windows API, the libmingwex implementation of wcsrtombs() conforms generally to ISO-C99, POSIX.1-2001, and POSIX.1-2008.

CAVEATS AND BUGS
Due to a documented limitation of Microsoft's setlocale() function implementation, it is not possible to directly select an active locale, in which the codeset is represented by any multibyte character sequence with an effective MB_CUR_MAX of more than two bytes. Prior to mingwrt-5.3, this limitation precludes the use of wcsrtombs() to convert to any codeset with MB_CUR_MAX greater than two bytes, (such as UTF-8). From mingwrt-5.3 onward, the MinGW.org implementation of wcsrtombs() mitigates this limitation by assignment of the codeset from the LC_CTYPE environment variable, provided the system default has been previously activated for the LC_CTYPE locale category; e.g. execution of:

        #define _ISOC99_SOURCE
        #include <stdio.h>
        #include <stdlib.h>
        #include <locale.h>
        #include <wchar.h>
        void print_conv( const wchar_t * );
        int main()
        {
          setlocale( LC_CTYPE, "" );
          putenv( "LC_CTYPE=en_GB.65001" );
          print_conv( L"\u6c34\U0001d10b" );
          return 0;
        }
        void print_conv( const wchar_t *wcs )
        {
          size_t len;
          if( (len = 1 + wcsrtombs( NULL, &wcs, 0, NULL )) > 0 )
          {
            const wchar_t *wc = wcs;
            size_t n = 1 + wcslen( wcs );
            unsigned char mbs[len], *mb = mbs;
            printf( "UTF-16: %u value%s: ", n, (n == 1) ? "" : "s" );
            do { printf( "0x%04X%c", *wc, (*wc == L'\0') ? '\n' : ':' );
               } while( *p++ != L'\0' );
            printf( "UTF-8: %u byte%s: ",
                1 + wcsrtombs( mbs, &wcs, len, NULL ),
                (len == 1) ? "" : "s"
              );
            do { printf( "0x%02X%s", *mb, (*mb == '\0') ? '\n' : ':' );
               } while( *mb++ != '\0' );
          }
          else perror( "wcsrtombs" );
        }

will select UTF-8 as the target codeset, then convert the L"\u6c34\U0001d10b" wide character string, resulting in the output:

        UTF-16: 4 values: 0x6C34:0xD834:0xDD0B:0x0000
        UTF-8: 8 bytes: 0xE6:0xB0:0xB4:0xF0:0x9D:0x84:0x8B:0x00

SEE ALSO
mbsinit(3), and wcrtomb(3)

AUTHOR
This manpage was written by Keith Marshall, <keith@users.osdn.me>, to document the wcsrtombs() function as it has been implemented for the MinGW.org Project. It may be copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by the original author remains in place.