Chapter 14: The Old-Style C IO System

Multibyte/Wide-Character Conversion Functions

The standard library supplies various functions that support conversions between multibyte and wide characters. These functions, shown in the following table, use the header <wchar.h>. Many of these functions are restartable versions of the normal multibyte functions. The restartable version utilizes the state information passed to it in a parameter of type mbstate_t. If this parameter is null, the function will provide its own mbstate_t object.

Function	Description
win_t btowc(int ch)	Converts ch into its wide-character equivalent and returns the result. Returns WEOF on error or if ch is not a one-byte, multibyte character.
size_t mbrlen(const char *str, size_t num,                        mbstate_t *state)	Restartable version of mblen( ) as described by state. Returns a positive value that indicates the length of the next multibyte character. Zero is returned if the next character is null. A negative value is returned if an error occurs. In C99, str and state are qualified by restrict.
size_t mbrtowc(wchar_t *out,                           const char *in, size_t num,                           mbstate_t *state)	Restartable version of mbtowc( ) as described by state. Returns a positive value that indicates the length of the next multibyte character. Zero is returned if the next character is null. A value of –1 is returned if an error occurs and the macro EILSEQ is assigned to errno. If the conversion is incomplete, –2 is returned. In C99, out, in, and state are qualified by restrict.
int mbsinit(const mbstate_t *state)	Returns true if state represents an initial conversion state.
size_t mbsrtowcs(wchar_t *out,                               const char **in,                               size_t num,                               mbstate_t state)	Restartable version of mbstowcs( ) as described by state. Also, mbsrtowcs( ) differs from mbstowcs( ) in that in is an indirect pointer to the source array. If an error occurs, the macro EILSEQ is assigned to errno. In C99, out, in, and state are qualified by restrict.
size_t wcrtomb(char *out, wchar_t ch,                           mbstate_t *state)	Restartable version of wctomb( ) as described by state. If an error occurs, the macro EILSEQ is assigned to errno. In C99, out and state are qualified by restrict.
size_t wcsrtombs(char *out,                               const wchar_t **in,                               size_t num,                               mbstate_t *state)	Restartable version of wcstombs( ) as described by state. Also, wcsrtombs( ) differs from wcstombs( ) in that in is an indirect pointer to the source array. If an error occurs, the macro EILSEQ is assigned to errno. In C99, out, in, and state are qualified by restrict.
int wctob(wint_t ch)	Converts ch into its one-byte multibyte equivalent. It returns EOF on failure.