| Copyright | (c) Simon Plakolb 2020 |
|---|---|
| License | MIT |
| Maintainer | s.plakolb@gmail.com |
| Stability | beta |
| Safe Haskell | None |
| Language | Haskell2010 |
Foreign.C.Structs
Description
The Foreign.C.Structs module allows you to construct C structs of arbitrary Storable types.
Synopsis
- data Struct2 a b = Struct2 {}
- data Struct3 a b c = Struct3 {}
- data Struct4 a b c d = Struct4 {}
- data Struct5 a b c d e = Struct5 {}
- data Struct6 a b c d e f = Struct6 {}
- structT :: Int -> DecsQ
- acs :: Int -> Int -> ExpQ
- next :: (Storable a, Storable b, Storable c) => Ptr a -> b -> IO (Ptr c)
- sizeof :: [Int] -> [Int] -> Int
- fmax :: Integral a => [a] -> a
- class Storable a
- peek :: Storable a => Ptr a -> IO a
- poke :: Storable a => Ptr a -> a -> IO ()
- sizeOf :: Storable a => a -> Int
- alignment :: Storable a => a -> Int
- castPtr :: Ptr a -> Ptr b
Documentation
A Struct2 can hold two records of any Storable types a and b.
It is itself an instance of Storable and can be used inside a Ptr.
The Struct2 constructor takes two arguments.
The record functions s21st and s22nd provide access to the fields values.
Instances
| (Eq a, Eq b) => Eq (Struct2 a b) Source # | |
| (Show a, Show b) => Show (Struct2 a b) Source # | |
| (Storable a, Storable b) => Storable (Struct2 a b) Source # | |
Defined in Foreign.C.Structs.Types Methods sizeOf :: Struct2 a b -> Int # alignment :: Struct2 a b -> Int # peekElemOff :: Ptr (Struct2 a b) -> Int -> IO (Struct2 a b) # pokeElemOff :: Ptr (Struct2 a b) -> Int -> Struct2 a b -> IO () # peekByteOff :: Ptr b0 -> Int -> IO (Struct2 a b) # pokeByteOff :: Ptr b0 -> Int -> Struct2 a b -> IO () # | |
A Struct3 can hold three records of any Storable types a, b and c.
It is itself an instance of Storable and can be used inside a Ptr.
The Struct3 constructor takes three arguments.
The record functions s31st, s32nd and s33rd provide access to the fields values.
Instances
| (Eq a, Eq b, Eq c) => Eq (Struct3 a b c) Source # | |
| (Show a, Show b, Show c) => Show (Struct3 a b c) Source # | |
| (Storable a, Storable b, Storable c) => Storable (Struct3 a b c) Source # | |
Defined in Foreign.C.Structs.Types Methods sizeOf :: Struct3 a b c -> Int # alignment :: Struct3 a b c -> Int # peekElemOff :: Ptr (Struct3 a b c) -> Int -> IO (Struct3 a b c) # pokeElemOff :: Ptr (Struct3 a b c) -> Int -> Struct3 a b c -> IO () # peekByteOff :: Ptr b0 -> Int -> IO (Struct3 a b c) # pokeByteOff :: Ptr b0 -> Int -> Struct3 a b c -> IO () # | |
A Struct4 can hold four records of any Storable types a, b, c and d.
It is itself an instance of Storable and can be used inside a Ptr.
The Struct4 constructor takes four arguments.
The record functions s41st, s42nd, s43rd and s44th provide access to the fields values.
Instances
| (Eq a, Eq b, Eq c, Eq d) => Eq (Struct4 a b c d) Source # | |
| (Show a, Show b, Show c, Show d) => Show (Struct4 a b c d) Source # | |
| (Storable a, Storable b, Storable c, Storable d) => Storable (Struct4 a b c d) Source # | |
Defined in Foreign.C.Structs.Types Methods sizeOf :: Struct4 a b c d -> Int # alignment :: Struct4 a b c d -> Int # peekElemOff :: Ptr (Struct4 a b c d) -> Int -> IO (Struct4 a b c d) # pokeElemOff :: Ptr (Struct4 a b c d) -> Int -> Struct4 a b c d -> IO () # peekByteOff :: Ptr b0 -> Int -> IO (Struct4 a b c d) # pokeByteOff :: Ptr b0 -> Int -> Struct4 a b c d -> IO () # | |
data Struct5 a b c d e Source #
A Struct5 can hold five records of any Storable types a, b, c, d and e.
It is itself an instance of Storable and can be used inside a Ptr.
The Struct5 constructor takes five arguments.
The record functions s51st, s52nd, s53rd, s54th and s55th provide access to the fields values.
Instances
| (Eq a, Eq b, Eq c, Eq d, Eq e) => Eq (Struct5 a b c d e) Source # | |
| (Show a, Show b, Show c, Show d, Show e) => Show (Struct5 a b c d e) Source # | |
| (Storable a, Storable b, Storable c, Storable d, Storable e) => Storable (Struct5 a b c d e) Source # | |
Defined in Foreign.C.Structs.Types Methods sizeOf :: Struct5 a b c d e -> Int # alignment :: Struct5 a b c d e -> Int # peekElemOff :: Ptr (Struct5 a b c d e) -> Int -> IO (Struct5 a b c d e) # pokeElemOff :: Ptr (Struct5 a b c d e) -> Int -> Struct5 a b c d e -> IO () # peekByteOff :: Ptr b0 -> Int -> IO (Struct5 a b c d e) # pokeByteOff :: Ptr b0 -> Int -> Struct5 a b c d e -> IO () # peek :: Ptr (Struct5 a b c d e) -> IO (Struct5 a b c d e) # poke :: Ptr (Struct5 a b c d e) -> Struct5 a b c d e -> IO () # | |
data Struct6 a b c d e f Source #
A Struct6 can hold six records of any Storable types a, b, c, d, e and f.
It is itself an instance of Storable and can be used inside a Ptr.
The Struct6 constructor takes six arguments.
The record functions s61st, s62nd, s63rd, s64th, s65th and s66th provide access to the fields values.
Instances
| (Eq a, Eq b, Eq c, Eq d, Eq e, Eq f) => Eq (Struct6 a b c d e f) Source # | |
| (Show a, Show b, Show c, Show d, Show e, Show f) => Show (Struct6 a b c d e f) Source # | |
| (Storable a, Storable b, Storable c, Storable d, Storable e, Storable f) => Storable (Struct6 a b c d e f) Source # | |
Defined in Foreign.C.Structs.Types Methods sizeOf :: Struct6 a b c d e f -> Int # alignment :: Struct6 a b c d e f -> Int # peekElemOff :: Ptr (Struct6 a b c d e f) -> Int -> IO (Struct6 a b c d e f) # pokeElemOff :: Ptr (Struct6 a b c d e f) -> Int -> Struct6 a b c d e f -> IO () # peekByteOff :: Ptr b0 -> Int -> IO (Struct6 a b c d e f) # pokeByteOff :: Ptr b0 -> Int -> Struct6 a b c d e f -> IO () # peek :: Ptr (Struct6 a b c d e f) -> IO (Struct6 a b c d e f) # poke :: Ptr (Struct6 a b c d e f) -> Struct6 a b c d e f -> IO () # | |
structT :: Int -> DecsQ Source #
All StructN types and their instances of Storable are declared using structT.
It can theoretically create C structs with an infinite number of fields.
The parameter of structT is the number of fields the struct type should have.
Its constructor and type will both be named StructN where N is equal to the argument to structT.
acs :: Int -> Int -> ExpQ Source #
Access function for fields of a StructN where N is the number of fields in the struct.
N is the first argument passed to acs, while the second is the field number.
The first field has number 1, the second 2 and so on.
s = Struct4 1 2 3 4 $(acs 4 3) s
next :: (Storable a, Storable b, Storable c) => Ptr a -> b -> IO (Ptr c) Source #
Jumps to the next pointer location in the struct.
sizeof :: [Int] -> [Int] -> Int Source #
Due to alignment constraints the size of C structs is dependent on the order of fields and their respectible sizes. The function sizeof can calculate the resulting size given a list of all alignments and sizes.
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 aa 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)
Instances
peek :: Storable a => 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 :: Storable a => Ptr a -> a -> IO () #
Write the given value to the given memory location. Alignment
restrictions might apply; see peek.
sizeOf :: Storable a => a -> Int #
Computes the storage requirements (in bytes) of the argument. The value of the argument is not used.