The standard C string type is not sufficient for handling the dynamic nature of D3 strings, so a hybrid data type has been created called CPSTR. This data type provides allocation, deallocation, and resizing of strings at a much higher performance level than that obtained using malloc() and free() with C strings.
The structure of a CPSTR is:
|Header||Internal use only-do not modify.|
|String||Character array containing the actual string.|
|Terminator||A single character used for termination.|
|Footer||Internal use only-do not modify.|
The macros listed below are provided to access all desired portions of a CPSTR structure:
|_CP_SLEN(s)||Returns the current length of a string. This length does not include any terminating character such as a segment mark or a null character.|
|_CP_SADDR(s)|| Returns a (char *) to the actual string
data that may or may not be terminated by a 0x00. Note that this (char *) must not be passed to the free() C function or to any C function that may try to use free() on the (char *).
Allocation of CPSTR strings is accomplished via special allocation routines. CPSTR strings must not be allocated with the C function malloc(). The allocation routines provided set necessary internal flags, and are much more efficient than malloc().
Note: These routines create dynamic structures which must be deallocated with the routines listed below.
|_CP_str_alloc(l)||Returns a CPSTR of length l. The actual string data portion of the string is undefined.|
|_CP_mkstr(char *s)||Returns a CPSTR from a C string s terminated by a null character. The string portion of the CPSTR will contain a copy of the C string's data. This function is less efficient than _CP_mkstrl as it must scan the C string to determine its length.|
|_CP_mkstrl(char *s, int l)||Returns a CPSTR from a C string s, of length l. The string portion of the CPSTR will contain a copy of the C string's data.|
|_CP_str_realloc(CPSTR **s, int l)||Resizes the CPSTR s.|
|_CP_str_free(CPSTR ** s)||Frees the desired string s.|
When the _CP_logoff call is executed, all CPSTRs remain valid, but they cannot be passed to any of the _CP_ routines. All CPSTRs are properly cleaned up when the C program exits.
It is necessary to free strings only when the user has finished with them completely. All resizing of strings is accomplished automatically by the _CP_ routines. For example, if a process repeatedly reads data into a buffer via the _CP_read call, this buffer will be automatically resized to fit the new data within the _CP_read call at every read.
The user must be careful with termination. Any _CP_ routine may modify the termination character. Therefore, the user must use the _CP_TERM() macro to terminate CPSTRs with a 0x00 if it is necessary to pass the string portion of it to a standard UNIX routine.