mbrtowc(3) [netbsd man page]
MBRTOWC(3) BSD Library Functions Manual MBRTOWC(3) NAME
mbrtowc -- converts a multibyte character to a wide character (restartable) LIBRARY
Standard C Library (libc, -lc) SYNOPSIS
#include <wchar.h> size_t mbrtowc(wchar_t * restrict pwc, const char * restrict s, size_t n, mbstate_t * restrict ps); DESCRIPTION
The mbrtowc() usually converts the multibyte character pointed to by s to a wide character, and stores the wide character to the wchar_t object pointed to by pwc if pwc is non-NULL and s points to a valid character. The conversion happens in accordance with, and changes the conversion state described in the mbstate_t object pointed to by ps. This function may examine at most n bytes of the array beginning from s. If s points to a valid character and the character corresponds to a nul wide character, then the mbrtowc() places the mbstate_t object pointed to by ps to an initial conversion state. Unlike mbtowc(3), the mbrtowc() may accept the byte sequence pointed to by s not forming a complete multibyte character but which may be part of a valid character. In this case, this function will accept all such bytes and save them into the conversion state object pointed to by ps. They will be used at subsequent calls of this function to restart the conversion suspended. The behaviour of mbrtowc() is affected by the LC_CTYPE category of the current locale. These are the special cases: s == NULL mbrtowc() sets the conversion state object pointed to by ps to an initial state and always returns 0. Unlike mbtowc(3), the value returned does not indicate whether the current encoding of the locale is state-dependent. In this case, mbrtowc() ignores pwc and n, and is equivalent to the following call: mbrtowc(NULL, "", 1, ps); pwc == NULL The conversion from a multibyte character to a wide character has taken place and the conversion state may be affected, but the resulting wide character is discarded. ps == NULL mbrtowc() uses its own internal state object to keep the conversion state, instead of ps mentioned in this manual page. Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of mbrtowc(), which is initial- ized at startup time of the program. RETURN VALUES
In the usual cases, mbrtowc() returns: 0 The next bytes pointed to by s form a nul character. positive If s points to a valid character, mbrtowc() returns the number of bytes in the character. (size_t)-2 s points to a byte sequence which possibly contains part of a valid multibyte character, but which is incomplete. When n is at least MB_CUR_MAX, this case can only occur if the array pointed to by s contains a redundant shift sequence. (size_t)-1 s points to an illegal byte sequence which does not form a valid multibyte character. In this case, mbrtowc() sets errno to indicate the error. ERRORS
mbrtowc() may cause an error in the following case: [EILSEQ] s points to an invalid or incomplete multibyte character. [EINVAL] ps points to an invalid or uninitialized mbstate_t object. SEE ALSO
mbrlen(3), mbtowc(3), setlocale(3) STANDARDS
The mbrtowc() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, Amendment 1''). The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99''). BSD
February 4, 2002 BSD
Check Out this Related Man Page
MBRLEN(3) BSD Library Functions Manual MBRLEN(3) NAME
mbrlen -- get number of bytes in a multibyte character (restartable) LIBRARY
Standard C Library (libc, -lc) SYNOPSIS
#include <wchar.h> size_t mbrlen(const char * restrict s, size_t n, mbstate_t * restrict ps); DESCRIPTION
The mbrlen() function usually determines the number of bytes in a multibyte character pointed to by s and returns it. This function shall only examine max n bytes of the array beginning from s. mbrlen() is equivalent to the following call (except ps is evaluated only once): mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal); Here, internal is an internal state object. In state-dependent encodings, s may point to the special sequence bytes to change the shift-state. Although such sequence bytes corresponds to no individual wide-character code, these affect the conversion state object pointed to by ps, and the mbrlen() treats the special sequence bytes as if these are a part of the subsequent multibyte character. Unlike mblen(3), mbrlen() may accept the byte sequence when it is not a complete character but possibly contains part of a valid character. In this case, this function will accept all such bytes and save them into the conversion state object pointed to by ps. They will be used on subsequent calls of this function to restart the conversion suspended. The behaviour of mbrlen() is affected by the LC_CTYPE category of the current locale. These are the special cases: s == NULL mbrlen() sets the conversion state object pointed to by ps to an initial state and always returns 0. Unlike mblen(3), the value returned does not indicate whether the current encoding of the locale is state-dependent. In this case, mbrlen() ignores n. n == 0 In this case, the first n bytes of the array pointed to by s never form a complete character. Thus, mbrlen() always returns (size_t)-2. ps == NULL mbrlen() uses its own internal state object to keep the conversion state, instead of ps mentioned in this manual page. Calling any other functions in Standard C Library (libc, -lc) never changes the internal state of mbrlen(), except for calling setlocale(3) with a changing LC_CTYPE category of the current locale. Such setlocale(3) calls cause the internal state of this function to be indeterminate. This internal state is initialized at startup time of the program. RETURN VALUES
The mbrlen() returns: 0 s points to a nul byte (' '). positive The value returned is a number of bytes for the valid multibyte character pointed to by s. There are no cases that this value is greater than n or the value of the MB_CUR_MAX macro. (size_t)-2 s points to the byte sequence which possibly contains part of a valid multibyte character, but which is incomplete. When n is at least MB_CUR_MAX, this case can only occur if the array pointed to by s contains a redundant shift sequence. (size_t)-1 s points to an illegal byte sequence which does not form a valid multibyte character. In this case, mbrtowc() sets errno to indicate the error. ERRORS
mbrlen() may cause an error in the following case: [EILSEQ] s points to an invalid multibyte character. [EINVAL] ps points to an invalid or uninitialized mbstate_t object. SEE ALSO
mblen(3), mbrtowc(3), setlocale(3) STANDARDS
The mbrlen() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, Amendment 1''). The restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99''). BSD
February 3, 2002 BSD