Multibyte-character termination

Many GLS library functions operate on just one multibyte character. Each function that accepts a multibyte character expects the character to be represented by the following two arguments:

• The character itself
• The maximum length of the character

The value that you provide for the character length tells the function how to handle the associated character, as the following table shows.

String-length value	Meaning
IFX_GL_NO_LIMIT	The function reads as many bytes as necessary from the multibyte character to form a complete character.
>=0	The function does not read more than this number of bytes from the multibyte character when it tries to form a complete character.
<0, != IFX_GL_NO_LIMIT	The function sets the error number to the IFX_GL_EINVAL error.

If the multibyte character is in a null-terminated multibyte string, the character length must be IFX_GL_NO_LIMIT. For example, if mbs points to a null-terminated string of multibyte characters, the following code fragment must specify IFX_GL_NO_LIMIT as the character length:

for ( mb = mbs; *mb != '\0'; mb += bytes )
    {
    if ( (bytes = ifx_gl_mblen(mb, IFX_GL_NO_LIMIT)) == -1 )
        /* handle error */
    }

If a multibyte character, mb, is in a length-terminated multibyte string or is a character in a buffer by itself, the character length must equal the number of bytes between where mb points and the end of the buffer that holds the string or character. For example, if mbs points to a length-terminated string of multibyte characters and mbs_bytes is the number of bytes in that string, the following call to ifx_gl_mblen() must specify the length of the multibyte string:

for ( mb = mbs; mbs_bytes > 0; mb += bytes,
        mbs_bytes -= bytes )
    {
    if ( (bytes = ifx_gl_mblen(mb, mbs_bytes)) == -1 )
        /* handle error */
    }

Similarly, if mb points to one multibyte character and mb_bytes is the number of bytes in the buffer that holds the character, the following call to ifx_gl_mblen() must specify the length of the multibyte character:

if ( (bytes = ifx_gl_mblen(mb, mb_bytes)) == -1 )
    /* handle error */

If the function cannot determine whether bytes in a buffer make up a valid multibyte character, it sets the error number to IFX_GL_EINVAL. The function is unable to determine a valid multibyte character for the following reasons:

• The function would need to read more than the specified number of bytes to recognize a multibyte character.
• The specified character length is less than or equal to zero (<=0).