char*-to-string

Function

Package: ff

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.

The remainder of this description is the old documentation for char*-to-string.

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 foreign-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 wchar*-to-string should be used to copy double byte characters from foreign space. The function is described in iacl.htm.

See ftype.htm for information on foreign types in Allegro CL and foreign-functions.htm for general information on foreign functions in Allegro CL.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.