Chapter 4. The lang category: language support

Table of Contents
4.1. Addr
4.2. Bits
4.3. ByteArray
4.4. CCall
4.5. CTypes
4.6. CTypesISO
4.7. Dynamic
4.8. Exception
4.9. Foreign
4.10. ForeignObj
4.11. GlaExts
4.12. IArray
4.13. Int
4.14. IOExts
4.15. LazyST
4.16. MArray
4.17. MutableArray
4.18. NumExts
4.19. PackedString
4.20. ShowFunctions
4.21. ST
4.22. Stable
4.23. StableName
4.24. StablePtr
4.25. Storable
4.26. Weak
4.27. Word

4.1. Addr

This library provides machine addresses, i.e., handles to chunks of raw memory. It is primarily intended for use with the Foreign Function Interface (FFI) and will usually be imported via the module Foreign (see Section 4.9).

4.1.1. Address Type and Arithmetic

data Addr      -- abstract handle for memory addresses
               -- instance of: Eq, Ord, Show, Typeable

data AddrOff   -- abstract handle of address offsets
               -- instance of: Eq, Ord, Show, Enum, Num, Real, Integral, Typeable

nullAddr  :: Addr
alignAddr :: Addr -> Int     -> Addr
plusAddr  :: Addr -> AddrOff -> Addr
minusAddr :: Addr -> Addr    -> AddrOff

The following specifies the behaviour of the four function definitions.

nullAddr :: Addr

The constant nullAddr contains a distinguished value of Addr that denotes the absence of an address that is associated with a valid memory location.

alignAddr :: Addr -> Int -> Addr

Given an arbitrary address and an alignment constraint, alignAddr 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.

plusAddr :: Addr -> AddrOff -> Addr

Advances the given address by the given address offset.

minusAddr :: Addr -> Addr -> AddrOff

Computes the offset required to get from the first to the second argument. We have

   a2 == a1 `plusAddr` (a2 `minusAddr` a1)

4.1.2. The Standard C-side Interface

The following definition is available to C programs inter-operating with Haskell code when including the header HsFFI.h.

typedef void* HsAddr;  /* C representation of an Addr */

4.1.3. Deprecated Functions

The following functions are deprecated in the new FFI. Use the module Storable (Section 4.25) instead.

-- read value out of _immutable_ memory
indexCharOffAddr       :: Addr -> Int -> Char
indexIntOffAddr        :: Addr -> Int -> Int
indexAddrOffAddr       :: Addr -> Int -> Addr
indexFloatOffAddr      :: Addr -> Int -> Float
indexDoubleOffAddr     :: Addr -> Int -> Double
indexWord8OffAddr      :: Addr -> Int -> Word8
indexWord16OffAddr     :: Addr -> Int -> Word16
indexWord32OffAddr     :: Addr -> Int -> Word32
indexWord64OffAddr     :: Addr -> Int -> Word64
indexInt8OffAddr       :: Addr -> Int -> Int8
indexInt16OffAddr      :: Addr -> Int -> Int16
indexInt32OffAddr      :: Addr -> Int -> Int32
indexInt64OffAddr      :: Addr -> Int -> Int64
indexStablePtrOffAddr  :: Addr -> Int -> StablePtr a

-- read value out of mutable memory
readCharOffAddr        :: Addr -> Int -> IO Char
readIntOffAddr         :: Addr -> Int -> IO Int
readAddrOffAddr        :: Addr -> Int -> IO Addr
readFloatOffAddr       :: Addr -> Int -> IO Float
readDoubleOffAddr      :: Addr -> Int -> IO Double
readWord8OffAddr       :: Addr -> Int -> IO Word8
readWord16OffAddr      :: Addr -> Int -> IO Word16
readWord32OffAddr      :: Addr -> Int -> IO Word32
readWord64OffAddr      :: Addr -> Int -> IO Word64
readInt8OffAddr        :: Addr -> Int -> IO Int8
readInt16OffAddr       :: Addr -> Int -> IO Int16
readInt32OffAddr       :: Addr -> Int -> IO Int32
readInt64OffAddr       :: Addr -> Int -> IO Int64
readStablePtrOffAddr   :: Addr -> Int -> IO (StablePtr a)

-- write value into mutable memory
writeCharOffAddr       :: Addr -> Int -> Char   -> IO ()
writeIntOffAddr        :: Addr -> Int -> Int    -> IO ()
writeAddrOffAddr       :: Addr -> Int -> Addr   -> IO ()
writeFloatOffAddr      :: Addr -> Int -> Float  -> IO ()
writeDoubleOffAddr     :: Addr -> Int -> Double -> IO ()
writeWord8OffAddr      :: Addr -> Int -> Word8  -> IO ()
writeWord16OffAddr     :: Addr -> Int -> Word16 -> IO ()
writeWord32OffAddr     :: Addr -> Int -> Word32 -> IO ()
writeWord64OffAddr     :: Addr -> Int -> Word64 -> IO ()
writeInt8OffAddr       :: Addr -> Int -> Int8   -> IO ()
writeInt16OffAddr      :: Addr -> Int -> Int16  -> IO ()
writeInt32OffAddr      :: Addr -> Int -> Int32  -> IO ()
writeInt64OffAddr      :: Addr -> Int -> Int64  -> IO ()
writeForeignObjOffAddr :: Addr -> Int -> ForeignObj -> IO ()
writeStablePtrOffAddr  :: Addr -> Int -> StablePtr a -> IO ()

-- conversion to/from Int, a little bit doubtful...
addrToInt              :: Addr -> Int
intToAddr              :: Int  -> Addr

-- completely deprecated
data Word = W# Word#
wordToInt              :: Word -> Int
intToWord              :: Int  -> Word

4.1.4. Hugs Specifics

Hugs provides Addr and nullAddr but does not provide any of the index, read or write functions. They can be implemented using GreenCard if required.