| Allegro CL version 8.2 Minimal update since 8.2 release. 8.1 version |
Arguments: address offset pos type &optional coerce
This function and the related function memref calculate an address in memory and performs a read from that address. This function takes an address as an argument while memref takes a Lisp object.
The width and style of the read depends upon the type. The possible values for the type argument are shown in a table below.
Except when the type argument
is :lisp
, the result is always a number, either an
integer or float. The type and possible range of that number
depends on the type argument.
This function is setf'able. The setf function writes to
the addressed memory instead of reading from it.
The address argument must be an integer and the offset and pos arguments must be fixnum values. The sum of the three arguments is treated as an address in memory from which data is fetched, or to which data is stored.
When the coerce argument is non-nil
some checking is done in the setf form. The
value to be stored is coerced to the required type.
This function provides low-level memory access in Allegro CL. However, even though the name is exported and documented, we recommend against using this function in user code. Instead, we recommend using higher-level functions, such as those linked to below. However, the function is useful in the development cycle for debugging purposes.
WARNING about setf: except when the type
is :lisp
, the setf function does not do any
setf-protection. If it is used to store non-Lisp values into a memory
location that was intended to hold a Lisp value, then a
non-recoverable error is very likely to occur during the next GC.
The access-types (possible values of type) 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 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 implementation.htm.
(setf (sys:memref-int array-address 0 0 :double-float :coerce) 1.0s0)
array-total-size-limit
).
For example, if the variable addr
holds the foreign
address of a large block of memory with a length stored in the
size
variable, the following loop could be used to
extract bytes from the block:
(dotimes (i size) (memref-int (+ addr i) 0 0 :byte))
Note how the address arithmetic is performed before the call to memref-int. If the index were passed as the offset or the pos argument, it would be subject to the fixnum limitation.
To avoid bignum boxing in this iteration, memref with a fixnum argument may be used to keep all numbers in the fixnum range. See the description of memref for a detailed analysis of this technique.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Minimal update since 8.2 release. 8.1 version |