base-4.9.0.0: Basic libraries

Copyright(c) The FFI task force 2001
Licensesee libraries/base/LICENSE
Maintainerffi@haskell.org
Stabilityprovisional
Portabilityportable
Safe HaskellTrustworthy
LanguageHaskell2010

Foreign.Storable

Description

The module Foreign.Storable provides most elementary support for marshalling and is part of the language-independent portion of the Foreign Function Interface (FFI), and will normally be imported via the Foreign module.

Synopsis

Documentation

class Storable a where

The member functions of this class facilitate writing values of primitive types to raw memory (which may have been allocated with the above mentioned routines) and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types.

Memory addresses are represented as values of type Ptr a, for some a which is an instance of class Storable. The type argument to Ptr helps provide some valuable type safety in FFI code (you can't mix pointers of different types without an explicit cast), while helping the Haskell type system figure out which marshalling method is needed for a given pointer.

All marshalling between Haskell and a foreign language ultimately boils down to translating Haskell data structures into the binary representation of a corresponding data structure of the foreign language and vice versa. To code this marshalling in Haskell, it is necessary to manipulate primitive data types stored in unstructured memory blocks. The class Storable facilitates this manipulation on all types for which it is instantiated, which are the standard basic types of Haskell, the fixed size Int types (Int8, Int16, Int32, Int64), the fixed size Word types (Word8, Word16, Word32, Word64), StablePtr, all types from Foreign.C.Types, as well as Ptr.

Minimal complete definition

sizeOf, alignment, (peek | peekElemOff | peekByteOff), (poke | pokeElemOff | pokeByteOff)

Methods

sizeOf :: a -> Int

Computes the storage requirements (in bytes) of the argument. The value of the argument is not used.

alignment :: a -> Int

Computes the alignment constraint of the argument. An alignment constraint x is fulfilled by any address divisible by x. The value of the argument is not used.

peekElemOff :: Ptr a -> Int -> IO a

Read a value from a memory area regarded as an array of values of the same kind. The first argument specifies the start address of the array and the second the index into the array (the first element of the array has index 0). The following equality holds,

peekElemOff addr idx = IOExts.fixIO $ \result ->
  peek (addr `plusPtr` (idx * sizeOf result))

Note that this is only a specification, not necessarily the concrete implementation of the function.

pokeElemOff :: Ptr a -> Int -> a -> IO ()

Write a value to a memory area regarded as an array of values of the same kind. The following equality holds:

pokeElemOff addr idx x = 
  poke (addr `plusPtr` (idx * sizeOf x)) x

peekByteOff :: Ptr b -> Int -> IO a

Read a value from a memory location given by a base address and offset. The following equality holds:

peekByteOff addr off = peek (addr `plusPtr` off)

pokeByteOff :: Ptr b -> Int -> a -> IO ()

Write a value to a memory location given by a base address and offset. The following equality holds:

pokeByteOff addr off x = poke (addr `plusPtr` off) x

peek :: Ptr a -> IO a

Read a value from the given memory location.

Note that the peek and poke functions might require properly aligned addresses to function correctly. This is architecture dependent; thus, portable code should ensure that when peeking or poking values of some type a, the alignment constraint for a, as given by the function alignment is fulfilled.

poke :: Ptr a -> a -> IO ()

Write the given value to the given memory location. Alignment restrictions might apply; see peek.

Instances

Storable Bool 

Methods

sizeOf :: Bool -> Int

alignment :: Bool -> Int

peekElemOff :: Ptr Bool -> Int -> IO Bool

pokeElemOff :: Ptr Bool -> Int -> Bool -> IO ()

peekByteOff :: Ptr b -> Int -> IO Bool

pokeByteOff :: Ptr b -> Int -> Bool -> IO ()

peek :: Ptr Bool -> IO Bool

poke :: Ptr Bool -> Bool -> IO ()

Storable Char 

Methods

sizeOf :: Char -> Int

alignment :: Char -> Int

peekElemOff :: Ptr Char -> Int -> IO Char

pokeElemOff :: Ptr Char -> Int -> Char -> IO ()

peekByteOff :: Ptr b -> Int -> IO Char

pokeByteOff :: Ptr b -> Int -> Char -> IO ()

peek :: Ptr Char -> IO Char

poke :: Ptr Char -> Char -> IO ()

Storable Double 
Storable Float 

Methods

sizeOf :: Float -> Int

alignment :: Float -> Int

peekElemOff :: Ptr Float -> Int -> IO Float

pokeElemOff :: Ptr Float -> Int -> Float -> IO ()

peekByteOff :: Ptr b -> Int -> IO Float

pokeByteOff :: Ptr b -> Int -> Float -> IO ()

peek :: Ptr Float -> IO Float

poke :: Ptr Float -> Float -> IO ()

Storable Int 

Methods

sizeOf :: Int -> Int

alignment :: Int -> Int

peekElemOff :: Ptr Int -> Int -> IO Int

pokeElemOff :: Ptr Int -> Int -> Int -> IO ()

peekByteOff :: Ptr b -> Int -> IO Int

pokeByteOff :: Ptr b -> Int -> Int -> IO ()

peek :: Ptr Int -> IO Int

poke :: Ptr Int -> Int -> IO ()

Storable Int8 

Methods

sizeOf :: Int8 -> Int

alignment :: Int8 -> Int

peekElemOff :: Ptr Int8 -> Int -> IO Int8

pokeElemOff :: Ptr Int8 -> Int -> Int8 -> IO ()

peekByteOff :: Ptr b -> Int -> IO Int8

pokeByteOff :: Ptr b -> Int -> Int8 -> IO ()

peek :: Ptr Int8 -> IO Int8

poke :: Ptr Int8 -> Int8 -> IO ()

Storable Int16 

Methods

sizeOf :: Int16 -> Int

alignment :: Int16 -> Int

peekElemOff :: Ptr Int16 -> Int -> IO Int16

pokeElemOff :: Ptr Int16 -> Int -> Int16 -> IO ()

peekByteOff :: Ptr b -> Int -> IO Int16

pokeByteOff :: Ptr b -> Int -> Int16 -> IO ()

peek :: Ptr Int16 -> IO Int16

poke :: Ptr Int16 -> Int16 -> IO ()

Storable Int32 

Methods

sizeOf :: Int32 -> Int

alignment :: Int32 -> Int

peekElemOff :: Ptr Int32 -> Int -> IO Int32

pokeElemOff :: Ptr Int32 -> Int -> Int32 -> IO ()

peekByteOff :: Ptr b -> Int -> IO Int32

pokeByteOff :: Ptr b -> Int -> Int32 -> IO ()

peek :: Ptr Int32 -> IO Int32

poke :: Ptr Int32 -> Int32 -> IO ()

Storable Int64 

Methods

sizeOf :: Int64 -> Int

alignment :: Int64 -> Int

peekElemOff :: Ptr Int64 -> Int -> IO Int64

pokeElemOff :: Ptr Int64 -> Int -> Int64 -> IO ()

peekByteOff :: Ptr b -> Int -> IO Int64

pokeByteOff :: Ptr b -> Int -> Int64 -> IO ()

peek :: Ptr Int64 -> IO Int64

poke :: Ptr Int64 -> Int64 -> IO ()

Storable Word 

Methods

sizeOf :: Word -> Int

alignment :: Word -> Int

peekElemOff :: Ptr Word -> Int -> IO Word

pokeElemOff :: Ptr Word -> Int -> Word -> IO ()

peekByteOff :: Ptr b -> Int -> IO Word

pokeByteOff :: Ptr b -> Int -> Word -> IO ()

peek :: Ptr Word -> IO Word

poke :: Ptr Word -> Word -> IO ()

Storable Word8 

Methods

sizeOf :: Word8 -> Int

alignment :: Word8 -> Int

peekElemOff :: Ptr Word8 -> Int -> IO Word8

pokeElemOff :: Ptr Word8 -> Int -> Word8 -> IO ()

peekByteOff :: Ptr b -> Int -> IO Word8

pokeByteOff :: Ptr b -> Int -> Word8 -> IO ()

peek :: Ptr Word8 -> IO Word8

poke :: Ptr Word8 -> Word8 -> IO ()

Storable Word16 
Storable Word32 
Storable Word64 
Storable () 

Methods

sizeOf :: () -> Int

alignment :: () -> Int

peekElemOff :: Ptr () -> Int -> IO ()

pokeElemOff :: Ptr () -> Int -> () -> IO ()

peekByteOff :: Ptr b -> Int -> IO ()

pokeByteOff :: Ptr b -> Int -> () -> IO ()

peek :: Ptr () -> IO ()

poke :: Ptr () -> () -> IO ()

Storable Fingerprint 
Storable CUIntMax 
Storable CIntMax 
Storable CUIntPtr 
Storable CIntPtr 
Storable CSUSeconds 
Storable CUSeconds 
Storable CTime 

Methods

sizeOf :: CTime -> Int

alignment :: CTime -> Int

peekElemOff :: Ptr CTime -> Int -> IO CTime

pokeElemOff :: Ptr CTime -> Int -> CTime -> IO ()

peekByteOff :: Ptr b -> Int -> IO CTime

pokeByteOff :: Ptr b -> Int -> CTime -> IO ()

peek :: Ptr CTime -> IO CTime

poke :: Ptr CTime -> CTime -> IO ()

Storable CClock 
Storable CSigAtomic 
Storable CWchar 
Storable CSize 

Methods

sizeOf :: CSize -> Int

alignment :: CSize -> Int

peekElemOff :: Ptr CSize -> Int -> IO CSize

pokeElemOff :: Ptr CSize -> Int -> CSize -> IO ()

peekByteOff :: Ptr b -> Int -> IO CSize

pokeByteOff :: Ptr b -> Int -> CSize -> IO ()

peek :: Ptr CSize -> IO CSize

poke :: Ptr CSize -> CSize -> IO ()

Storable CPtrdiff 
Storable CDouble 
Storable CFloat 
Storable CULLong 
Storable CLLong 
Storable CULong 
Storable CLong 

Methods

sizeOf :: CLong -> Int

alignment :: CLong -> Int

peekElemOff :: Ptr CLong -> Int -> IO CLong

pokeElemOff :: Ptr CLong -> Int -> CLong -> IO ()

peekByteOff :: Ptr b -> Int -> IO CLong

pokeByteOff :: Ptr b -> Int -> CLong -> IO ()

peek :: Ptr CLong -> IO CLong

poke :: Ptr CLong -> CLong -> IO ()

Storable CUInt 

Methods

sizeOf :: CUInt -> Int

alignment :: CUInt -> Int

peekElemOff :: Ptr CUInt -> Int -> IO CUInt

pokeElemOff :: Ptr CUInt -> Int -> CUInt -> IO ()

peekByteOff :: Ptr b -> Int -> IO CUInt

pokeByteOff :: Ptr b -> Int -> CUInt -> IO ()

peek :: Ptr CUInt -> IO CUInt

poke :: Ptr CUInt -> CUInt -> IO ()

Storable CInt 

Methods

sizeOf :: CInt -> Int

alignment :: CInt -> Int

peekElemOff :: Ptr CInt -> Int -> IO CInt

pokeElemOff :: Ptr CInt -> Int -> CInt -> IO ()

peekByteOff :: Ptr b -> Int -> IO CInt

pokeByteOff :: Ptr b -> Int -> CInt -> IO ()

peek :: Ptr CInt -> IO CInt

poke :: Ptr CInt -> CInt -> IO ()

Storable CUShort 
Storable CShort 
Storable CUChar 
Storable CSChar 
Storable CChar 

Methods

sizeOf :: CChar -> Int

alignment :: CChar -> Int

peekElemOff :: Ptr CChar -> Int -> IO CChar

pokeElemOff :: Ptr CChar -> Int -> CChar -> IO ()

peekByteOff :: Ptr b -> Int -> IO CChar

pokeByteOff :: Ptr b -> Int -> CChar -> IO ()

peek :: Ptr CChar -> IO CChar

poke :: Ptr CChar -> CChar -> IO ()

Storable IntPtr 
Storable WordPtr 
Storable Fd 

Methods

sizeOf :: Fd -> Int

alignment :: Fd -> Int

peekElemOff :: Ptr Fd -> Int -> IO Fd

pokeElemOff :: Ptr Fd -> Int -> Fd -> IO ()

peekByteOff :: Ptr b -> Int -> IO Fd

pokeByteOff :: Ptr b -> Int -> Fd -> IO ()

peek :: Ptr Fd -> IO Fd

poke :: Ptr Fd -> Fd -> IO ()

Storable CRLim 

Methods

sizeOf :: CRLim -> Int

alignment :: CRLim -> Int

peekElemOff :: Ptr CRLim -> Int -> IO CRLim

pokeElemOff :: Ptr CRLim -> Int -> CRLim -> IO ()

peekByteOff :: Ptr b -> Int -> IO CRLim

pokeByteOff :: Ptr b -> Int -> CRLim -> IO ()

peek :: Ptr CRLim -> IO CRLim

poke :: Ptr CRLim -> CRLim -> IO ()

Storable CTcflag 
Storable CSpeed 
Storable CCc 

Methods

sizeOf :: CCc -> Int

alignment :: CCc -> Int

peekElemOff :: Ptr CCc -> Int -> IO CCc

pokeElemOff :: Ptr CCc -> Int -> CCc -> IO ()

peekByteOff :: Ptr b -> Int -> IO CCc

pokeByteOff :: Ptr b -> Int -> CCc -> IO ()

peek :: Ptr CCc -> IO CCc

poke :: Ptr CCc -> CCc -> IO ()

Storable CUid 

Methods

sizeOf :: CUid -> Int

alignment :: CUid -> Int

peekElemOff :: Ptr CUid -> Int -> IO CUid

pokeElemOff :: Ptr CUid -> Int -> CUid -> IO ()

peekByteOff :: Ptr b -> Int -> IO CUid

pokeByteOff :: Ptr b -> Int -> CUid -> IO ()

peek :: Ptr CUid -> IO CUid

poke :: Ptr CUid -> CUid -> IO ()

Storable CNlink 
Storable CGid 

Methods

sizeOf :: CGid -> Int

alignment :: CGid -> Int

peekElemOff :: Ptr CGid -> Int -> IO CGid

pokeElemOff :: Ptr CGid -> Int -> CGid -> IO ()

peekByteOff :: Ptr b -> Int -> IO CGid

pokeByteOff :: Ptr b -> Int -> CGid -> IO ()

peek :: Ptr CGid -> IO CGid

poke :: Ptr CGid -> CGid -> IO ()

Storable CSsize 
Storable CPid 

Methods

sizeOf :: CPid -> Int

alignment :: CPid -> Int

peekElemOff :: Ptr CPid -> Int -> IO CPid

pokeElemOff :: Ptr CPid -> Int -> CPid -> IO ()

peekByteOff :: Ptr b -> Int -> IO CPid

pokeByteOff :: Ptr b -> Int -> CPid -> IO ()

peek :: Ptr CPid -> IO CPid

poke :: Ptr CPid -> CPid -> IO ()

Storable COff 

Methods

sizeOf :: COff -> Int

alignment :: COff -> Int

peekElemOff :: Ptr COff -> Int -> IO COff

pokeElemOff :: Ptr COff -> Int -> COff -> IO ()

peekByteOff :: Ptr b -> Int -> IO COff

pokeByteOff :: Ptr b -> Int -> COff -> IO ()

peek :: Ptr COff -> IO COff

poke :: Ptr COff -> COff -> IO ()

Storable CMode 

Methods

sizeOf :: CMode -> Int

alignment :: CMode -> Int

peekElemOff :: Ptr CMode -> Int -> IO CMode

pokeElemOff :: Ptr CMode -> Int -> CMode -> IO ()

peekByteOff :: Ptr b -> Int -> IO CMode

pokeByteOff :: Ptr b -> Int -> CMode -> IO ()

peek :: Ptr CMode -> IO CMode

poke :: Ptr CMode -> CMode -> IO ()

Storable CIno 

Methods

sizeOf :: CIno -> Int

alignment :: CIno -> Int

peekElemOff :: Ptr CIno -> Int -> IO CIno

pokeElemOff :: Ptr CIno -> Int -> CIno -> IO ()

peekByteOff :: Ptr b -> Int -> IO CIno

pokeByteOff :: Ptr b -> Int -> CIno -> IO ()

peek :: Ptr CIno -> IO CIno

poke :: Ptr CIno -> CIno -> IO ()

Storable CDev 

Methods

sizeOf :: CDev -> Int

alignment :: CDev -> Int

peekElemOff :: Ptr CDev -> Int -> IO CDev

pokeElemOff :: Ptr CDev -> Int -> CDev -> IO ()

peekByteOff :: Ptr b -> Int -> IO CDev

pokeByteOff :: Ptr b -> Int -> CDev -> IO ()

peek :: Ptr CDev -> IO CDev

poke :: Ptr CDev -> CDev -> IO ()

(Storable a, Integral a) => Storable (Ratio a) 

Methods

sizeOf :: Ratio a -> Int

alignment :: Ratio a -> Int

peekElemOff :: Ptr (Ratio a) -> Int -> IO (Ratio a)

pokeElemOff :: Ptr (Ratio a) -> Int -> Ratio a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Ratio a)

pokeByteOff :: Ptr b -> Int -> Ratio a -> IO ()

peek :: Ptr (Ratio a) -> IO (Ratio a)

poke :: Ptr (Ratio a) -> Ratio a -> IO ()

Storable (StablePtr a) 

Methods

sizeOf :: StablePtr a -> Int

alignment :: StablePtr a -> Int

peekElemOff :: Ptr (StablePtr a) -> Int -> IO (StablePtr a)

pokeElemOff :: Ptr (StablePtr a) -> Int -> StablePtr a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (StablePtr a)

pokeByteOff :: Ptr b -> Int -> StablePtr a -> IO ()

peek :: Ptr (StablePtr a) -> IO (StablePtr a)

poke :: Ptr (StablePtr a) -> StablePtr a -> IO ()

Storable (Ptr a) 

Methods

sizeOf :: Ptr a -> Int

alignment :: Ptr a -> Int

peekElemOff :: Ptr (Ptr a) -> Int -> IO (Ptr a)

pokeElemOff :: Ptr (Ptr a) -> Int -> Ptr a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Ptr a)

pokeByteOff :: Ptr b -> Int -> Ptr a -> IO ()

peek :: Ptr (Ptr a) -> IO (Ptr a)

poke :: Ptr (Ptr a) -> Ptr a -> IO ()

Storable (FunPtr a) 

Methods

sizeOf :: FunPtr a -> Int

alignment :: FunPtr a -> Int

peekElemOff :: Ptr (FunPtr a) -> Int -> IO (FunPtr a)

pokeElemOff :: Ptr (FunPtr a) -> Int -> FunPtr a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (FunPtr a)

pokeByteOff :: Ptr b -> Int -> FunPtr a -> IO ()

peek :: Ptr (FunPtr a) -> IO (FunPtr a)

poke :: Ptr (FunPtr a) -> FunPtr a -> IO ()

Storable a => Storable (Complex a) 

Methods

sizeOf :: Complex a -> Int

alignment :: Complex a -> Int

peekElemOff :: Ptr (Complex a) -> Int -> IO (Complex a)

pokeElemOff :: Ptr (Complex a) -> Int -> Complex a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Complex a)

pokeByteOff :: Ptr b -> Int -> Complex a -> IO ()

peek :: Ptr (Complex a) -> IO (Complex a)

poke :: Ptr (Complex a) -> Complex a -> IO ()

Storable a => Storable (Identity a) 

Methods

sizeOf :: Identity a -> Int

alignment :: Identity a -> Int

peekElemOff :: Ptr (Identity a) -> Int -> IO (Identity a)

pokeElemOff :: Ptr (Identity a) -> Int -> Identity a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Identity a)

pokeByteOff :: Ptr b -> Int -> Identity a -> IO ()

peek :: Ptr (Identity a) -> IO (Identity a)

poke :: Ptr (Identity a) -> Identity a -> IO ()

Storable a => Storable (Const k a b) 

Methods

sizeOf :: Const k a b -> Int

alignment :: Const k a b -> Int

peekElemOff :: Ptr (Const k a b) -> Int -> IO (Const k a b)

pokeElemOff :: Ptr (Const k a b) -> Int -> Const k a b -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Const k a b)

pokeByteOff :: Ptr b -> Int -> Const k a b -> IO ()

peek :: Ptr (Const k a b) -> IO (Const k a b)

poke :: Ptr (Const k a b) -> Const k a b -> IO ()