[project @ 2005-03-03 05:11:41 by chak]

[ghc-base.git] / Foreign / C / String.hs

diff --git a/Foreign/C/String.hs b/Foreign/C/String.hs
index c624588..5654883 100644 (file)
--- a/Foreign/C/String.hs
+++ b/Foreign/C/String.hs
@@ -1,4 +1,4 @@
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Foreign.C.String
@@ -139,7 +139,9 @@ peekCStringLen = peekCAStringLen
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * new storage is allocated for the C string and must be explicitly freed
+-- * new storage is allocated for the C string and must be
+--   explicitly freed using 'Foreign.Marshal.Alloc.free' or
+--   'Foreign.Marshal.Alloc.finalizerFree'.
 --
 newCString :: String -> IO CString
 newCString = newCAString
@@ -147,7 +149,9 @@ newCString = newCAString
 -- | Marshal a Haskell string into a C string (ie, character array) with
 -- explicit length information.
 --
--- * new storage is allocated for the C string and must be explicitly freed
+-- * new storage is allocated for the C string and must be
+--   explicitly freed using 'Foreign.Marshal.Alloc.free' or
+--   'Foreign.Marshal.Alloc.finalizerFree'.
 --
 newCStringLen     :: String -> IO CStringLen
 newCStringLen = newCAStringLen
@@ -157,7 +161,9 @@ newCStringLen = newCAStringLen
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * see the lifetime constraints of 'Foreign.Marshal.Alloc.alloca'
+-- * the memory is freed when the subcomputation terminates (either
+--   normally or via an exception), so the pointer to the temporary
+--   storage must /not/ be used after this.
 --
 withCString :: String -> (CString -> IO a) -> IO a
 withCString = withCAString
@@ -167,7 +173,9 @@ withCString = withCAString
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * see the lifetime constraints of 'Foreign.Marshal.Alloc.alloca'
+-- * the memory is freed when the subcomputation terminates (either
+--   normally or via an exception), so the pointer to the temporary
+--   storage must /not/ be used after this.
 --
 withCStringLen         :: String -> (CStringLen -> IO a) -> IO a
 withCStringLen = withCAStringLen
@@ -237,7 +245,9 @@ peekCAStringLen (cp, len)
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * new storage is allocated for the C string and must be explicitly freed
+-- * new storage is allocated for the C string and must be
+--   explicitly freed using 'Foreign.Marshal.Alloc.free' or
+--   'Foreign.Marshal.Alloc.finalizerFree'.
 --
 newCAString :: String -> IO CString
 #ifndef __GLASGOW_HASKELL__
@@ -255,7 +265,9 @@ newCAString str = do
 -- | Marshal a Haskell string into a C string (ie, character array) with
 -- explicit length information.
 --
--- * new storage is allocated for the C string and must be explicitly freed
+-- * new storage is allocated for the C string and must be
+--   explicitly freed using 'Foreign.Marshal.Alloc.free' or
+--   'Foreign.Marshal.Alloc.finalizerFree'.
 --
 newCAStringLen     :: String -> IO CStringLen
 #ifndef __GLASGOW_HASKELL__
@@ -279,7 +291,9 @@ newCAStringLen str = do
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * see the lifetime constraints of 'Foreign.Marshal.Alloc.alloca'
+-- * the memory is freed when the subcomputation terminates (either
+--   normally or via an exception), so the pointer to the temporary
+--   storage must /not/ be used after this.
 --
 withCAString :: String -> (CString -> IO a) -> IO a
 #ifndef __GLASGOW_HASKELL__
@@ -300,7 +314,9 @@ withCAString str f =
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * see the lifetime constraints of 'Foreign.Marshal.Alloc.alloca'
+-- * the memory is freed when the subcomputation terminates (either
+--   normally or via an exception), so the pointer to the temporary
+--   storage must /not/ be used after this.
 --
 withCAStringLen         :: String -> (CStringLen -> IO a) -> IO a
 #ifndef __GLASGOW_HASKELL__
@@ -376,7 +392,9 @@ peekCWStringLen (cp, len)  = do
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * new storage is allocated for the C string and must be explicitly freed
+-- * new storage is allocated for the C wide string and must
+--   be explicitly freed using 'Foreign.Marshal.Alloc.free' or
+--   'Foreign.Marshal.Alloc.finalizerFree'.
 --
 newCWString :: String -> IO CWString
 newCWString  = newArray0 wNUL . charsToCWchars
@@ -384,7 +402,9 @@ newCWString  = newArray0 wNUL . charsToCWchars
 -- | Marshal a Haskell string into a C wide string (ie, wide character array)
 -- with explicit length information.
 --
--- * new storage is allocated for the C string and must be explicitly freed
+-- * new storage is allocated for the C wide string and must
+--   be explicitly freed using 'Foreign.Marshal.Alloc.free' or
+--   'Foreign.Marshal.Alloc.finalizerFree'.
 --
 newCWStringLen     :: String -> IO CWStringLen
 newCWStringLen str  = do
@@ -396,7 +416,9 @@ newCWStringLen str  = do
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * see the lifetime constraints of 'Foreign.Marshal.Alloc.alloca'
+-- * the memory is freed when the subcomputation terminates (either
+--   normally or via an exception), so the pointer to the temporary
+--   storage must /not/ be used after this.
 --
 withCWString :: String -> (CWString -> IO a) -> IO a
 withCWString  = withArray0 wNUL . charsToCWchars
@@ -406,7 +428,9 @@ withCWString  = withArray0 wNUL . charsToCWchars
 --
 -- * the Haskell string may /not/ contain any NUL characters
 --
--- * see the lifetime constraints of 'Foreign.Marshal.Alloc.alloca'
+-- * the memory is freed when the subcomputation terminates (either
+--   normally or via an exception), so the pointer to the temporary
+--   storage must /not/ be used after this.
 --
 withCWStringLen         :: String -> (CWStringLen -> IO a) -> IO a
 withCWStringLen str act  = withArray (charsToCWchars str) $ act . pairLength str
@@ -420,7 +444,7 @@ wNUL = 0
 cWcharsToChars :: [CWchar] -> [Char]
 charsToCWchars :: [Char] -> [CWchar]
 
-#ifdef mingw32_TARGET_OS
+#ifdef mingw32_HOST_OS
 
 -- On Windows, wchar_t is 16 bits wide and CWString uses the UTF-16 encoding.
 
@@ -441,7 +465,7 @@ charsToCWchars = foldr utf16Char [] . map ord
                     fromIntegral (c' `div` 0x400 + 0xd800) :
                     fromIntegral (c' `mod` 0x400 + 0xdc00) : wcs
 
-#else /* !mingw32_TARGET_OS */
+#else /* !mingw32_HOST_OS */
 
 cWcharsToChars xs  = map castCWcharToChar xs
 charsToCWchars xs  = map castCharToCWchar xs
@@ -455,4 +479,4 @@ castCWcharToChar ch = chr (fromIntegral ch )
 castCharToCWchar :: Char -> CWchar
 castCharToCWchar ch = fromIntegral (ord ch)
 
-#endif /* !mingw32_TARGET_OS */
+#endif /* !mingw32_HOST_OS */