ifx_gl_putmb

ifx_gl_putmb - put a single multi-byte character

SYNOPSIS

#include <ifxgls.h>

int ifx_gl_putmb(gl_mchar_t *mb, int mb_byte_limit, 
             int (*funcp)(gl_mchar_t byte, void *v), void *v,
             int *bytes_put);

DESCRIPTION

This function calls the user defined function funcp with each byte of the multi-byte character, mb. The pointer v will be passed to funcp each time it is called.

If mb_byte_limit is IFX_GL_NO_LIMIT then this function will read as many bytes as necessary from mb to form a complete character; otherwise, it will not read more than mb_byte_limit bytes from mb when trying to form a complete character. See Multi-Byte Character Termination for more general information about mb_byte_limit.

The funcp function must be defined as follows:

int funcp(gl_mchar_t byte, void *v)

funcp must return zero upon success or -1 upon failure. The number of bytes successfully put with funcp will be returned in bytes_put (even when failure is returned).

RETURN VALUES

This function will return either zero upon success or -1 upon failure.

ERRORS

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

[IFX_GL_EILSEQ]: mb is not a valid multi-byte character
[IFX_GL_EINVAL]: The function cannot determine whether mb is a valid multi-byte character, because it would need to read more than mb_byte_limit bytes from mb. If mb_byte_limit is less than or equal to zero, this function always gives this error. See Keeping Multi-Byte Strings Consistent for more information about this error.
[IFX_GL_EIO]: funcp returned -1 when called

ACKNOWLEDGEMENT