octets-to-native

Arguments: vector8 &key address aligned (length (position 0 vector8)) (null-terminate t) result-vector

This function was modified by a patch which added the two additional keyword arguments null-terminate and result-vector. Behavior of this function if those arguments are unspecified has not changed. The documentation assumes the patch has been applied. (The patch is for version 10.0 only. Earlier versions are not changed.)

This function returns an address when result-vector is nil and returns result-vector when that argument is non-nil.

This function copies the 8-bit bytes from vector8, a (simple-array (unsigned-byte 8) (*)) array, into one of the following locations, based on the arguments:

• static (i.e., non-Lisp heap) memory, when address and result-vector are unspecified or nil. The address of the first character of the copied data is returned.
the location specified by address, when address is non-nil and result-vector is unspecified or nil. address, which becomes the location of the first byte of the copied data, is returned.
result-vector, when result-vector is non-nil (address is ignored when result-vector is non-nil). result-vector is returned.

If the address argument is specified, it must be an integer specifying an address. The address may be in the Lisp heap, but note that in an SMP Lisp, addresses in the Lisp heap are not stable (the address may be valid when this function is called but a gc may happen while this function is running with the possible result that writing to the address can destroy Lisp data and cause Lisp failure). In non-SMP Lisps, it is possible to ensure that garbage collections do not occur while cons-free code is run but that is difficult to impossible in an SMP Lisp. More commonly, the address is in static space. The programmer must ensure that other data is not overwritten by the octets being copied when address is used. The system does no checking on its own. If result-vector is specified non-nil, address is ignored.

If address and result-vector are both unspecified or nil, new static memory is allocated. When no longer needed, the resulting memory must be passed to aclfree to be reclaimed.

If the aligned keyword argument is true, then address is an aligned address. Aligned addresses are returned by functions like lispval-to-aligned-malloc-address.

If the length argument is specified, then it specifies the number of elements to copy.

If result-vector is specified and not nil, it must be an octet vector, i.e. a (simple-array (unsigned-byte 8) (*)). vector8 will be copied to that vector. If result-array is in the Lisp heap, Care should be taken not to take the address of the result vector (e.g. with lispval-to-address) until there is no chance for a gc (again, this is hard to do in an SMP Lisp). This is not an issue if result-vector is a static array --see Static arrays in gc.htm.

The null-terminate argument controls whether a single 0 octet is appended at the end of the copied bytes. null-terminate defaults to t. :null-terminate nil can be specified to prevent the addition of the null-terminating octet. If null-terminate is nil, then the length keyword must also be specified.

In earlier releases, this function was called mb-to-native. That name is preserved for backward compatibility, but new code should use the new name.

See also iacl.htm for general information on international character set support in Allegro CL and see native-to-octets and string-to-native.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.