ifx_gl_getmb - get a single multi-byte character

SYNOPSIS

#include <ifxgls.h>

int ifx_gl_fgetmb(gl_mchar_t *mb, 
                  int (*funcp)(void *v), void *v, 
                  int *bytes_got);

DESCRIPTION

This function calls the user defined function funcp to obtain bytes which are used to form one multi-byte character. This multi-byte character is then written to mb. The pointer v will be passed to funcp each time it is called.

The function funcp must defined as follows: 

       int funcp(void *v)
On success funcp should return a value between 0 and 255, inclusive, which is the next byte of the multi-byte character. On failure funcp should return -1.

This function will call funcp until one of the following occurs:

  1. a complete multi-byte character has been formed
  2. funcp returns a byte that forms an illegal character when appended to the bytes already read.
  3. funcp fails.
All bytes obtained by calling funcp are guaranteed to be written to mb.

The number of bytes successfully read by funcp will be returned in bytes_got (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]
The bytes read from funcp do not form a valid multi-byte character
[IFX_GL_EINVAL]
funcp returned -1 in the middle of an otherwise valid multi-byte character
[IFX_GL_EOF]
funcp returned -1 on the first call

MEMORY MANAGEMENT

This function assumes that mb contains enough space to hold the result. There are two ways to determine the number of bytes that will be written to mb.

The function ifx_gl_mb_loc_max() calculates the maximum number of bytes in any multi-byte character for the current locale.

The macro IFX_GL_MB_MAX is the maximum number of bytes in any multi-byte character in any locale. This value will always be equal to or greater than the value returned by ifx_gl_mb_loc_max().

Of the two options, the macro IFX_GL_MB_MAX is the fastest and the only one that can be used to initialize static buffers. The function ifx_gl_mb_loc_max() is slower, but more precise.

SEE ALSO

ifx_gl_putmb()

ACKNOWLEDGEMENT

Portions of this description were derived from the X/Open CAE Specification: "System Interfaces and Headers, Issue 4"; X/Open Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company Ltd., U.K.