1. GLS Library String and Character Termination

Therefore, each of the GLS library functions that take a string argument allow you to pass them either a null-terminated string, or a string whose end is determined by the separate length that you pass them.

Multi-Byte Character String Termination

  ..., mbs, mbs_byte_length, ...

Multi-byte character strings which are not null-terminated are called length-terminated multi-byte strings and can contain null characters, but these null characters do not indicate the end of the string.

If mbs_byte_length is neither IFX_GL_NULL nor greater than or equal to zero, then the function gives the IFX_GL_PARAMERR error.

Multi-Byte Character Termination

  ..., mb, mb_byte_limit, ...

1. If mb is a character in a null-terminated multi-byte string, then mb_byte_limit must be equal to IFX_GL_NO_LIMIT. For example, if mbs points to a string of multi-byte characters that are null terminated,

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

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

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

If 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 or if mb_byte_limit is less than or equal to zero, then the function gives the IFX_GL_EINVAL error.

Wide-Character String Termination

  ..., wcs, wcs_char_length, ...

Wide-character strings which are not null-terminated are called length-terminated wide-character strings and can contain null characters, but these null characters do not indicate the end of the string.

If wcs_char_length is neither IFX_GL_NULL nor greater than or equal to zero, then the function gives the IFX_GL_PARAMERR error.

2. GLS Library Memory Allocation

Memory Allocation by GLS Library Functions

Memory Allocation by GLS Library Callers

Multi-byte character string allocation

gl_mchar_t mbs[20*IFX_GL_MB_MAX];

gl_mchar_t *mbs = (gl_mchar_t *) malloc(20*IFX_GL_MB_MAX);

gl_mchar_t *mbs = (gl_mchar_t *) malloc(20*ifx_gl_mb_loc_max());

gl_mchar_t mbs[20*IFX_GL_MB_MAX+1];

gl_mchar_t *mbs = (gl_mchar_t *) malloc(20*IFX_GL_MB_MAX+1);

gl_mchar_t *p = (gl_mchar_t *) malloc(20*gl_mb_loc_max()+1);

Wide-Character String Allocation

gl_wchar_t wcs[20];

gl_wchar_t *wcs = (gl_wchar_t *) malloc(20*sizeof(gl_wchar_t));

gl_wchar_t wcs[21];

gl_wchar_t *wcs = (gl_wchar_t *) malloc(21*sizeof(gl_wchar_t));

3. Keeping Multi-Byte Strings Consistent

Truncating Long Multi-Byte Strings

However, truncating a string that can contain even one multi-byte character is difficult. This is because truncating at an arbitrary byte location in the string can result in truncating a multi-byte character in its middle such that the truncated string ends with the first 1, 2 or 3 bytes of a character without the character's remaining bytes.

If such a situation occurs, then subsequent traversal of the truncated string could result in reading beyond the end of the buffer.

Therefore, all GLS library functions which traverse one multi-byte character or traverse length-terminated multi-byte characters strings give a special error if they detect that an otherwise valid character has been truncated: IFX_GL_EINVAL.

If it is known that no truncation occurred to the string, then IFX_GL_EINVAL can be considered the same as IFX_GL_EILSEQ. However, if it is possible that truncation has occurred, then IFX_GL_EINVAL indicates to the caller that they need to further truncate the string so that the last byte of the string is the last byte of the last character in the string.

Depending upon your application, you may either end up making the truncated string even shorter than originally indented or you may have to replace the first 1, 2, or 3 bytes of the truncated character with a padding character that is appropriate for your application.

Even though the GLS library functions can be used to detect this situation after it has occurred, it is much better to use them to avoid the situation.

Fragmenting Long Multi-Byte Strings

However, fragmenting a string that can contain even one multi-byte character is difficult. This is because fragmenting at arbitrary byte locations in the string can result in fragmenting a multi-byte character in its middle such that one fragment ends with the first 1, 2 or 3 bytes of a character and the next fragment starts with the remaining bytes.

If the only thing you ever will do with these fragments is to concatenate them back together to form one string, then no special processing needs to be done. However, if you traverse the fragments as multi-byte strings, this can result in reading beyond the end of one fragment or finding an illegal character at the beginning of another.

Therefore, all GLS library functions which traverse one multi-byte character or traverse length-terminated multi-byte characters strings give a special error if they detect that an otherwise valid character has been truncated at the end of a fragment: IFX_GL_EINVAL. It is impossible to detect that the beginning of a fragment contains the remaining bytes of the last character in the previous fragment without looking at the previous fragment first. This is because the last 1, 2 or 3 bytes of a multi-byte character may look exactly like a valid character.

If it is known that no fragmentation occurred to the string, then IFX_GL_EINVAL can be considered the same as IFX_GL_EILSEQ. However, if it is possible that fragmentation has occurred, then IFX_GL_EINVAL indicates to the caller that they need to fragment the string so that the last byte of each fragment is the last byte of the last character in the fragment and so that the first byte of each fragment is the first byte of the first character in the fragment.

Depending upon your application, you may either end up making a fragment even shorter than originally indented or you may have to replace the first 1, 2, or 3 bytes of the fragmented character with a padding character that is appropriate for your application and shift these bytes to the beginning of the next fragment.

Even though the GLS library functions can be used to detect this situation after it has occurred, it is much better to use them to avoid the situation.

ACKNOWLEDGEMENT