W3cubDocs

/Haskell 8

Foreign.Storable

Copyright (c) The FFI task force 2001
License see libraries/base/LICENSE
Maintainer [email protected]
Stability provisional
Portability portable
Safe Haskell Trustworthy
Language Haskell2010

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.

class Storable a where Source

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 Source

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

alignment :: a -> Int Source

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 Source

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 () Source

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 Source

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 () Source

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 Source

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 () Source

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

Instances

Storable Bool

Since: 2.1

Storable Char

Since: 2.1

Storable Double

Since: 2.1

Storable Float

Since: 2.1

Storable Int

Since: 2.1

Methods

sizeOf :: Int -> Int Source

alignment :: Int -> Int Source

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

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

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

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

peek :: Ptr Int -> IO Int Source

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

Storable Int8

Since: 2.1

Storable Int16

Since: 2.1

Storable Int32

Since: 2.1

Storable Int64

Since: 2.1

Storable Word

Since: 2.1

Storable Word8

Since: 2.1

Storable Word16

Since: 2.1

Storable Word32

Since: 2.1

Storable Word64

Since: 2.1

Storable ()

Since: 4.9.0.0

Methods

sizeOf :: () -> Int Source

alignment :: () -> Int Source

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

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

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

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

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

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

Storable Fingerprint

Since: 4.4.0.0

Storable IntPtr
Storable WordPtr
Storable CUIntMax
Storable CIntMax
Storable CUIntPtr
Storable CIntPtr
Storable CSUSeconds
Storable CUSeconds
Storable CTime
Storable CClock
Storable CSigAtomic
Storable CWchar
Storable CSize
Storable CPtrdiff
Storable CDouble
Storable CFloat
Storable CBool
Storable CULLong
Storable CLLong
Storable CULong
Storable CLong
Storable CUInt
Storable CInt
Storable CUShort
Storable CShort
Storable CUChar
Storable CSChar
Storable CChar
Storable Fd

Methods

sizeOf :: Fd -> Int Source

alignment :: Fd -> Int Source

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

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

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

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

peek :: Ptr Fd -> IO Fd Source

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

Storable CTimer
Storable CKey
Storable CId

Methods

sizeOf :: CId -> Int Source

alignment :: CId -> Int Source

peekElemOff :: Ptr CId -> Int -> IO CId Source

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

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

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

peek :: Ptr CId -> IO CId Source

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

Storable CFsFilCnt
Storable CFsBlkCnt
Storable CClockId
Storable CBlkCnt
Storable CBlkSize
Storable CRLim
Storable CTcflag
Storable CSpeed
Storable CCc

Methods

sizeOf :: CCc -> Int Source

alignment :: CCc -> Int Source

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

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

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

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

peek :: Ptr CCc -> IO CCc Source

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

Storable CUid
Storable CNlink
Storable CGid
Storable CSsize
Storable CPid
Storable COff
Storable CMode
Storable CIno
Storable CDev
(Storable a, Integral a) => Storable (Ratio a)

Since: 4.8.0.0

Methods

sizeOf :: Ratio a -> Int Source

alignment :: Ratio a -> Int Source

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

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

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

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

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

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

Storable (StablePtr a)

Since: 2.1

Storable (Ptr a)

Since: 2.1

Methods

sizeOf :: Ptr a -> Int Source

alignment :: Ptr a -> Int Source

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

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

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

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

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

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

Storable (FunPtr a)

Since: 2.1

Methods

sizeOf :: FunPtr a -> Int Source

alignment :: FunPtr a -> Int Source

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

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

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

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

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

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

Storable a => Storable (Identity a)

Methods

sizeOf :: Identity a -> Int Source

alignment :: Identity a -> Int Source

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

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

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

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

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

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

Storable a => Storable (Complex a)

Since: 4.8.0.0

Methods

sizeOf :: Complex a -> Int Source

alignment :: Complex a -> Int Source

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

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

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

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

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

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

Storable a => Storable (Const k a b)

Methods

sizeOf :: Const k a b -> Int Source

alignment :: Const k a b -> Int Source

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

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

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

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

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

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

© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/8.2.1/docs/html/libraries/base-4.10.0.0/Foreign-Storable.html