Character-string termination

The API that you use with the library might handle string termination in either of the following ways:

All character strings are terminated with a null character.
The null character indicates the end of the string. Such strings are called null-terminated strings. The null terminator of a multibyte string consists of one byte whose value is 0. The null terminator of a wide-character string consists of one gl_wchar_t character whose value is 0.
Each string consists of a pointer and length that indicates the number of bytes in the string.
Character strings that are not null-terminated are called length-terminated strings. Length-terminated strings can contain null characters, but these null characters do not indicate the end of the string.

The functions that take a string argument allow you to pass this string as either a null-terminated string or a length-terminated string. To provide this flexibility, many functions that accept a multibyte or wide-character string expect the string to be represented with the following two arguments:

The string itself
The length of the string

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


String-length value	Meaning
IFX_GL_NULL	The function assumes that the string is a null-terminated string.
>=0	The function assumes that this length indicates the number of bytes in the length-terminated string.
<0, != IFX_GL_NULL	The function sets the error number to the IFX_GL_PARAMERR error.