--
-- * 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
-- | 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
--
-- * 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
--
-- * 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
--
-- * 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__
-- | 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__
--
-- * 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__
--
-- * 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__
--
-- * 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
-- | 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
--
-- * 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
--
-- * 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