W3cubDocs

/Haskell 8

Foreign.Ptr

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

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.

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 (* -> ) t => (forall d. Data d => c (t d)) -> Maybe (c (Ptr a)) Source dataCast2 :: Typeable ( -> * -> *) 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
Functor (URec (Ptr ()))
Methods fmap :: (a -> b) -> URec (Ptr ()) a -> URec (Ptr ()) b Source (<$) :: a -> URec (Ptr ()) b -> URec (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
Foldable (URec (Ptr ()))
Methods fold :: Monoid m => URec (Ptr ()) m -> m Source foldMap :: Monoid m => (a -> m) -> URec (Ptr ()) a -> m Source foldr :: (a -> b -> b) -> b -> URec (Ptr ()) a -> b Source foldr' :: (a -> b -> b) -> b -> URec (Ptr ()) a -> b Source foldl :: (b -> a -> b) -> b -> URec (Ptr ()) a -> b Source foldl' :: (b -> a -> b) -> b -> URec (Ptr ()) a -> b Source foldr1 :: (a -> a -> a) -> URec (Ptr ()) a -> a Source foldl1 :: (a -> a -> a) -> URec (Ptr ()) a -> a Source toList :: URec (Ptr ()) a -> [a] Source null :: URec (Ptr ()) a -> Bool Source length :: URec (Ptr ()) a -> Int Source elem :: Eq a => a -> URec (Ptr ()) a -> Bool Source maximum :: Ord a => URec (Ptr ()) a -> a Source minimum :: Ord a => URec (Ptr ()) a -> a Source sum :: Num a => URec (Ptr ()) a -> a Source product :: Num a => URec (Ptr ()) a -> a Source
Traversable (URec (Ptr ()))
Methods traverse :: Applicative f => (a -> f b) -> URec (Ptr ()) a -> f (URec (Ptr ()) b) Source sequenceA :: Applicative f => URec (Ptr ()) (f a) -> f (URec (Ptr ()) a) Source mapM :: Monad m => (a -> m b) -> URec (Ptr ()) a -> m (URec (Ptr ()) b) Source sequence :: Monad m => URec (Ptr ()) (m a) -> m (URec (Ptr ()) a) Source
Generic1 (URec (Ptr ()))
Associated Types type Rep1 (URec (Ptr ()) :: * -> ) :: -> * Source Methods from1 :: URec (Ptr ()) a -> Rep1 (URec (Ptr ())) a Source to1 :: Rep1 (URec (Ptr ())) a -> URec (Ptr ()) a 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
type Rep1 (URec (Ptr ()))
type Rep1 (URec (Ptr ())) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just Symbol "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) UAddr))
data URec (Ptr ())	Used for marking occurrences of `Addr#`
data URec (Ptr ()) = UAddr { uAddr# :: Addr# }
type Rep (URec (Ptr ()) p)
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.

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

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

Foreign.Ptr

Contents

Description

Data pointers

Instances

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Associated Types

Methods

Methods

Methods

Methods

Associated Types

Methods

Function pointers

Instances

Methods

Methods

Methods

Methods

Integral types with lossless conversion to and from pointers

Instances

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Instances

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods