2 {-# OPTIONS_GHC -fno-implicit-prelude #-}
3 -----------------------------------------------------------------------------
6 -- Copyright : (c) The FFI Task Force, 2000-2002
7 -- License : see libraries/base/LICENSE
9 -- Maintainer : ffi@haskell.org
10 -- Stability : internal
11 -- Portability : non-portable (GHC Extensions)
13 -- The 'Ptr' and 'FunPtr' types and operations.
15 -----------------------------------------------------------------------------
22 ------------------------------------------------------------------------
25 data Ptr a = Ptr Addr# deriving (Eq, Ord)
26 -- ^ A value of type @'Ptr' a@ represents a pointer to an object, or an
27 -- array of objects, which may be marshalled to or from Haskell values
30 -- The type @a@ will often be an instance of class
31 -- 'Foreign.Storable.Storable' which provides the marshalling operations.
32 -- However this is not essential, and you can provide your own operations
33 -- to access the pointer. For example you might write small foreign
34 -- functions to get or set the fields of a C @struct@.
36 -- |The constant 'nullPtr' contains a distinguished value of 'Ptr'
37 -- that is not associated with a valid memory location.
39 nullPtr = Ptr nullAddr#
41 -- |The 'castPtr' function casts a pointer from one type to another.
42 castPtr :: Ptr a -> Ptr b
43 castPtr (Ptr addr) = Ptr addr
45 -- |Advances the given address by the given offset in bytes.
46 plusPtr :: Ptr a -> Int -> Ptr b
47 plusPtr (Ptr addr) (I# d) = Ptr (plusAddr# addr d)
49 -- |Given an arbitrary address and an alignment constraint,
50 -- 'alignPtr' yields the next higher address that fulfills the
51 -- alignment constraint. An alignment constraint @x@ is fulfilled by
52 -- any address divisible by @x@. This operation is idempotent.
53 alignPtr :: Ptr a -> Int -> Ptr a
54 alignPtr addr@(Ptr a) (I# i)
55 = case remAddr# a i of {
57 n -> Ptr (plusAddr# a (i -# n)) }
59 -- |Computes the offset required to get from the first to the second
62 -- > p2 == p1 `plusPtr` (p2 `minusPtr` p1)
63 minusPtr :: Ptr a -> Ptr b -> Int
64 minusPtr (Ptr a1) (Ptr a2) = I# (minusAddr# a1 a2)
66 ------------------------------------------------------------------------
67 -- Function pointers for the default calling convention.
69 data FunPtr a = FunPtr Addr# deriving (Eq, Ord)
70 -- ^ A value of type @'FunPtr' a@ is a pointer to a function callable
71 -- from foreign code. The type @a@ will normally be a /foreign type/,
72 -- a function type with zero or more arguments where
74 -- * the argument types are /marshallable foreign types/,
75 -- i.e. 'Char', 'Int', 'Prelude.Double', 'Prelude.Float',
76 -- 'Bool', 'Data.Int.Int8', 'Data.Int.Int16', 'Data.Int.Int32',
77 -- 'Data.Int.Int64', 'Data.Word.Word8', 'Data.Word.Word16',
78 -- 'Data.Word.Word32', 'Data.Word.Word64', @'Ptr' a@, @'FunPtr' a@,
79 -- @'Foreign.StablePtr.StablePtr' a@ or a renaming of any of these
82 -- * the return type is either a marshallable foreign type or has the form
83 -- @'Prelude.IO' t@ where @t@ is a marshallable foreign type or @()@.
85 -- A value of type @'FunPtr' a@ may be a pointer to a foreign function,
86 -- either returned by another foreign function or imported with a
87 -- a static address import like
89 -- > foreign import ccall "stdlib.h &free"
90 -- > p_free :: FunPtr (Ptr a -> IO ())
92 -- or a pointer to a Haskell function created using a /wrapper/ stub
93 -- declared to produce a 'FunPtr' of the correct type. For example:
95 -- > type Compare = Int -> Int -> Bool
96 -- > foreign import ccall "wrapper"
97 -- > mkCompare :: Compare -> IO (FunPtr Compare)
99 -- Calls to wrapper stubs like @mkCompare@ allocate storage, which
100 -- should be released with 'Foreign.Ptr.freeHaskellFunPtr' when no
103 -- To convert 'FunPtr' values to corresponding Haskell functions, one
104 -- can define a /dynamic/ stub for the specific foreign type, e.g.
106 -- > type IntFunction = CInt -> IO ()
107 -- > foreign import ccall "dynamic"
108 -- > mkFun :: FunPtr IntFunction -> IntFunction
110 -- |The constant 'nullFunPtr' contains a
111 -- distinguished value of 'FunPtr' that is not
112 -- associated with a valid memory location.
113 nullFunPtr :: FunPtr a
114 nullFunPtr = FunPtr nullAddr#
116 -- |Casts a 'FunPtr' to a 'FunPtr' of a different type.
117 castFunPtr :: FunPtr a -> FunPtr b
118 castFunPtr (FunPtr addr) = FunPtr addr
120 -- |Casts a 'FunPtr' to a 'Ptr'.
122 -- /Note:/ this is valid only on architectures where data and function
123 -- pointers range over the same set of addresses, and should only be used
124 -- for bindings to external libraries whose interface already relies on
126 castFunPtrToPtr :: FunPtr a -> Ptr b
127 castFunPtrToPtr (FunPtr addr) = Ptr addr
129 -- |Casts a 'Ptr' to a 'FunPtr'.
131 -- /Note:/ this is valid only on architectures where data and function
132 -- pointers range over the same set of addresses, and should only be used
133 -- for bindings to external libraries whose interface already relies on
135 castPtrToFunPtr :: Ptr a -> FunPtr b
136 castPtrToFunPtr (Ptr addr) = FunPtr addr