char*-to-string

$Revision: 5.0.2.5 $

Function

Package: FOREIGN-FUNCTIONS

Arguments: (address &optional string make-string-p)

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

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

Users are encouraged to use excl:string-to-native instead of ff:string-to-char* for new code. See also excl:string-to-native and excl: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. ff: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.

ff: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 non-nil, 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 foreign_functions.htm for general information on foreign functions in Allegro CL. See ftype.htm for information on foreign types.

The general documentation description is in introduction.htm. The index is in index.htm.