Ptr.hs 2.81 KB
Newer Older
1
{-# LANGUAGE Trustworthy #-}
2
{-# LANGUAGE CPP, NoImplicitPrelude, MagicHash, GeneralizedNewtypeDeriving,
3
             StandaloneDeriving #-}
4

5
-----------------------------------------------------------------------------
6
-- |
7 8
-- Module      :  Foreign.Ptr
-- Copyright   :  (c) The FFI task force 2001
9
-- License     :  BSD-style (see the file libraries/base/LICENSE)
10 11
-- 
-- Maintainer  :  ffi@haskell.org
12 13
-- Stability   :  provisional
-- Portability :  portable
14
--
15
-- This module provides typed pointers to foreign data.  It is part
16 17
-- of the Foreign Function Interface (FFI) and will normally be
-- imported via the "Foreign" module.
18 19 20 21
--
-----------------------------------------------------------------------------

module Foreign.Ptr (
22 23

    -- * Data pointers
Don Stewart's avatar
Don Stewart committed
24

25 26 27 28 29 30
    Ptr,
    nullPtr,
    castPtr,
    plusPtr,
    alignPtr,
    minusPtr,
Don Stewart's avatar
Don Stewart committed
31

32
    -- * Function pointers
Don Stewart's avatar
Don Stewart committed
33

34 35 36 37 38
    FunPtr,
    nullFunPtr,
    castFunPtr,
    castFunPtrToPtr,
    castPtrToFunPtr,
Don Stewart's avatar
Don Stewart committed
39

40
    freeHaskellFunPtr,
41 42
    -- Free the function pointer created by foreign export dynamic.

Ross Paterson's avatar
Ross Paterson committed
43
    -- * Integral types with lossless conversion to and from pointers
44 45 46 47 48 49
    IntPtr,
    ptrToIntPtr,
    intPtrToPtr,
    WordPtr,
    ptrToWordPtr,
    wordPtrToPtr
50 51 52
 ) where

import GHC.Ptr
53 54
import GHC.Base
import GHC.Num
55 56
import GHC.Read
import GHC.Real
57
import GHC.Show
58
import GHC.Enum
59

60 61 62
import Data.Bits
import Foreign.Storable ( Storable(..) )

ross's avatar
ross committed
63 64 65 66
-- | 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.
67
foreign import ccall unsafe "freeHaskellFunctionPtr"
68
    freeHaskellFunPtr :: FunPtr a -> IO ()
69

70 71
#include "HsBaseConfig.h"
#include "CTypes.h"
72

73
-- | An unsigned integral type that can be losslessly converted to and from
74 75
-- @Ptr@. This type is also compatible with the C99 type @uintptr_t@, and
-- can be marshalled to and from that type safely.
76
INTEGRAL_TYPE(WordPtr,Word)
Don Stewart's avatar
Don Stewart committed
77
        -- Word and Int are guaranteed pointer-sized in GHC
78

79
-- | A signed integral type that can be losslessly converted to and from
80 81
-- @Ptr@.  This type is also compatible with the C99 type @intptr_t@, and
-- can be marshalled to and from that type safely.
82
INTEGRAL_TYPE(IntPtr,Int)
Don Stewart's avatar
Don Stewart committed
83
        -- Word and Int are guaranteed pointer-sized in GHC
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99

-- | casts a @Ptr@ to a @WordPtr@
ptrToWordPtr :: Ptr a -> WordPtr
ptrToWordPtr (Ptr a#) = WordPtr (W# (int2Word# (addr2Int# a#)))

-- | casts a @WordPtr@ to a @Ptr@
wordPtrToPtr :: WordPtr -> Ptr a
wordPtrToPtr (WordPtr (W# w#)) = Ptr (int2Addr# (word2Int# w#))

-- | casts a @Ptr@ to an @IntPtr@
ptrToIntPtr :: Ptr a -> IntPtr
ptrToIntPtr (Ptr a#) = IntPtr (I# (addr2Int# a#))

-- | casts an @IntPtr@ to a @Ptr@
intPtrToPtr :: IntPtr -> Ptr a
intPtrToPtr (IntPtr (I# i#)) = Ptr (int2Addr# i#)