%PAGEREF%(MinGW)

NAME
mbsinit - check state of multibyte to wide character conversion

SYNOPSIS
#include <wchar.h>

int mbsinit( mbstate_t *ps );

DESCRIPTION
If ps is not a NULL pointer, the mbsinit() function determines whether the mbstate_t object, to which it points, represents a multibyte to wide character conversion in the initial, or in an intermediate state.

The initial conversion state is represented by a zero-valued mbstate_t object. (POSIX.1 stipulates that this representation must be supported, although additional alternative representations are permitted; MinGW uses only the zero-valued representation).

In MinGW, an initial conversion state may be establised by initialization:

        mbstate_t st = (mbstate_t)(0), *ps = &st;

or by assignment:

        *ps = (mbstate_t)(0);

However, for portability:

        memset( ps, 0, sizeof( mbstate_t ));

may be preferred.

Nominally, mbstate_t objects represent shift states of the active codeset. However, since MS-Windows codesets do not use shift states, as such, MinGW uses mbsinit_t odjects to represent an alternative class of intermediate conversion states, viz.:

    •   Parsing of a multibyte sequence has been interrupted, before interpretation of MB_CUR_MAX bytes, without identification of a complete code point; this conversion state may arise following a call of mbrlen(3), or mbrtowc(3), which has returned a parsed sequence length of (size_t)(-2).

    •   Processing of a wide character sequence has encountered a high surrogate, but the complementary low surrogate has yet to be evaluated; this state may arise after a call of mbrtowc(3), has returned the high surrogate, (with a returned sequence length between one and MB_CUR_MAX), and a further call is needed, to retrieve the low surrogate; alternatively, a complementary conversion state may arise when wcrtomb(3) has been called to interpret a high surrogate, and a further call, to complete the conversion to a multibyte sequence, by evaluation of the complementary low surrogate, is still required.

RETURN VALUE
If ps is a NULL pointer, or if the conversion state, represented by the mbstate_t object to which it points, is the initial state, mbsinit() returns a non-zero value; otherwise, zero is returned, indicating an intermediate conversion state.

ERROR CONDITIONS
No error conditions are defined.

STANDARDS CONFORMANCE
There is no Microsoft implementation of the mbsinit() function, which is readily accessible for use in MinGW applications; the libmingwex implementation conforms generally to ISO-C99, POSIX.1-2001, and POSIX.1-2008.

CAVEATS AND BUGS
Prior to mingwrt-5.3, the libmingwex implementation of mbsinit() would always return non-zero, apparently indicating an initial conversion state, regardless of the actual state indicated by any mbstate_t object referred to by *ps; this defect is corrected, in mingwrt-5.3.

Any intermediate conversion state, arising from a call to mbrlen(3), mbrtowc(3), or wcrtomb(3), is specific to the particular conversion which produces it. Any intermediate state produced by mbrlen(3), or by mbrtowc(3) may be resolved by a further call to either of these two functions, or to mbsrtowcs(3), provided the initial part of the multibyte sequence, passed in the subsequent call, completes the sequence which led to the intermediate state; if this intermediate state is used in any other context, the consequent behaviour is undefined.

Similarly, an intermediate state resulting from a call to wcrtomb(3) may be resolved by a further call to wcrtomb(3), or to wcsrtomb(3), provided the first, (or the only), wide character to be interpreted, in the subsequent call, represents the low surrogate which completes the pending surrogate pair from which the intermediate state was created. Once again, if this intermediate state is used in any other context, the consequent behaviour is undefined.

SEE ALSO
mbrlen(3), mbrtowc(3), mbsrtowcs(3), wcrtomb(3), and wcrtomb(3).

AUTHOR
This manpage was written by Keith Marshall, <keith@users.osdn.me>, to document the mbsinit() 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.