<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Foreign.C.String</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[ window.onload = function () {pageLoad();setSynopsis("mini_Foreign-C-String.html");}; //]]> </script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">base-4.3.1.0: Basic libraries</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>portable</td></tr><tr><th>Stability</th><td>provisional</td></tr><tr><th>Maintainer</th><td>ffi@haskell.org</td></tr></table><p class="caption">Foreign.C.String</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">C strings </a><ul><li><a href="#g:2">Using a locale-dependent encoding </a></li><li><a href="#g:3">Using 8-bit characters </a></li></ul></li><li><a href="#g:4">C wide strings </a></li></ul></div><div id="description"><p class="caption">Description</p><div 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></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><span class="keyword">type</span> <a href="#t:CString">CString</a> = <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CChar">CChar</a></li><li class="src short"><span class="keyword">type</span> <a href="#t:CStringLen">CStringLen</a> = (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CChar">CChar</a>, <a href="Data-Int.html#t:Int">Int</a>)</li><li class="src short"><a href="#v:peekCString">peekCString</a> :: <a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></li><li class="src short"><a href="#v:peekCStringLen">peekCStringLen</a> :: <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></li><li class="src short"><a href="#v:newCString">newCString</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CString">CString</a></li><li class="src short"><a href="#v:newCStringLen">newCStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a></li><li class="src short"><a href="#v:withCString">withCString</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:withCStringLen">withCStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:charIsRepresentable">charIsRepresentable</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Bool.html#t:Bool">Bool</a></li><li class="src short"><a href="#v:castCharToCChar">castCharToCChar</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="Foreign-C-Types.html#t:CChar">CChar</a></li><li class="src short"><a href="#v:castCCharToChar">castCCharToChar</a> :: <a href="Foreign-C-Types.html#t:CChar">CChar</a> -> <a href="Data-Char.html#t:Char">Char</a></li><li class="src short"><a href="#v:castCharToCUChar">castCharToCUChar</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="Foreign-C-Types.html#t:CUChar">CUChar</a></li><li class="src short"><a href="#v:castCUCharToChar">castCUCharToChar</a> :: <a href="Foreign-C-Types.html#t:CUChar">CUChar</a> -> <a href="Data-Char.html#t:Char">Char</a></li><li class="src short"><a href="#v:castCharToCSChar">castCharToCSChar</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="Foreign-C-Types.html#t:CSChar">CSChar</a></li><li class="src short"><a href="#v:castCSCharToChar">castCSCharToChar</a> :: <a href="Foreign-C-Types.html#t:CSChar">CSChar</a> -> <a href="Data-Char.html#t:Char">Char</a></li><li class="src short"><a href="#v:peekCAString">peekCAString</a> :: <a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></li><li class="src short"><a href="#v:peekCAStringLen">peekCAStringLen</a> :: <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></li><li class="src short"><a href="#v:newCAString">newCAString</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CString">CString</a></li><li class="src short"><a href="#v:newCAStringLen">newCAStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a></li><li class="src short"><a href="#v:withCAString">withCAString</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:withCAStringLen">withCAStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</li><li class="src short"><span class="keyword">type</span> <a href="#t:CWString">CWString</a> = <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CWchar">CWchar</a></li><li class="src short"><span class="keyword">type</span> <a href="#t:CWStringLen">CWStringLen</a> = (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CWchar">CWchar</a>, <a href="Data-Int.html#t:Int">Int</a>)</li><li class="src short"><a href="#v:peekCWString">peekCWString</a> :: <a href="Foreign-C-String.html#t:CWString">CWString</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></li><li class="src short"><a href="#v:peekCWStringLen">peekCWStringLen</a> :: <a href="Foreign-C-String.html#t:CWStringLen">CWStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></li><li class="src short"><a href="#v:newCWString">newCWString</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CWString">CWString</a></li><li class="src short"><a href="#v:newCWStringLen">newCWStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CWStringLen">CWStringLen</a></li><li class="src short"><a href="#v:withCWString">withCWString</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CWString">CWString</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:withCWStringLen">withCWStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CWStringLen">CWStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</li></ul></div><div id="interface"><h1 id="g:1">C strings </h1><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:CString" class="def">CString</a> = <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CChar">CChar</a></p><div class="doc"><p>A C string is a reference to an array of C characters terminated by NUL. </p></div></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:CStringLen" class="def">CStringLen</a> = (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CChar">CChar</a>, <a href="Data-Int.html#t:Int">Int</a>)</p><div class="doc"><p>A string with explicit length information in bytes instead of a terminating NUL (allowing NUL characters in the middle of the string). </p></div></div><h2 id="g:2">Using a locale-dependent encoding </h2><div class="doc"><p>Currently these functions are identical to their <code>CAString</code> counterparts; eventually they will use an encoding determined by the current locale. </p></div><div class="top"><p class="src"><a name="v:peekCString" class="def">peekCString</a> :: <a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></p><div class="doc"><p>Marshal a NUL terminated C string into a Haskell string. </p></div></div><div class="top"><p class="src"><a name="v:peekCStringLen" class="def">peekCStringLen</a> :: <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></p><div class="doc"><p>Marshal a C string with explicit length into a Haskell string. </p></div></div><div class="top"><p class="src"><a name="v:newCString" class="def">newCString</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CString">CString</a></p><div 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 <code>Foreign.Marshal.Alloc.free</code> or <code>Foreign.Marshal.Alloc.finalizerFree</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:newCStringLen" class="def">newCStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a></p><div 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 <code>Foreign.Marshal.Alloc.free</code> or <code>Foreign.Marshal.Alloc.finalizerFree</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:withCString" class="def">withCString</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</p><div 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></div></div><div class="top"><p class="src"><a name="v:withCStringLen" class="def">withCStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</p><div 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></div></div><div class="top"><p class="src"><a name="v:charIsRepresentable" class="def">charIsRepresentable</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Bool.html#t:Bool">Bool</a></p><div class="doc"><p>Determines whether a character can be accurately encoded in a <code><a href="Foreign-C-String.html#t:CString">CString</a></code>. Unrepresentable characters are converted to <code>'?'</code>. </p><p>Currently only Latin-1 characters are representable. </p></div></div><h2 id="g:3">Using 8-bit characters </h2><div class="doc"><p>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. </p></div><div class="top"><p class="src"><a name="v:castCharToCChar" class="def">castCharToCChar</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="Foreign-C-Types.html#t:CChar">CChar</a></p><div class="doc"><p>Convert a Haskell character to a C character. This function is only safe on the first 256 characters. </p></div></div><div class="top"><p class="src"><a name="v:castCCharToChar" class="def">castCCharToChar</a> :: <a href="Foreign-C-Types.html#t:CChar">CChar</a> -> <a href="Data-Char.html#t:Char">Char</a></p><div class="doc"><p>Convert a C byte, representing a Latin-1 character, to the corresponding Haskell character. </p></div></div><div class="top"><p class="src"><a name="v:castCharToCUChar" class="def">castCharToCUChar</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="Foreign-C-Types.html#t:CUChar">CUChar</a></p><div class="doc"><p>Convert a Haskell character to a C <code>unsigned char</code>. This function is only safe on the first 256 characters. </p></div></div><div class="top"><p class="src"><a name="v:castCUCharToChar" class="def">castCUCharToChar</a> :: <a href="Foreign-C-Types.html#t:CUChar">CUChar</a> -> <a href="Data-Char.html#t:Char">Char</a></p><div class="doc"><p>Convert a C <code>unsigned char</code>, representing a Latin-1 character, to the corresponding Haskell character. </p></div></div><div class="top"><p class="src"><a name="v:castCharToCSChar" class="def">castCharToCSChar</a> :: <a href="Data-Char.html#t:Char">Char</a> -> <a href="Foreign-C-Types.html#t:CSChar">CSChar</a></p><div class="doc"><p>Convert a Haskell character to a C <code>signed char</code>. This function is only safe on the first 256 characters. </p></div></div><div class="top"><p class="src"><a name="v:castCSCharToChar" class="def">castCSCharToChar</a> :: <a href="Foreign-C-Types.html#t:CSChar">CSChar</a> -> <a href="Data-Char.html#t:Char">Char</a></p><div class="doc"><p>Convert a C <code>signed char</code>, representing a Latin-1 character, to the corresponding Haskell character. </p></div></div><div class="top"><p class="src"><a name="v:peekCAString" class="def">peekCAString</a> :: <a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></p><div class="doc"><p>Marshal a NUL terminated C string into a Haskell string. </p></div></div><div class="top"><p class="src"><a name="v:peekCAStringLen" class="def">peekCAStringLen</a> :: <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></p><div class="doc"><p>Marshal a C string with explicit length into a Haskell string. </p></div></div><div class="top"><p class="src"><a name="v:newCAString" class="def">newCAString</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CString">CString</a></p><div 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 <code>Foreign.Marshal.Alloc.free</code> or <code>Foreign.Marshal.Alloc.finalizerFree</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:newCAStringLen" class="def">newCAStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CStringLen">CStringLen</a></p><div 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 <code>Foreign.Marshal.Alloc.free</code> or <code>Foreign.Marshal.Alloc.finalizerFree</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:withCAString" class="def">withCAString</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CString">CString</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</p><div 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></div></div><div class="top"><p class="src"><a name="v:withCAStringLen" class="def">withCAStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</p><div 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></div></div><h1 id="g:4">C wide strings </h1><div class="doc"><p>These variants of the above functions are for use with C libraries that encode Unicode using the C <code>wchar_t</code> type in a system-dependent way. The only encodings supported are </p><ul><li> UTF-32 (the C compiler defines <code>__STDC_ISO_10646__</code>), or </li><li> UTF-16 (as used on Windows systems). </li></ul></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:CWString" class="def">CWString</a> = <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CWchar">CWchar</a></p><div class="doc"><p>A C wide string is a reference to an array of C wide characters terminated by NUL. </p></div></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:CWStringLen" class="def">CWStringLen</a> = (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="Foreign-C-Types.html#t:CWchar">CWchar</a>, <a href="Data-Int.html#t:Int">Int</a>)</p><div class="doc"><p>A wide character string with explicit length information in <code><a href="Foreign-C-Types.html#t:CWchar">CWchar</a></code>s instead of a terminating NUL (allowing NUL characters in the middle of the string). </p></div></div><div class="top"><p class="src"><a name="v:peekCWString" class="def">peekCWString</a> :: <a href="Foreign-C-String.html#t:CWString">CWString</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></p><div class="doc"><p>Marshal a NUL terminated C wide string into a Haskell string. </p></div></div><div class="top"><p class="src"><a name="v:peekCWStringLen" class="def">peekCWStringLen</a> :: <a href="Foreign-C-String.html#t:CWStringLen">CWStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Data-Char.html#t:String">String</a></p><div class="doc"><p>Marshal a C wide string with explicit length into a Haskell string. </p></div></div><div class="top"><p class="src"><a name="v:newCWString" class="def">newCWString</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CWString">CWString</a></p><div 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 <code>Foreign.Marshal.Alloc.free</code> or <code>Foreign.Marshal.Alloc.finalizerFree</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:newCWStringLen" class="def">newCWStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> <a href="System-IO.html#t:IO">IO</a> <a href="Foreign-C-String.html#t:CWStringLen">CWStringLen</a></p><div 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 <code>Foreign.Marshal.Alloc.free</code> or <code>Foreign.Marshal.Alloc.finalizerFree</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:withCWString" class="def">withCWString</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CWString">CWString</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</p><div 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></div></div><div class="top"><p class="src"><a name="v:withCWStringLen" class="def">withCWStringLen</a> :: <a href="Data-Char.html#t:String">String</a> -> (<a href="Foreign-C-String.html#t:CWStringLen">CWStringLen</a> -> <a href="System-IO.html#t:IO">IO</a> a) -> <a href="System-IO.html#t:IO">IO</a> a</p><div 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></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.9.2</p></div></body></html>