%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 );

    Feature Test Macro Requirements for libmingwex:

__MSVCRT_VERSION__: since mingwrt-5.3, if this feature test macro is defined, with a value of at least 0x0800, (corresponding to the symbolic constant, __MSCVR80_DLL, and thus declaring intent to link with MSVCR80.DLL, or any later version of Microsoft's non-free runtime library, instead of with MSVCRT.DLL), calls to wcsrtombs() will be directed to the implementation thereof, within Microsoft's runtime DLL.

_ISOC99_SOURCE, _ISOC11_SOURCE: since mingwrt-5.3.1, when linking with MSVCRT.DLL, or when __MSVCRT_VERSION__ is either undefined, or is defined with any value which is less than 0x0800, (thus denying intent to link with MSVCR80.DLL, or any later non-free version of Microsoft's runtime library), explicitly defining either of these feature test macros will cause any call to wcsrtombs() to be directed to the libmingwex implementation; if neither macro is defined, calls to wcsrtombs() will be directed to Microsoft's runtime implementation, if it is available, otherwise falling back to the libmingwex implementation.

Prior to mingwrt-5.3, none of the above feature test macros have any effect on wcsrtombs(); all calls will be directed to the libmingwex implementation.

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; (prior to mingwrt-5.3, and in those cases where calls may be delegated to a Microsoft runtime DLL implementation, this level of conformity may not be achieved).

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.