ifx_gl_mbstowcs

ifx_gl_mbstowcs - convert a multi-byte character string to its wide-character representation

SYNOPSIS

#include <ifxgls.h>
int ifx_gl_mbstowcs(gl_wchar_t *wcsp, gl_mchar_t *mbs, int mbs_byte_length, int char_limit);

DESCRIPTION

This function converts mbs into its wide-character representation and stores the result in the location pointed to by wcsp. No more than char_limit characters will be read from mbs and written to wcsp.

If mbs_byte_length is the value IFX_GL_NULL then the function will assume that mbs is a null-terminated string; otherwise the function assumes that mbs_byte_length is the number of bytes in mbs. See Multi-Byte Character String Termination for more general information about mbs_byte_length.

If mbs_byte_length is equal to IFX_GL_NULL then the function will null-terminate the string stored in wcsp; otherwise it will not.

RETURN VALUES

This function returns the number of characters read from mbs and the number of characters written to wcsp, not counting the null-terminator.

ERRORS

If an error has occurred, this function returns -1 and sets ifx_gl_lc_errno() to one of the following,

[IFX_GL_PARAMERR]: mbs_byte_length is not equal to IFX_GL_NULL and is not greater than or equal to zero.
[IFX_GL_EILSEQ]: mbs contains an invalid multi-byte character
[IFX_GL_EINVAL]: The function cannot determine whether the last character of mbs is a valid multi-byte character, because it would need to read more than mbs_byte_length bytes from mbs. See Keeping Multi-Byte Strings Consistent for more information about this error.

ACKNOWLEDGEMENT