Foreign.Ptr

base-4.9.0.0: Basic libraries

Copyright | (c) The FFI task force 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | ffi@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

Foreign.Ptr

Contents

- Data pointers
- Function pointers
- Integral types with lossless conversion to and from pointers

Description

This module provides typed pointers to foreign data. It is part of the Foreign Function Interface (FFI) and will normally be imported via the Foreign module.

Synopsis

- data Ptr a
- 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
- data FunPtr a
- nullFunPtr :: FunPtr a
- castFunPtr :: FunPtr a -> FunPtr b
- castFunPtrToPtr :: FunPtr a -> Ptr b
- castPtrToFunPtr :: Ptr a -> FunPtr b
- freeHaskellFunPtr :: FunPtr a -> IO ()
- data IntPtr
- ptrToIntPtr :: Ptr a -> IntPtr
- intPtrToPtr :: IntPtr -> Ptr a
- data WordPtr
- ptrToWordPtr :: Ptr a -> WordPtr
- wordPtrToPtr :: WordPtr -> Ptr a

# Data pointers

data Ptr a Source

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 often be an instance of class `Storable` which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C `struct`.

Instances

Eq (Ptr a) |
Methods (==) :: Ptr a -> Ptr a -> Bool Source (/=) :: Ptr a -> Ptr a -> Bool Source
Data a => Data (Ptr a) |
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Ptr a -> c (Ptr a) Source gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Ptr a) Source toConstr :: Ptr a -> Constr Source dataTypeOf :: Ptr a -> DataType Source dataCast1 :: Typeable (TYPE Lifted -> TYPE Lifted) t => (forall d. Data d => c (t d)) -> Maybe (c (Ptr a)) Source dataCast2 :: Typeable (TYPE Lifted -> TYPE Lifted -> TYPE Lifted) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Ptr a)) Source gmapT :: (forall b. Data b => b -> b) -> Ptr a -> Ptr a Source gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Ptr a -> r Source gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Ptr a -> r Source gmapQ :: (forall d. Data d => d -> u) -> Ptr a -> [u] Source gmapQi :: Int -> (forall d. Data d => d -> u) -> Ptr a -> u Source gmapM :: Monad m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) Source gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) Source gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) Source
Ord (Ptr a) |
Methods compare :: Ptr a -> Ptr a -> Ordering Source (<) :: Ptr a -> Ptr a -> Bool Source (<=) :: Ptr a -> Ptr a -> Bool Source (>) :: Ptr a -> Ptr a -> Bool Source (>=) :: Ptr a -> Ptr a -> Bool Source max :: Ptr a -> Ptr a -> Ptr a Source min :: Ptr a -> Ptr a -> Ptr a Source
Show (Ptr a) |
Methods showsPrec :: Int -> Ptr a -> ShowS Source show :: Ptr a -> String Source showList :: [Ptr a] -> ShowS Source
Storable (Ptr a) |
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
Eq (URec (Ptr ()) p) |
Methods (==) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool Source (/=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool Source
Ord (URec (Ptr ()) p) |
Methods compare :: URec (Ptr ()) p -> URec (Ptr ()) p -> Ordering Source (<) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool Source (<=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool Source (>) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool Source (>=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool Source max :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p Source min :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p Source
Generic (URec (Ptr ()) p) |
Associated Types type Rep (URec (Ptr ()) p) :: * -> * Source Methods from :: URec (Ptr ()) p -> Rep (URec (Ptr ()) p) x Source to :: Rep (URec (Ptr ()) p) x -> URec (Ptr ()) p Source
data URec (Ptr ()) = UAddr { uAddr# :: Addr# } | Used for marking occurrences of `Addr#`
type Rep (URec (Ptr ()) p) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just Symbol "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) UAddr)) |

nullPtr :: Ptr a Source

The constant `nullPtr` contains a distinguished value of `Ptr` that is not associated with a valid memory location.

castPtr :: Ptr a -> Ptr b Source

The `castPtr` function casts a pointer from one type to another.

plusPtr :: Ptr a -> Int -> Ptr b Source

Advances the given address by the given offset in bytes.

alignPtr :: Ptr a -> Int -> Ptr a Source

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.

minusPtr :: Ptr a -> Ptr b -> Int Source

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

    p2 == p1 `plusPtr` (p2 `minusPtr` p1)

# Function pointers

data FunPtr a Source

A value of type ``FunPtr` a` is a pointer to a function callable from foreign code. The type `a` will normally be a foreign type, a function type with zero or more arguments where

- the argument types are marshallable foreign types, i.e. `Char`, `Int`, `Double`, `Float`, `Bool`, `Int8`, `Int16`, `Int32`, `Int64`, `Word8`, `Word16`, `Word32`, `Word64`, ``Ptr` a`, ``FunPtr` a`, ``StablePtr` a` or a renaming of any of these using `newtype`.
- the return type is either a marshallable foreign type or has the form ``IO` t` where `t` is a marshallable foreign type or `()`.

A value of type ``FunPtr` a` may be a pointer to a foreign function, either returned by another foreign function or imported with a a static address import like

    foreign import ccall "stdlib.h &free"
      p_free :: FunPtr (Ptr a -> IO ())

or a pointer to a Haskell function created using a wrapper stub declared to produce a `FunPtr` of the correct type. For example:

    type Compare = Int -> Int -> Bool
    foreign import ccall "wrapper"
      mkCompare :: Compare -> IO (FunPtr Compare)

Calls to wrapper stubs like `mkCompare` allocate storage, which should be released with `freeHaskellFunPtr` when no longer required.

To convert `FunPtr` values to corresponding Haskell functions, one can define a dynamic stub for the specific foreign type, e.g.

    type IntFunction = CInt -> IO ()
    foreign import ccall "dynamic"
      mkFun :: FunPtr IntFunction -> IntFunction

Instances

Eq (FunPtr a) |
Methods (==) :: FunPtr a -> FunPtr a -> Bool Source (/=) :: FunPtr a -> FunPtr a -> Bool Source
Ord (FunPtr a) |
Methods compare :: FunPtr a -> FunPtr a -> Ordering Source (<) :: FunPtr a -> FunPtr a -> Bool Source (<=) :: FunPtr a -> FunPtr a -> Bool Source (>) :: FunPtr a -> FunPtr a -> Bool Source (>=) :: FunPtr a -> FunPtr a -> Bool Source max :: FunPtr a -> FunPtr a -> FunPtr a Source min :: FunPtr a -> FunPtr a -> FunPtr a Source
Show (FunPtr a) |
Methods showsPrec :: Int -> FunPtr a -> ShowS Source show :: FunPtr a -> String Source showList :: [FunPtr a] -> ShowS Source
Storable (FunPtr a) |
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

nullFunPtr :: FunPtr a Source

The constant `nullFunPtr` contains a distinguished value of `FunPtr` that is not associated with a valid memory location.

castFunPtr :: FunPtr a -> FunPtr b Source

Casts a `FunPtr` to a `FunPtr` of a different type.

castFunPtrToPtr :: FunPtr a -> Ptr b Source

Casts a `FunPtr` to a `Ptr`.

Note: this is valid only on architectures where data and function pointers range over the same set of addresses, and should only be used for bindings to external libraries whose interface already relies on this assumption.

castPtrToFunPtr :: Ptr a -> FunPtr b Source

Casts a `Ptr` to a `FunPtr`.

Note: this is valid only on architectures where data and function pointers range over the same set of addresses, and should only be used for bindings to external libraries whose interface already relies on this assumption.

freeHaskellFunPtr :: FunPtr a -> IO () Source

Release the storage associated with the given `FunPtr`, which must have been obtained from a wrapper stub. This should be called whenever the return value from a foreign import wrapper function is no longer required; otherwise, the storage it uses will leak.

# Integral types with lossless conversion to and from pointers

data IntPtr Source

A signed integral type that can be losslessly converted to and from `Ptr`. This type is also compatible with the C99 type `intptr_t`, and can be marshalled to and from that type safely.

Instances

Bounded IntPtr |
Methods minBound :: IntPtr Source maxBound :: IntPtr Source
Enum IntPtr |
Methods succ :: IntPtr -> IntPtr Source pred :: IntPtr -> IntPtr Source toEnum :: Int -> IntPtr Source fromEnum :: IntPtr -> Int Source enumFrom :: IntPtr -> [IntPtr] Source enumFromThen :: IntPtr -> IntPtr -> [IntPtr] Source enumFromTo :: IntPtr -> IntPtr -> [IntPtr] Source enumFromThenTo :: IntPtr -> IntPtr -> IntPtr -> [IntPtr] Source
Eq IntPtr |
Methods (==) :: IntPtr -> IntPtr -> Bool Source (/=) :: IntPtr -> IntPtr -> Bool Source
Integral IntPtr |
Methods quot :: IntPtr -> IntPtr -> IntPtr Source rem :: IntPtr -> IntPtr -> IntPtr Source div :: IntPtr -> IntPtr -> IntPtr Source mod :: IntPtr -> IntPtr -> IntPtr Source quotRem :: IntPtr -> IntPtr -> (IntPtr, IntPtr) Source divMod :: IntPtr -> IntPtr -> (IntPtr, IntPtr) Source toInteger :: IntPtr -> Integer Source
Num IntPtr |
Methods (+) :: IntPtr -> IntPtr -> IntPtr Source (-) :: IntPtr -> IntPtr -> IntPtr Source (*) :: IntPtr -> IntPtr -> IntPtr Source negate :: IntPtr -> IntPtr Source abs :: IntPtr -> IntPtr Source signum :: IntPtr -> IntPtr Source fromInteger :: Integer -> IntPtr Source
Ord IntPtr |
Methods compare :: IntPtr -> IntPtr -> Ordering Source (<) :: IntPtr -> IntPtr -> Bool Source (<=) :: IntPtr -> IntPtr -> Bool Source (>) :: IntPtr -> IntPtr -> Bool Source (>=) :: IntPtr -> IntPtr -> Bool Source max :: IntPtr -> IntPtr -> IntPtr Source min :: IntPtr -> IntPtr -> IntPtr Source
Read IntPtr |
Methods readsPrec :: Int -> ReadS IntPtr Source readList :: ReadS [IntPtr] Source readPrec :: ReadPrec IntPtr Source readListPrec :: ReadPrec [IntPtr] Source
Real IntPtr |
Methods toRational :: IntPtr -> Rational Source
Show IntPtr |
Methods showsPrec :: Int -> IntPtr -> ShowS Source show :: IntPtr -> String Source showList :: [IntPtr] -> ShowS Source
FiniteBits IntPtr |
Methods finiteBitSize :: IntPtr -> Int Source countLeadingZeros :: IntPtr -> Int Source countTrailingZeros :: IntPtr -> Int Source
Bits IntPtr |
Methods (.&.) :: IntPtr -> IntPtr -> IntPtr Source (.|.) :: IntPtr -> IntPtr -> IntPtr Source xor :: IntPtr -> IntPtr -> IntPtr Source complement :: IntPtr -> IntPtr Source shift :: IntPtr -> Int -> IntPtr Source rotate :: IntPtr -> Int -> IntPtr Source zeroBits :: IntPtr Source bit :: Int -> IntPtr Source setBit :: IntPtr -> Int -> IntPtr Source clearBit :: IntPtr -> Int -> IntPtr Source complementBit :: IntPtr -> Int -> IntPtr Source testBit :: IntPtr -> Int -> Bool Source bitSizeMaybe :: IntPtr -> Maybe Int Source bitSize :: IntPtr -> Int Source isSigned :: IntPtr -> Bool Source shiftL :: IntPtr -> Int -> IntPtr Source unsafeShiftL :: IntPtr -> Int -> IntPtr Source shiftR :: IntPtr -> Int -> IntPtr Source unsafeShiftR :: IntPtr -> Int -> IntPtr Source rotateL :: IntPtr -> Int -> IntPtr Source rotateR :: IntPtr -> Int -> IntPtr Source popCount :: IntPtr -> Int Source
Storable IntPtr |
Methods sizeOf :: IntPtr -> Int Source alignment :: IntPtr -> Int Source peekElemOff :: Ptr IntPtr -> Int -> IO IntPtr Source pokeElemOff :: Ptr IntPtr -> Int -> IntPtr -> IO () Source peekByteOff :: Ptr b -> Int -> IO IntPtr Source pokeByteOff :: Ptr b -> Int -> IntPtr -> IO () Source peek :: Ptr IntPtr -> IO IntPtr Source poke :: Ptr IntPtr -> IntPtr -> IO () Source

ptrToIntPtr :: Ptr a -> IntPtr Source

casts a `Ptr` to an `IntPtr`

intPtrToPtr :: IntPtr -> Ptr a Source

casts an `IntPtr` to a `Ptr`

data WordPtr Source

An unsigned integral type that can be losslessly converted to and from `Ptr`. This type is also compatible with the C99 type `uintptr_t`, and can be marshalled to and from that type safely.

Instances

Bounded WordPtr |
Methods minBound :: WordPtr Source maxBound :: WordPtr Source
Enum WordPtr |
Methods succ :: WordPtr -> WordPtr Source pred :: WordPtr -> WordPtr Source toEnum :: Int -> WordPtr Source fromEnum :: WordPtr -> Int Source enumFrom :: WordPtr -> [WordPtr] Source enumFromThen :: WordPtr -> WordPtr -> [WordPtr] Source enumFromTo :: WordPtr -> WordPtr -> [WordPtr] Source enumFromThenTo :: WordPtr -> WordPtr -> WordPtr -> [WordPtr] Source
Eq WordPtr |
Methods (==) :: WordPtr -> WordPtr -> Bool Source (/=) :: WordPtr -> WordPtr -> Bool Source
Integral WordPtr |
Methods quot :: WordPtr -> WordPtr -> WordPtr Source rem :: WordPtr -> WordPtr -> WordPtr Source div :: WordPtr -> WordPtr -> WordPtr Source mod :: WordPtr -> WordPtr -> WordPtr Source quotRem :: WordPtr -> WordPtr -> (WordPtr, WordPtr) Source divMod :: WordPtr -> WordPtr -> (WordPtr, WordPtr) Source toInteger :: WordPtr -> Integer Source
Num WordPtr |
Methods (+) :: WordPtr -> WordPtr -> WordPtr Source (-) :: WordPtr -> WordPtr -> WordPtr Source (*) :: WordPtr -> WordPtr -> WordPtr Source negate :: WordPtr -> WordPtr Source abs :: WordPtr -> WordPtr Source signum :: WordPtr -> WordPtr Source fromInteger :: Integer -> WordPtr Source
Ord WordPtr |
Methods compare :: WordPtr -> WordPtr -> Ordering Source (<) :: WordPtr -> WordPtr -> Bool Source (<=) :: WordPtr -> WordPtr -> Bool Source (>) :: WordPtr -> WordPtr -> Bool Source (>=) :: WordPtr -> WordPtr -> Bool Source max :: WordPtr -> WordPtr -> WordPtr Source min :: WordPtr -> WordPtr -> WordPtr Source
Read WordPtr |
Methods readsPrec :: Int -> ReadS WordPtr Source readList :: ReadS [WordPtr] Source readPrec :: ReadPrec WordPtr Source readListPrec :: ReadPrec [WordPtr] Source
Real WordPtr |
Methods toRational :: WordPtr -> Rational Source
Show WordPtr |
Methods showsPrec :: Int -> WordPtr -> ShowS Source show :: WordPtr -> String Source showList :: [WordPtr] -> ShowS Source
FiniteBits WordPtr |
Methods finiteBitSize :: WordPtr -> Int Source countLeadingZeros :: WordPtr -> Int Source countTrailingZeros :: WordPtr -> Int Source
Bits WordPtr |
Methods (.&.) :: WordPtr -> WordPtr -> WordPtr Source (.|.) :: WordPtr -> WordPtr -> WordPtr Source xor :: WordPtr -> WordPtr -> WordPtr Source complement :: WordPtr -> WordPtr Source shift :: WordPtr -> Int -> WordPtr Source rotate :: WordPtr -> Int -> WordPtr Source zeroBits :: WordPtr Source bit :: Int -> WordPtr Source setBit :: WordPtr -> Int -> WordPtr Source clearBit :: WordPtr -> Int -> WordPtr Source complementBit :: WordPtr -> Int -> WordPtr Source testBit :: WordPtr -> Int -> Bool Source bitSizeMaybe :: WordPtr -> Maybe Int Source bitSize :: WordPtr -> Int Source isSigned :: WordPtr -> Bool Source shiftL :: WordPtr -> Int -> WordPtr Source unsafeShiftL :: WordPtr -> Int -> WordPtr Source shiftR :: WordPtr -> Int -> WordPtr Source unsafeShiftR :: WordPtr -> Int -> WordPtr Source rotateL :: WordPtr -> Int -> WordPtr Source rotateR :: WordPtr -> Int -> WordPtr Source popCount :: WordPtr -> Int Source
Storable WordPtr |
Methods sizeOf :: WordPtr -> Int Source alignment :: WordPtr -> Int Source peekElemOff :: Ptr WordPtr -> Int -> IO WordPtr Source pokeElemOff :: Ptr WordPtr -> Int -> WordPtr -> IO () Source peekByteOff :: Ptr b -> Int -> IO WordPtr Source pokeByteOff :: Ptr b -> Int -> WordPtr -> IO () Source peek :: Ptr WordPtr -> IO WordPtr Source poke :: Ptr WordPtr -> WordPtr -> IO () Source

ptrToWordPtr :: Ptr a -> WordPtr Source

casts a `Ptr` to a `WordPtr`

wordPtrToPtr :: WordPtr -> Ptr a Source

casts a `WordPtr` to a `Ptr`