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. |