<!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>Data.ByteString.Unsafe</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_Data-ByteString-Unsafe.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">bytestring-0.9.2.1: Fast, packed, strict and lazy byte arrays with a list interface</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>experimental</td></tr><tr><th>Maintainer</th><td>dons@cse.unsw.edu.au, duncan@haskell.org</td></tr><tr><th>Safe Haskell</th><td>None</td></tr></table><p class="caption">Data.ByteString.Unsafe</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Unchecked access </a></li><li><a href="#g:2">Low level interaction with CStrings </a><ul><li><a href="#g:3">Using ByteStrings with functions for CStrings </a></li><li><a href="#g:4">Converting CStrings to ByteStrings </a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>A module containing unsafe <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code> operations. </p><p>While these functions have a stable API and you may use these functions in applications, do carefully consider the documented pre-conditions; incorrect use can break referential transparency or worse. </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"><a href="#v:unsafeHead">unsafeHead</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></li><li class="src short"><a href="#v:unsafeTail">unsafeTail</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeIndex">unsafeIndex</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></li><li class="src short"><a href="#v:unsafeTake">unsafeTake</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeDrop">unsafeDrop</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeUseAsCString">unsafeUseAsCString</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:unsafeUseAsCStringLen">unsafeUseAsCStringLen</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:unsafePackCString">unsafePackCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackCStringLen">unsafePackCStringLen</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackMallocCString">unsafePackMallocCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackAddress">unsafePackAddress</a> :: <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackAddressLen">unsafePackAddressLen</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackCStringFinalizer">unsafePackCStringFinalizer</a> :: <a href="../base-4.5.1.0/Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeFinalize">unsafeFinalize</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li></ul></div><div id="interface"><h1 id="g:1">Unchecked access </h1><div class="top"><p class="src"><a name="v:unsafeHead" class="def">unsafeHead</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:head">head</a></code> for non-empty ByteStrings. <code><a href="Data-ByteString-Unsafe.html#v:unsafeHead">unsafeHead</a></code> omits the check for the empty case, so there is an obligation on the programmer to provide a proof that the ByteString is non-empty. </p></div></div><div class="top"><p class="src"><a name="v:unsafeTail" class="def">unsafeTail</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:tail">tail</a></code> for non-empty ByteStrings. <code><a href="Data-ByteString-Unsafe.html#v:unsafeTail">unsafeTail</a></code> omits the check for the empty case. As with <code><a href="Data-ByteString-Unsafe.html#v:unsafeHead">unsafeHead</a></code>, the programmer must provide a separate proof that the ByteString is non-empty. </p></div></div><div class="top"><p class="src"><a name="v:unsafeIndex" class="def">unsafeIndex</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></p><div class="doc"><p>Unsafe <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code> index (subscript) operator, starting from 0, returning a <code><a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></code> This omits the bounds check, which means there is an accompanying obligation on the programmer to ensure the bounds are checked in some other way. </p></div></div><div class="top"><p class="src"><a name="v:unsafeTake" class="def">unsafeTake</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:take">take</a></code> which omits the checks on <code>n</code> so there is an obligation on the programmer to provide a proof that <code>0 <= n <= <code><a href="../base-4.5.1.0/Data-List.html#v:length">length</a></code> xs</code>. </p></div></div><div class="top"><p class="src"><a name="v:unsafeDrop" class="def">unsafeDrop</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:drop">drop</a></code> which omits the checks on <code>n</code> so there is an obligation on the programmer to provide a proof that <code>0 <= n <= <code><a href="../base-4.5.1.0/Data-List.html#v:length">length</a></code> xs</code>. </p></div></div><h1 id="g:2">Low level interaction with CStrings </h1><h2 id="g:3">Using ByteStrings with functions for CStrings </h2><div class="top"><p class="src"><a name="v:unsafeUseAsCString" class="def">unsafeUseAsCString</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</p><div class="doc"><p><em>O(1) construction</em> Use a <code>ByteString</code> with a function requiring a <code>CString</code>. </p><p>This function does zero copying, and merely unwraps a <code>ByteString</code> to appear as a <code>CString</code>. It is <em>unsafe</em> in two ways: </p><ul><li> After calling this function the <code>CString</code> shares the underlying byte buffer with the original <code>ByteString</code>. Thus modifying the <code>CString</code>, either in C, or using poke, will cause the contents of the <code>ByteString</code> to change, breaking referential transparency. Other <code>ByteStrings</code> created by sharing (such as those produced via <code><a href="../base-4.5.1.0/Data-List.html#v:take">take</a></code> or <code><a href="../base-4.5.1.0/Data-List.html#v:drop">drop</a></code>) will also reflect these changes. Modifying the <code>CString</code> will break referential transparency. To avoid this, use <code>useAsCString</code>, which makes a copy of the original <code>ByteString</code>. </li><li> <code>CStrings</code> are often passed to functions that require them to be null-terminated. If the original <code>ByteString</code> wasn't null terminated, neither will the <code>CString</code> be. It is the programmers responsibility to guarantee that the <code>ByteString</code> is indeed null terminated. If in doubt, use <code>useAsCString</code>. </li></ul></div></div><div class="top"><p class="src"><a name="v:unsafeUseAsCStringLen" class="def">unsafeUseAsCStringLen</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</p><div class="doc"><p><em>O(1) construction</em> Use a <code>ByteString</code> with a function requiring a <code>CStringLen</code>. </p><p>This function does zero copying, and merely unwraps a <code>ByteString</code> to appear as a <code>CStringLen</code>. It is <em>unsafe</em>: </p><ul><li> After calling this function the <code>CStringLen</code> shares the underlying byte buffer with the original <code>ByteString</code>. Thus modifying the <code>CStringLen</code>, either in C, or using poke, will cause the contents of the <code>ByteString</code> to change, breaking referential transparency. Other <code>ByteStrings</code> created by sharing (such as those produced via <code><a href="../base-4.5.1.0/Data-List.html#v:take">take</a></code> or <code><a href="../base-4.5.1.0/Data-List.html#v:drop">drop</a></code>) will also reflect these changes. Modifying the <code>CStringLen</code> will break referential transparency. To avoid this, use <code>useAsCStringLen</code>, which makes a copy of the original <code>ByteString</code>. </li></ul></div></div><h2 id="g:4">Converting CStrings to ByteStrings </h2><div class="top"><p class="src"><a name="v:unsafePackCString" class="def">unsafePackCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(n)</em> Build a <code>ByteString</code> from a <code>CString</code>. This value will have <em>no</em> finalizer associated to it, and will not be garbage collected by Haskell. The ByteString length is calculated using <em>strlen(3)</em>, and thus the complexity is a <em>O(n)</em>. </p><p>This function is <em>unsafe</em>. If the <code>CString</code> is later modified, this change will be reflected in the resulting <code>ByteString</code>, breaking referential transparency. </p></div></div><div class="top"><p class="src"><a name="v:unsafePackCStringLen" class="def">unsafePackCStringLen</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(1)</em> Build a <code>ByteString</code> from a <code>CStringLen</code>. This value will have <em>no</em> finalizer associated with it, and will not be garbage collected by Haskell. This operation has <em>O(1)</em> complexity as we already know the final size, so no <em>strlen(3)</em> is required. </p><p>This funtion is <em>unsafe</em>. If the original <code>CStringLen</code> is later modified, this change will be reflected in the resulting <code>ByteString</code>, breaking referential transparency. </p></div></div><div class="top"><p class="src"><a name="v:unsafePackMallocCString" class="def">unsafePackMallocCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(n)</em> Build a <code>ByteString</code> from a malloced <code>CString</code>. This value will have a <code>free(3)</code> finalizer associated to it. </p><p>This funtion is <em>unsafe</em>. If the original <code>CString</code> is later modified, this change will be reflected in the resulting <code>ByteString</code>, breaking referential transparency. </p><p>This function is also unsafe if you call its finalizer twice, which will result in a <em>double free</em> error, or if you pass it a CString not allocated with <code>malloc</code>. </p></div></div><div class="top"><p class="src"><a name="v:unsafePackAddress" class="def">unsafePackAddress</a> :: <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(n)</em> Pack a null-terminated sequence of bytes, pointed to by an Addr# (an arbitrary machine address assumed to point outside the garbage-collected heap) into a <code>ByteString</code>. A much faster way to create an Addr# is with an unboxed string literal, than to pack a boxed string. A unboxed string literal is compiled to a static <code>char []</code> by GHC. Establishing the length of the string requires a call to <code>strlen(3)</code>, so the Addr# must point to a null-terminated buffer (as is the case with <a href="string.html">string</a># literals in GHC). Use <code><a href="Data-ByteString-Unsafe.html#v:unsafePackAddressLen">unsafePackAddressLen</a></code> if you know the length of the string statically. </p><p>An example: </p><pre> literalFS = unsafePackAddress "literal"# </pre><p>This function is <em>unsafe</em>. If you modify the buffer pointed to by the original Addr# this modification will be reflected in the resulting <code>ByteString</code>, breaking referential transparency. </p><p>Note this also won't work if you Add# has embedded '\0' characters in the string (strlen will fail). </p></div></div><div class="top"><p class="src"><a name="v:unsafePackAddressLen" class="def">unsafePackAddressLen</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(1)</em> <code><a href="Data-ByteString-Unsafe.html#v:unsafePackAddressLen">unsafePackAddressLen</a></code> provides constant-time construction of <code>ByteStrings</code> which is ideal for string literals. It packs a sequence of bytes into a <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code>, given a raw <code><a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a></code> to the string, and the length of the string. </p><p>This function is <em>unsafe</em> in two ways: </p><ul><li> the length argument is assumed to be correct. If the length argument is incorrect, it is possible to overstep the end of the byte array. </li><li> if the underying Addr# is later modified, this change will be reflected in resulting <code>ByteString</code>, breaking referential transparency. </li></ul><p>If in doubt, don't use these functions. </p></div></div><div class="top"><p class="src"><a name="v:unsafePackCStringFinalizer" class="def">unsafePackCStringFinalizer</a> :: <a href="../base-4.5.1.0/Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(1)</em> Construct a <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code> given a Ptr Word8 to a buffer, a length, and an IO action representing a finalizer. This function is not available on Hugs. </p><p>This function is <em>unsafe</em>, it is possible to break referential transparency by modifying the underlying buffer pointed to by the first argument. Any changes to the original buffer will be reflected in the resulting <code>ByteString</code>. </p></div></div><div class="top"><p class="src"><a name="v:unsafeFinalize" class="def">unsafeFinalize</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></p><div class="doc"><p>Explicitly run the finaliser associated with a <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code>. References to this value after finalisation may generate invalid memory references. </p><p>This function is <em>unsafe</em>, as there may be other <code>ByteStrings</code> referring to the same underlying pages. If you use this, you need to have a proof of some kind that all <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code>s ever generated from the underlying byte array are no longer live. </p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.11.0</p></div></body></html>