Update Trac ticket URLs to point to GitLab
[ghc.git] / libraries / base / Foreign / Ptr.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE DerivingStrategies #-}
3 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
4 {-# LANGUAGE MagicHash #-}
5 {-# LANGUAGE NoImplicitPrelude #-}
6 {-# LANGUAGE StandaloneDeriving #-}
7 {-# LANGUAGE Trustworthy #-}
8
9 -----------------------------------------------------------------------------
10 -- |
11 -- Module : Foreign.Ptr
12 -- Copyright : (c) The FFI task force 2001
13 -- License : BSD-style (see the file libraries/base/LICENSE)
14 --
15 -- Maintainer : ffi@haskell.org
16 -- Stability : provisional
17 -- Portability : portable
18 --
19 -- This module provides typed pointers to foreign data. It is part
20 -- of the Foreign Function Interface (FFI) and will normally be
21 -- imported via the "Foreign" module.
22 --
23 -----------------------------------------------------------------------------
24
25 module Foreign.Ptr (
26
27 -- * Data pointers
28
29 Ptr,
30 nullPtr,
31 castPtr,
32 plusPtr,
33 alignPtr,
34 minusPtr,
35
36 -- * Function pointers
37
38 FunPtr,
39 nullFunPtr,
40 castFunPtr,
41 castFunPtrToPtr,
42 castPtrToFunPtr,
43
44 freeHaskellFunPtr,
45 -- Free the function pointer created by foreign export dynamic.
46
47 -- * Integral types with lossless conversion to and from pointers
48 IntPtr(..),
49 ptrToIntPtr,
50 intPtrToPtr,
51 WordPtr(..),
52 ptrToWordPtr,
53 wordPtrToPtr
54
55 -- See Note [Exporting constructors of marshallable foreign types]
56 -- for why the constructors for IntPtr and WordPtr are exported.
57 ) where
58
59 import GHC.Ptr
60 import GHC.Base
61 import GHC.Num
62 import GHC.Read
63 import GHC.Real
64 import GHC.Show
65 import GHC.Enum
66
67 import Data.Bits
68 import Foreign.Storable ( Storable(..) )
69
70 -- | Release the storage associated with the given 'FunPtr', which
71 -- must have been obtained from a wrapper stub. This should be called
72 -- whenever the return value from a foreign import wrapper function is
73 -- no longer required; otherwise, the storage it uses will leak.
74 foreign import ccall unsafe "freeHaskellFunctionPtr"
75 freeHaskellFunPtr :: FunPtr a -> IO ()
76
77 #include "HsBaseConfig.h"
78 #include "CTypes.h"
79
80 -- | An unsigned integral type that can be losslessly converted to and from
81 -- @Ptr@. This type is also compatible with the C99 type @uintptr_t@, and
82 -- can be marshalled to and from that type safely.
83 INTEGRAL_TYPE(WordPtr,Word)
84 -- Word and Int are guaranteed pointer-sized in GHC
85
86 -- | A signed integral type that can be losslessly converted to and from
87 -- @Ptr@. This type is also compatible with the C99 type @intptr_t@, and
88 -- can be marshalled to and from that type safely.
89 INTEGRAL_TYPE(IntPtr,Int)
90 -- Word and Int are guaranteed pointer-sized in GHC
91
92 -- | casts a @Ptr@ to a @WordPtr@
93 ptrToWordPtr :: Ptr a -> WordPtr
94 ptrToWordPtr (Ptr a#) = WordPtr (W# (int2Word# (addr2Int# a#)))
95
96 -- | casts a @WordPtr@ to a @Ptr@
97 wordPtrToPtr :: WordPtr -> Ptr a
98 wordPtrToPtr (WordPtr (W# w#)) = Ptr (int2Addr# (word2Int# w#))
99
100 -- | casts a @Ptr@ to an @IntPtr@
101 ptrToIntPtr :: Ptr a -> IntPtr
102 ptrToIntPtr (Ptr a#) = IntPtr (I# (addr2Int# a#))
103
104 -- | casts an @IntPtr@ to a @Ptr@
105 intPtrToPtr :: IntPtr -> Ptr a
106 intPtrToPtr (IntPtr (I# i#)) = Ptr (int2Addr# i#)
107
108 {-
109 Note [Exporting constructors of marshallable foreign types]
110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111 One might expect that IntPtr, WordPtr, and the other newtypes in the
112 Foreign.C.Types and System.Posix.Types modules to be abstract, but this is not
113 the case in GHC (see #5229 and #11983). In fact, we deliberately export
114 the constructors for these datatypes in order to satisfy a requirement of the
115 Haskell 2010 Report (ยง 8.4.2) that if a newtype is used in a foreign
116 declaration, then its constructor must be visible.
117
118 This requirement was motivated by the fact that using a type in a foreign
119 declaration necessarily exposes some information about the type to the user,
120 so being able to use abstract types in a foreign declaration breaks their
121 abstraction (see #3008). As a result, the constructors of all FFI-related
122 newtypes in base must be exported in order to be useful for FFI programming,
123 even at the cost of exposing their underlying, architecture-dependent types.
124 -}