<!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.Marshal.Alloc</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-Marshal-Alloc.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.5.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><tr><th>Safe Haskell</th><td>Trustworthy</td></tr></table><p class="caption">Foreign.Marshal.Alloc</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Memory allocation
</a><ul><li><a href="#g:2">Local allocation
</a></li><li><a href="#g:3">Dynamic allocation
</a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>The module <a href="Foreign-Marshal-Alloc.html">Foreign.Marshal.Alloc</a> provides operations to allocate and
deallocate blocks of raw memory (i.e., unstructured chunks of memory
outside of the area maintained by the Haskell storage manager). These
memory blocks are commonly used to pass compound data structures to
foreign functions or to provide space in which compound result values
are obtained from foreign functions.
</p><p>If any of the allocation functions fails, an exception is thrown.
In some cases, memory exhaustion may mean the process is terminated.
If <code><a href="Foreign-Marshal-Alloc.html#v:free">free</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code> is applied to a memory area
that has been allocated with <code><a href="Foreign-Marshal-Alloc.html#v:alloca">alloca</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:allocaBytes">allocaBytes</a></code>, the
behaviour is undefined. Any further access to memory areas allocated with
<code><a href="Foreign-Marshal-Alloc.html#v:alloca">alloca</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:allocaBytes">allocaBytes</a></code>, after the computation that was passed to
the allocation function has terminated, leads to undefined behaviour. Any
further access to the memory area referenced by a pointer passed to
<code><a href="Foreign-Marshal-Alloc.html#v:realloc">realloc</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code>, or <code><a href="Foreign-Marshal-Alloc.html#v:free">free</a></code> entails undefined
behaviour.
</p><p>All storage allocated by functions that allocate based on a <em>size in bytes</em>
must be sufficiently aligned for any of the basic foreign types
that fits into the newly allocated storage. All storage allocated by
functions that allocate based on a specific type must be sufficiently
aligned for that type. Array allocation routines need to obey the same
alignment constraints for each array element.
</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:alloca">alloca</a> :: <a href="Foreign-Storable.html#t:Storable">Storable</a> a => (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> b) -> <a href="System-IO.html#t:IO">IO</a> b</li><li class="src short"><a href="#v:allocaBytes">allocaBytes</a> :: <a href="Data-Int.html#t:Int">Int</a> -> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> b) -> <a href="System-IO.html#t:IO">IO</a> b</li><li class="src short"><a href="#v:allocaBytesAligned">allocaBytesAligned</a> :: <a href="Data-Int.html#t:Int">Int</a> -> <a href="Data-Int.html#t:Int">Int</a> -> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> b) -> <a href="System-IO.html#t:IO">IO</a> b</li><li class="src short"><a href="#v:malloc">malloc</a> :: <a href="Foreign-Storable.html#t:Storable">Storable</a> a => <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a)</li><li class="src short"><a href="#v:mallocBytes">mallocBytes</a> :: <a href="Data-Int.html#t:Int">Int</a> -> <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a)</li><li class="src short"><a href="#v:realloc">realloc</a> :: <a href="Foreign-Storable.html#t:Storable">Storable</a> b => <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> b)</li><li class="src short"><a href="#v:reallocBytes">reallocBytes</a> :: <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="Data-Int.html#t:Int">Int</a> -> <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a)</li><li class="src short"><a href="#v:free">free</a> :: <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li><li class="src short"><a href="#v:finalizerFree">finalizerFree</a> :: <a href="Foreign-ForeignPtr-Safe.html#t:FinalizerPtr">FinalizerPtr</a> a</li></ul></div><div id="interface"><h1 id="g:1">Memory allocation
</h1><h2 id="g:2">Local allocation
</h2><div class="top"><p class="src"><a name="v:alloca" class="def">alloca</a> :: <a href="Foreign-Storable.html#t:Storable">Storable</a> a => (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> b) -> <a href="System-IO.html#t:IO">IO</a> b</p><div class="doc"><p><code><code><a href="Foreign-Marshal-Alloc.html#v:alloca">alloca</a></code> f</code> executes the computation <code>f</code>, passing as argument
a pointer to a temporarily allocated block of memory sufficient to
hold values of type <code>a</code>.
</p><p>The memory is freed when <code>f</code> terminates (either normally or via an
exception), so the pointer passed to <code>f</code> must <em>not</em> be used after this.
</p></div></div><div class="top"><p class="src"><a name="v:allocaBytes" class="def">allocaBytes</a> :: <a href="Data-Int.html#t:Int">Int</a> -> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> b) -> <a href="System-IO.html#t:IO">IO</a> b</p><div class="doc"><p><code><code><a href="Foreign-Marshal-Alloc.html#v:allocaBytes">allocaBytes</a></code> n f</code> executes the computation <code>f</code>, passing as argument
a pointer to a temporarily allocated block of memory of <code>n</code> bytes.
The block of memory is sufficiently aligned for any of the basic
foreign types that fits into a memory block of the allocated size.
</p><p>The memory is freed when <code>f</code> terminates (either normally or via an
exception), so the pointer passed to <code>f</code> must <em>not</em> be used after this.
</p></div></div><div class="top"><p class="src"><a name="v:allocaBytesAligned" class="def">allocaBytesAligned</a> :: <a href="Data-Int.html#t:Int">Int</a> -> <a href="Data-Int.html#t:Int">Int</a> -> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> b) -> <a href="System-IO.html#t:IO">IO</a> b</p></div><h2 id="g:3">Dynamic allocation
</h2><div class="top"><p class="src"><a name="v:malloc" class="def">malloc</a> :: <a href="Foreign-Storable.html#t:Storable">Storable</a> a => <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a)</p><div class="doc"><p>Allocate a block of memory that is sufficient to hold values of type
<code>a</code>. The size of the area allocated is determined by the <code><a href="Foreign-Storable.html#v:sizeOf">sizeOf</a></code>
method from the instance of <code><a href="Foreign-Storable.html#t:Storable">Storable</a></code> for the appropriate type.
</p><p>The memory may be deallocated using <code><a href="Foreign-Marshal-Alloc.html#v:free">free</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:finalizerFree">finalizerFree</a></code> when
no longer required.
</p></div></div><div class="top"><p class="src"><a name="v:mallocBytes" class="def">mallocBytes</a> :: <a href="Data-Int.html#t:Int">Int</a> -> <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a)</p><div class="doc"><p>Allocate a block of memory of the given number of bytes.
The block of memory is sufficiently aligned for any of the basic
foreign types that fits into a memory block of the allocated size.
</p><p>The memory may be deallocated using <code><a href="Foreign-Marshal-Alloc.html#v:free">free</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:finalizerFree">finalizerFree</a></code> when
no longer required.
</p></div></div><div class="top"><p class="src"><a name="v:realloc" class="def">realloc</a> :: <a href="Foreign-Storable.html#t:Storable">Storable</a> b => <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> b)</p><div class="doc"><p>Resize a memory area that was allocated with <code><a href="Foreign-Marshal-Alloc.html#v:malloc">malloc</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:mallocBytes">mallocBytes</a></code>
to the size needed to store values of type <code>b</code>. The returned pointer
may refer to an entirely different memory area, but will be suitably
aligned to hold values of type <code>b</code>. The contents of the referenced
memory area will be the same as of the original pointer up to the
minimum of the original size and the size of values of type <code>b</code>.
</p><p>If the argument to <code><a href="Foreign-Marshal-Alloc.html#v:realloc">realloc</a></code> is <code><a href="Foreign-Ptr.html#v:nullPtr">nullPtr</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:realloc">realloc</a></code> behaves like
<code><a href="Foreign-Marshal-Alloc.html#v:malloc">malloc</a></code>.
</p></div></div><div class="top"><p class="src"><a name="v:reallocBytes" class="def">reallocBytes</a> :: <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="Data-Int.html#t:Int">Int</a> -> <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a)</p><div class="doc"><p>Resize a memory area that was allocated with <code><a href="Foreign-Marshal-Alloc.html#v:malloc">malloc</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:mallocBytes">mallocBytes</a></code>
to the given size. The returned pointer may refer to an entirely
different memory area, but will be sufficiently aligned for any of the
basic foreign types that fits into a memory block of the given size.
The contents of the referenced memory area will be the same as of
the original pointer up to the minimum of the original size and the
given size.
</p><p>If the pointer argument to <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code> is <code><a href="Foreign-Ptr.html#v:nullPtr">nullPtr</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code>
behaves like <code><a href="Foreign-Marshal-Alloc.html#v:malloc">malloc</a></code>. If the requested size is 0, <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code>
behaves like <code><a href="Foreign-Marshal-Alloc.html#v:free">free</a></code>.
</p></div></div><div class="top"><p class="src"><a name="v:free" class="def">free</a> :: <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> a -> <a href="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>Free a block of memory that was allocated with <code><a href="Foreign-Marshal-Alloc.html#v:malloc">malloc</a></code>,
<code><a href="Foreign-Marshal-Alloc.html#v:mallocBytes">mallocBytes</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:realloc">realloc</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code>, <code><a href="Foreign-Marshal-Utils.html#v:new">new</a></code>
or any of the <code>new</code><em>X</em> functions in <a href="Foreign-Marshal-Array.html">Foreign.Marshal.Array</a> or
<a href="Foreign-C-String.html">Foreign.C.String</a>.
</p></div></div><div class="top"><p class="src"><a name="v:finalizerFree" class="def">finalizerFree</a> :: <a href="Foreign-ForeignPtr-Safe.html#t:FinalizerPtr">FinalizerPtr</a> a</p><div class="doc"><p>A pointer to a foreign function equivalent to <code><a href="Foreign-Marshal-Alloc.html#v:free">free</a></code>, which may be
used as a finalizer (cf <code><a href="Foreign-ForeignPtr.html#t:ForeignPtr">ForeignPtr</a></code>) for storage
allocated with <code><a href="Foreign-Marshal-Alloc.html#v:malloc">malloc</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:mallocBytes">mallocBytes</a></code>, <code><a href="Foreign-Marshal-Alloc.html#v:realloc">realloc</a></code> or <code><a href="Foreign-Marshal-Alloc.html#v:reallocBytes">reallocBytes</a></code>.
</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>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
6e204a966e8c42d976f99a1700ce5f20
>
files
>
2275
