The module Ptr provides typed pointers to foreign data. It is part of the Foreign Function Interface (FFI) and will normally be imported via the module Foreign (see Section 4.13).
data Ptr a -- abstract handle for pointers to data -- instance of: Eq, Ord, Show nullPtr :: Ptr a castPtr :: Ptr a -> Ptr b plusPtr :: Ptr a -> Int -> Ptr b alignPtr :: Ptr a -> Int -> Ptr a minusPtr :: Ptr a -> Ptr b -> Int |
The following specifies the semantics of the data definition and the functions.
A value of type Ptr a represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type a. The type a will normally be an instance of class Storable (see Section 4.35), which provides the marshalling operations.
The constant nullPtr contains a distinguished value of Ptr that is not associated with a valid memory location.
The castPtr function casts a pointer from one type to another.
Advances the given address by the given offset in bytes.
Given an arbitrary address and an alignment constraint, alignPtr yields the next higher address that fulfills the alignment constraint. An alignment constraint x is fulfilled by any address divisible by x. This operation is idempotent.
Computes the offset required to get from the first to the second argument. We have
p2 == p1 `plusPtr` (p2 `minusPtr` p1) |
data FunPtr a -- abstract handle for pointers to functions -- instance of: Eq, Ord, Show nullFunPtr :: FunPtr a castFunPtr :: FunPtr a -> FunPtr b freeHaskellFunPtr :: FunPtr a -> IO () castFunPtrToPtr :: FunPtr a -> Ptr b -- see warning below castPtrToFunPtr :: Ptr a -> FunPtr b -- see warning below |
A value of type FunPtr a is a pointer to a piece of code. It may be the pointer to a C function or to a Haskell function created using foreign export dynamic. A foreign export dynamic should normally be declared to produce a FunPtr of the correct type. For example:
type Compare = Int -> Int -> Bool foreign export dynamic mkCompare :: Compare -> IO (FunPtr Compare) |
The constant nullFunPtr contains a distinguished value of Ptr that is not associated with a valid memory location.
Casts a FunPtr to a FunPtr of a different type.
Releases the storage associated with the given FunPtr. This should be called whenever the return value from a foreign export dynamic function is no longer required, otherwise the storage it uses will leak.
These two functions cast Ptrs to FunPtrs and vice versa.
Warning: These functions are only valid on architectures that use the same representation for data and function pointers. It is recommended to avoid using these functions; more precisely, only where bindings to external libraries are made whose interface already relies on this assumption, should the use of castFunPtrToPtr and castPtrToFunPtr be considered at all.
The following definition is available to C programs inter-operating with Haskell code when including the header HsFFI.h.
typedef void *HsPtr; /* C representation of a `Ptr a' */ typedef void (*HsFunPtr)(void); /* C representation of a `FunPtr a' */ |