FunctionPackage: ffToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.0 version


Arguments: address &optional string make-string-p

This function is obsolete. It has been replaced by native-to-string. A call to char*-to-string is converted to

(excl:native-to-string address 
                       :string string
                       :make-string? make-string-p
                       :external-format :default)

Users are encouraged to use native-to-string instead of char*-to-string for new code. See also string-to-native and with-native-string. Using native-to-string means fewer modules need be present in an image using this functionality.

The remainder of this description is the old documentation for char*-to-string. The function is defined in the :ffcompat module which is not present in an image by default.

This function returns a Lisp string. address should be a integer returned by a foreign function. char*-to-string converts a C string to a Lisp string by copying the elements of the C character array into a newly allocated Lisp string. A C string is really just an array of characters ending with a null character.

char*-to-string takes a second, optional, string argument which if given should be a string large enough to hold the contents of the char*. If the string is long enough, then it is used to store the char*. If the given string isn't long enough, an error will be signaled, unless a third argument is given and is true, in which case a long enough string will be created (but string will not be used).

If the second argument, a string, is given then the following should be noted: The string must be a simple string. If the string is long enough then it will be filled with the characters pointed to by the char*. The null terminating character will not be stored in the string. After char*-to-string is run, the size of the lisp string will be unchanged. In order to determine the length of the string copied the program can either call char*-strlen on the char* value, or it can fill the string with #\null's before calling char*-to-string.

Note to users of International Allegro Common Lisp (see iacl.htm): This function will only copy single byte character from foreign space. However the characters will be stored correctly in double-byte Lisp character strings. The function native-to-string should be used to copy double byte characters from foreign space. The function is described in iacl.htm.


Created 2009.7.29.

Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.0 version