Sophie: ghc-doc-0:6.10.4-1mdv2010.0 i586

ghc-doc-6.10.4-1mdv2010.0.i586.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--Rendered using the Haskell Html Library v0.2-->
<HTML
><HEAD
><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"
><TITLE
>Foreign.C.String</TITLE
><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css"
><SCRIPT SRC="haddock-util.js" TYPE="text/javascript"
></SCRIPT
><SCRIPT TYPE="text/javascript"
>window.onload = function () {setSynopsis("mini_Foreign-C-String.html")};</SCRIPT
></HEAD
><BODY
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="topbar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" "
></TD
><TD CLASS="title"
>base-4.1.0.0: Basic libraries</TD
><TD CLASS="topbut"
><A HREF="index.html"
>Contents</A
></TD
><TD CLASS="topbut"
><A HREF="doc-index.html"
>Index</A
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="modulebar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><FONT SIZE="6"
>Foreign.C.String</FONT
></TD
><TD ALIGN="right"
><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="infohead"
>Portability</TD
><TD CLASS="infoval"
>portable</TD
></TR
><TR
><TD CLASS="infohead"
>Stability</TD
><TD CLASS="infoval"
>provisional</TD
></TR
><TR
><TD CLASS="infohead"
>Maintainer</TD
><TD CLASS="infoval"
>ffi@haskell.org</TD
></TR
></TABLE
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="section4"
><B
>Contents</B
></TD
></TR
><TR
><TD
><DL
><DT
><A HREF="#1"
>C strings
</A
></DT
><DD
><DL
><DT
><A HREF="#2"
>Using a locale-dependent encoding
</A
></DT
><DT
><A HREF="#3"
>Using 8-bit characters
</A
></DT
></DL
></DD
><DT
><A HREF="#4"
>C wide strings
</A
></DT
></DL
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Description</TD
></TR
><TR
><TD CLASS="doc"
><P
>Utilities for primitive marshalling of C strings.
</P
><P
>The marshalling converts each Haskell character, representing a Unicode
 code point, to one or more bytes in a manner that, by default, is
 determined by the current locale.  As a consequence, no guarantees
 can be made about the relative length of a Haskell string and its
 corresponding C string, and therefore all the marshalling routines
 include memory allocation.  The translation between Unicode and the
 encoding of the current locale may be lossy.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Synopsis</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A HREF="#t%3ACString"
>CString</A
> = <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A HREF="#t%3ACStringLen"
>CStringLen</A
> = (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
>, <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
>)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ApeekCString"
>peekCString</A
> :: <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ApeekCStringLen"
>peekCStringLen</A
> :: <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewCString"
>newCString</A
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewCStringLen"
>newCStringLen</A
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithCString"
>withCString</A
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithCStringLen"
>withCStringLen</A
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AcharIsRepresentable"
>charIsRepresentable</A
> :: <A HREF="../ghc-prim/GHC-Types.html#t%3AChar"
>Char</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Bool.html#t%3ABool"
>Bool</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AcastCharToCChar"
>castCharToCChar</A
> :: <A HREF="../ghc-prim/GHC-Types.html#t%3AChar"
>Char</A
> -&gt; <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AcastCCharToChar"
>castCCharToChar</A
> :: <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
> -&gt; <A HREF="../ghc-prim/GHC-Types.html#t%3AChar"
>Char</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ApeekCAString"
>peekCAString</A
> :: <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ApeekCAStringLen"
>peekCAStringLen</A
> :: <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewCAString"
>newCAString</A
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewCAStringLen"
>newCAStringLen</A
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithCAString"
>withCAString</A
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithCAStringLen"
>withCAStringLen</A
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A HREF="#t%3ACWString"
>CWString</A
> = <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACWchar"
>CWchar</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A HREF="#t%3ACWStringLen"
>CWStringLen</A
> = (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACWchar"
>CWchar</A
>, <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
>)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ApeekCWString"
>peekCWString</A
> :: <A HREF="Foreign-C-String.html#t%3ACWString"
>CWString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ApeekCWStringLen"
>peekCWStringLen</A
> :: <A HREF="Foreign-C-String.html#t%3ACWStringLen"
>CWStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewCWString"
>newCWString</A
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACWString"
>CWString</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewCWStringLen"
>newCWStringLen</A
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACWStringLen"
>CWStringLen</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithCWString"
>withCWString</A
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACWString"
>CWString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithCWStringLen"
>withCWStringLen</A
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACWStringLen"
>CWStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="1"
><A NAME="1"
>C strings
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A NAME="t:CString"
><A NAME="t%3ACString"
></A
></A
><B
>CString</B
> = <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
></TD
></TR
><TR
><TD CLASS="doc"
>A C string is a reference to an array of C characters terminated by NUL.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A NAME="t:CStringLen"
><A NAME="t%3ACStringLen"
></A
></A
><B
>CStringLen</B
> = (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
>, <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
>)</TD
></TR
><TR
><TD CLASS="doc"
>A string with explicit length information in bytes instead of a
 terminating NUL (allowing NUL characters in the middle of the string).
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="2"
><A NAME="2"
>Using a locale-dependent encoding
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
>Currently these functions are identical to their <TT
>CAString</TT
> counterparts;
 eventually they will use an encoding determined by the current locale.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:peekCString"
><A NAME="v%3ApeekCString"
></A
></A
><B
>peekCString</B
> :: <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="doc"
>Marshal a NUL terminated C string into a Haskell string.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:peekCStringLen"
><A NAME="v%3ApeekCStringLen"
></A
></A
><B
>peekCStringLen</B
> :: <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="doc"
>Marshal a C string with explicit length into a Haskell string.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newCString"
><A NAME="v%3AnewCString"
></A
></A
><B
>newCString</B
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C string.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> new storage is allocated for the C string and must be
   explicitly freed using Foreign.Marshal.Alloc.free or
   Foreign.Marshal.Alloc.finalizerFree.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newCStringLen"
><A NAME="v%3AnewCStringLen"
></A
></A
><B
>newCStringLen</B
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a C string (ie, character array) with
 explicit length information.
</P
><UL
><LI
> new storage is allocated for the C string and must be
   explicitly freed using Foreign.Marshal.Alloc.free or
   Foreign.Marshal.Alloc.finalizerFree.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withCString"
><A NAME="v%3AwithCString"
></A
></A
><B
>withCString</B
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C string using temporary
 storage.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> the memory is freed when the subcomputation terminates (either
   normally or via an exception), so the pointer to the temporary
   storage must <EM
>not</EM
> be used after this.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withCStringLen"
><A NAME="v%3AwithCStringLen"
></A
></A
><B
>withCStringLen</B
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a C string (ie, character array)
 in temporary storage, with explicit length information.
</P
><UL
><LI
> the memory is freed when the subcomputation terminates (either
   normally or via an exception), so the pointer to the temporary
   storage must <EM
>not</EM
> be used after this.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:charIsRepresentable"
><A NAME="v%3AcharIsRepresentable"
></A
></A
><B
>charIsRepresentable</B
> :: <A HREF="../ghc-prim/GHC-Types.html#t%3AChar"
>Char</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Bool.html#t%3ABool"
>Bool</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Determines whether a character can be accurately encoded in a <TT
><A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
></TT
>.
 Unrepresentable characters are converted to <TT
>'?'</TT
>.
</P
><P
>Currently only Latin-1 characters are representable.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="3"
><A NAME="3"
>Using 8-bit characters
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
>These variants of the above functions are for use with C libraries
 that are ignorant of Unicode.  These functions should be used with
 care, as a loss of information can occur.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:castCharToCChar"
><A NAME="v%3AcastCharToCChar"
></A
></A
><B
>castCharToCChar</B
> :: <A HREF="../ghc-prim/GHC-Types.html#t%3AChar"
>Char</A
> -&gt; <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
></TD
></TR
><TR
><TD CLASS="doc"
>Convert a Haskell character to a C character.
 This function is only safe on the first 256 characters.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:castCCharToChar"
><A NAME="v%3AcastCCharToChar"
></A
></A
><B
>castCCharToChar</B
> :: <A HREF="Foreign-C-Types.html#t%3ACChar"
>CChar</A
> -&gt; <A HREF="../ghc-prim/GHC-Types.html#t%3AChar"
>Char</A
></TD
></TR
><TR
><TD CLASS="doc"
>Convert a C byte, representing a Latin-1 character, to the corresponding
 Haskell character.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:peekCAString"
><A NAME="v%3ApeekCAString"
></A
></A
><B
>peekCAString</B
> :: <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="doc"
>Marshal a NUL terminated C string into a Haskell string.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:peekCAStringLen"
><A NAME="v%3ApeekCAStringLen"
></A
></A
><B
>peekCAStringLen</B
> :: <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="doc"
>Marshal a C string with explicit length into a Haskell string.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newCAString"
><A NAME="v%3AnewCAString"
></A
></A
><B
>newCAString</B
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C string.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> new storage is allocated for the C string and must be
   explicitly freed using Foreign.Marshal.Alloc.free or
   Foreign.Marshal.Alloc.finalizerFree.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newCAStringLen"
><A NAME="v%3AnewCAStringLen"
></A
></A
><B
>newCAStringLen</B
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a C string (ie, character array) with
 explicit length information.
</P
><UL
><LI
> new storage is allocated for the C string and must be
   explicitly freed using Foreign.Marshal.Alloc.free or
   Foreign.Marshal.Alloc.finalizerFree.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withCAString"
><A NAME="v%3AwithCAString"
></A
></A
><B
>withCAString</B
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACString"
>CString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C string using temporary
 storage.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> the memory is freed when the subcomputation terminates (either
   normally or via an exception), so the pointer to the temporary
   storage must <EM
>not</EM
> be used after this.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withCAStringLen"
><A NAME="v%3AwithCAStringLen"
></A
></A
><B
>withCAStringLen</B
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACStringLen"
>CStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a C string (ie, character array)
 in temporary storage, with explicit length information.
</P
><UL
><LI
> the memory is freed when the subcomputation terminates (either
   normally or via an exception), so the pointer to the temporary
   storage must <EM
>not</EM
> be used after this.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
><A NAME="4"
><A NAME="4"
>C wide strings
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="doc"
><P
>These variants of the above functions are for use with C libraries
 that encode Unicode using the C <TT
>wchar_t</TT
> type in a system-dependent
 way.  The only encodings supported are
</P
><UL
><LI
> UTF-32 (the C compiler defines <TT
>__STDC_ISO_10646__</TT
>), or
</LI
><LI
> UTF-16 (as used on Windows systems).
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A NAME="t:CWString"
><A NAME="t%3ACWString"
></A
></A
><B
>CWString</B
> = <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACWchar"
>CWchar</A
></TD
></TR
><TR
><TD CLASS="doc"
>A C wide string is a reference to an array of C wide characters
 terminated by NUL.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A NAME="t:CWStringLen"
><A NAME="t%3ACWStringLen"
></A
></A
><B
>CWStringLen</B
> = (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> <A HREF="Foreign-C-Types.html#t%3ACWchar"
>CWchar</A
>, <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
>)</TD
></TR
><TR
><TD CLASS="doc"
>A wide character string with explicit length information in <TT
><A HREF="Foreign-C-Types.html#t%3ACWchar"
>CWchar</A
></TT
>s
 instead of a terminating NUL (allowing NUL characters in the middle
 of the string).
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:peekCWString"
><A NAME="v%3ApeekCWString"
></A
></A
><B
>peekCWString</B
> :: <A HREF="Foreign-C-String.html#t%3ACWString"
>CWString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="doc"
>Marshal a NUL terminated C wide string into a Haskell string.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:peekCWStringLen"
><A NAME="v%3ApeekCWStringLen"
></A
></A
><B
>peekCWStringLen</B
> :: <A HREF="Foreign-C-String.html#t%3ACWStringLen"
>CWStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Data-Char.html#t%3AString"
>String</A
></TD
></TR
><TR
><TD CLASS="doc"
>Marshal a C wide string with explicit length into a Haskell string.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newCWString"
><A NAME="v%3AnewCWString"
></A
></A
><B
>newCWString</B
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACWString"
>CWString</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C wide string.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> new storage is allocated for the C wide string and must
   be explicitly freed using Foreign.Marshal.Alloc.free or
   Foreign.Marshal.Alloc.finalizerFree.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newCWStringLen"
><A NAME="v%3AnewCWStringLen"
></A
></A
><B
>newCWStringLen</B
> :: <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="Foreign-C-String.html#t%3ACWStringLen"
>CWStringLen</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a C wide string (ie, wide character array)
 with explicit length information.
</P
><UL
><LI
> new storage is allocated for the C wide string and must
   be explicitly freed using Foreign.Marshal.Alloc.free or
   Foreign.Marshal.Alloc.finalizerFree.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withCWString"
><A NAME="v%3AwithCWString"
></A
></A
><B
>withCWString</B
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACWString"
>CWString</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C wide string using
 temporary storage.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> the memory is freed when the subcomputation terminates (either
   normally or via an exception), so the pointer to the temporary
   storage must <EM
>not</EM
> be used after this.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withCWStringLen"
><A NAME="v%3AwithCWStringLen"
></A
></A
><B
>withCWStringLen</B
> ::  <A HREF="Data-Char.html#t%3AString"
>String</A
> -&gt; (<A HREF="Foreign-C-String.html#t%3ACWStringLen"
>CWStringLen</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>Marshal a Haskell string into a NUL terminated C wide string using
 temporary storage.
</P
><UL
><LI
> the Haskell string may <EM
>not</EM
> contain any NUL characters
</LI
><LI
> the memory is freed when the subcomputation terminates (either
   normally or via an exception), so the pointer to the temporary
   storage must <EM
>not</EM
> be used after this.
</LI
></UL
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="botbar"
>Produced by <A HREF="http://www.haskell.org/haddock/"
>Haddock</A
> version 2.4.2</TD
></TR
></TABLE
></BODY
></HTML
>