ifx_gl_mbsncpy

ifx_gl_mbsncpy - copy part of a multi-byte string

SYNOPSIS

#include <ifxgls.h>
int ifx_gl_mbsncpy(gl_mchar_t *mbs1, gl_mchar_t *mbs2, int mbs2_byte_length, int char_limit)

DESCRIPTION

This function copies mbs2 to the location pointed to by mbs1. No more than char_limit characters will be read from mbs2 and written to mbs1. If mbs1 and mbs2 overlap, the results of this function are undefined.

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

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

RETURN VALUES

This function returns the number of bytes in the resulting copied string, not including the null terminator, if any.

ERRORS

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

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

ACKNOWLEDGEMENT