Arguments: address offset pos type &optional coerce
This function and memref provide low-level memory access in Allegro CL. However, even though their names are exported and they are documented, we recommend against using them in user code. Instead, we recommend using higher-level functions, such as those linked to below. However, the function are useful in the development cycle for debugging purposes.
Each function calculates an address in memory and performs a read from that address. The width and style of the read depends upon the type.
These functions are setf-able. The setf functions write to the
addressed memory instead of reading. WARNING: except
when the type is :lisp, these
setf-functions do not do any setf-protection. If they are used to
store non-lisp values into a memory location that was intended to hold
a lisp value, then GC death will occur.
Some checking can be done. When the setf functions for memref and sys:memref-int are given an optional true fifth coerce argument, then runtime checking and coersion is done on the value before it is stored. This is especially useful when the argument is a float value, but of the wrong type, as in
(setf (sys:memref array 0 0 :double-float :coerce) 1.0s0)
Note that when this fifth argument is supplied, then the call is not open-coded when compiled.
object (the first argument of memref) can be any lisp object, whose address (including the tag bits) is used as the base for the memory access. address (the first argument of memref-int) can be any integer that represents a valid address in the lisp. The value of this address (which may be a bignum) is used as the base for the memory access.
offset and pos are equivalent and interchangeable. They are both added as byte-offsets to the base address to determine the final memory address. Usually, the offset is some constant that adjusts for the start of the data in the object being accessed. Some of the offsets for lisp objects are described in [Allegro directory]/misc/lisp.h in the Allegro CL distribution. In an earlier version of this documentation, it was stated that the offsets are available in Lisp itself by calling certain otherwise undocumented functions. That statement was incorrect. The offsets are not reliably available with Lisp.
The access-types that are available are as follows:
:unsigned-byte, :signed-byte (1-byte access, 1-byte integer result)
:unsigned-word, :signed-word (2-byte access, 2-byte integer result)
:unsigned-long, :signed-long
;; 4-byte access, 4-byte integer result in 32-bit lisps
;; undetermined (4-byte or 8-byte) in 64-bit lisps
:unsigned-long32 (4-byte access, 4-byte integer result)
:unsigned-long64 (8-byte access, 8-byte integer result on 64-bit
Lisps and Compaq Alpha and SGI32-bit Lisps
but 4-byte access, 4-byte integer result
on all others)
:fixnum (4-byte access, fixnum result [top bits lost on overflow])
:lisp (4-byte access, lisp result [careful, could confuse gc])
:single-float (or single-float) (4-byte access, 4-byte single-float result)
:double-float (or double-float) (8-byte access, 8-byte double-float result)
:signed-natural
:unsigned-natural
;; For these last two, in 32-bit lisps, these will
;; construct 32-bit values, and in 64-bit lisps, it will construct
;; 64-bit values
:nybble (4-bit -- half-byte -- value)
Be aware that though the access types might look similar to C types, they are not actually identical.
For more information on :signed-natural and
:unsigned-natural, see 64 bit Allegro CL
Implementations in release-notes.htm.
In place of using memref-int and memref, operators like single-float-to-shorts, double-float-to-shorts, shorts-to-single-float, shorts-to-double-float may be used for accessing/creating floats. A foreign type can be defined (see ftype.htm). See also write-vector.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.
Created 2000.10.5.