<refentry id="glib-Memory-Allocation">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Memory-Allocation.top_of_page">Memory Allocation</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Memory Allocation</refname>
<refpurpose>general memory-handling</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Memory-Allocation.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

#define             <link linkend="g-new">g_new</link>                               (struct_type, n_structs)
#define             <link linkend="g-new0">g_new0</link>                              (struct_type, n_structs)
#define             <link linkend="g-renew">g_renew</link>                             (struct_type, mem, n_structs)
#define             <link linkend="g-try-new">g_try_new</link>                           (struct_type, n_structs)
#define             <link linkend="g-try-new0">g_try_new0</link>                          (struct_type, n_structs)
#define             <link linkend="g-try-renew">g_try_renew</link>                         (struct_type, mem, n_structs)

<link linkend="gpointer">gpointer</link>            <link linkend="g-malloc">g_malloc</link>                            (<link linkend="gsize">gsize</link> n_bytes);
<link linkend="gpointer">gpointer</link>            <link linkend="g-malloc0">g_malloc0</link>                           (<link linkend="gsize">gsize</link> n_bytes);
<link linkend="gpointer">gpointer</link>            <link linkend="g-realloc">g_realloc</link>                           (<link linkend="gpointer">gpointer</link> mem,
                                                         <link linkend="gsize">gsize</link> n_bytes);
<link linkend="gpointer">gpointer</link>            <link linkend="g-try-malloc">g_try_malloc</link>                        (<link linkend="gsize">gsize</link> n_bytes);
<link linkend="gpointer">gpointer</link>            <link linkend="g-try-malloc0">g_try_malloc0</link>                       (<link linkend="gsize">gsize</link> n_bytes);
<link linkend="gpointer">gpointer</link>            <link linkend="g-try-realloc">g_try_realloc</link>                       (<link linkend="gpointer">gpointer</link> mem,
                                                         <link linkend="gsize">gsize</link> n_bytes);

<link linkend="void">void</link>                <link linkend="g-free">g_free</link>                              (<link linkend="gpointer">gpointer</link> mem);
extern              gboolean <link linkend="g-mem-gc-friendly">g_mem_gc_friendly</link>;

#define             <link linkend="g-alloca">g_alloca</link>                            (size)
#define             <link linkend="g-newa">g_newa</link>                              (struct_type, n_structs)

#define             <link linkend="g-memmove">g_memmove</link>                           (dest,src,len)
<link linkend="gpointer">gpointer</link>            <link linkend="g-memdup">g_memdup</link>                            (<link linkend="gconstpointer">gconstpointer</link> mem,
                                                         <link linkend="guint">guint</link> byte_size);

                    <link linkend="GMemVTable">GMemVTable</link>;
<link linkend="void">void</link>                <link linkend="g-mem-set-vtable">g_mem_set_vtable</link>                    (<link linkend="GMemVTable">GMemVTable</link> *vtable);
<link linkend="gboolean">gboolean</link>            <link linkend="g-mem-is-system-malloc">g_mem_is_system_malloc</link>              (void);

extern              GMemVTable	*<link linkend="glib-mem-profiler-table">glib_mem_profiler_table</link>;
<link linkend="void">void</link>                <link linkend="g-mem-profile">g_mem_profile</link>                       (void);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Memory-Allocation.description" role="desc">
<title role="desc.title">Description</title>
<para>
These functions provide support for allocating and freeing memory.
</para>
<note>
<para>
If any call to allocate memory fails, the application is terminated.
This also means that there is no need to check if the call succeeded.
</para>
</note>
<note>
<para>
It's important to match <link linkend="g-malloc"><function>g_malloc()</function></link> with <link linkend="g-free"><function>g_free()</function></link>, plain <link linkend="malloc"><function>malloc()</function></link> with <link linkend="free"><function>free()</function></link>,
and (if you're using C++) new with delete and new[] with delete[]. Otherwise
bad things can happen, since these allocators may use different memory
pools (and new/delete call constructors and destructors). See also
<link linkend="g-mem-set-vtable"><function>g_mem_set_vtable()</function></link>.
</para>
</note>
</refsect1>

<refsect1 id="glib-Memory-Allocation.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-new" role="macro">
<title>g_new()</title>
<indexterm zone="g-new"><primary sortas="new">g_new</primary></indexterm><programlisting>#define             g_new(struct_type, n_structs)</programlisting>
<para>
Allocates <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>.
The returned pointer is cast to a pointer to the given type.
If <parameter>n_structs</parameter> is 0 it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para>
<para>
Since the returned pointer is already casted to the right type,
it is normally unnecessary to cast it explicitly, and doing
so might hide memory allocation errors.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>the type of the elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>the number of elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the allocated memory, cast to a pointer to <parameter>struct_type</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-new0" role="macro">
<title>g_new0()</title>
<indexterm zone="g-new0"><primary sortas="new0">g_new0</primary></indexterm><programlisting>#define             g_new0(struct_type, n_structs)</programlisting>
<para>
Allocates <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>, initialized to 0's.
The returned pointer is cast to a pointer to the given type.
If <parameter>n_structs</parameter> is 0 it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para>
<para>
Since the returned pointer is already casted to the right type,
it is normally unnecessary to cast it explicitly, and doing
so might hide memory allocation errors.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>the type of the elements to allocate.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>the number of elements to allocate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the allocated memory, cast to a pointer to <parameter>struct_type</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-renew" role="macro">
<title>g_renew()</title>
<indexterm zone="g-renew"><primary sortas="renew">g_renew</primary></indexterm><programlisting>#define             g_renew(struct_type, mem, n_structs)</programlisting>
<para>
Reallocates the memory pointed to by <parameter>mem</parameter>, so that it now has space for
<parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>. It returns the new address of
the memory, which may have been moved.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>the type of the elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mem</parameter>&#160;:</term>
<listitem><simpara>the currently allocated memory
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>the number of elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the new allocated memory, cast to a pointer to <parameter>struct_type</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-try-new" role="macro" condition="since:2.8">
<title>g_try_new()</title>
<indexterm zone="g-try-new" role="2.8"><primary sortas="try_new">g_try_new</primary></indexterm><programlisting>#define             g_try_new(struct_type, n_structs)</programlisting>
<para>
Attempts to allocate <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>, and returns
<link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure. Contrast with <link linkend="g-new"><function>g_new()</function></link>, which aborts the program on failure.
The returned pointer is cast to a pointer to the given type.
If <parameter>n_structs</parameter> is 0 it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>the type of the elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>the number of elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the allocated memory, cast to a pointer to <parameter>struct_type</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-try-new0" role="macro" condition="since:2.8">
<title>g_try_new0()</title>
<indexterm zone="g-try-new0" role="2.8"><primary sortas="try_new0">g_try_new0</primary></indexterm><programlisting>#define             g_try_new0(struct_type, n_structs)</programlisting>
<para>
Attempts to allocate <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>, initialized
to 0's, and returns <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure. Contrast with <link linkend="g-new0"><function>g_new0()</function></link>, which aborts
the program on failure.
The returned pointer is cast to a pointer to the given type.
The function returns <link linkend="NULL--CAPS"><literal>NULL</literal></link> when <parameter>n_structs</parameter> is 0.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>the type of the elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>the number of elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the allocated memory, cast to a pointer to <parameter>struct_type</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-try-renew" role="macro" condition="since:2.8">
<title>g_try_renew()</title>
<indexterm zone="g-try-renew" role="2.8"><primary sortas="try_renew">g_try_renew</primary></indexterm><programlisting>#define             g_try_renew(struct_type, mem, n_structs)</programlisting>
<para>
Attempts to reallocate the memory pointed to by <parameter>mem</parameter>, so that it now has
space for <parameter>n_structs</parameter> elements of type <parameter>struct_type</parameter>, and returns <link linkend="NULL--CAPS"><literal>NULL</literal></link> on
failure. Contrast with <link linkend="g-renew"><function>g_renew()</function></link>, which aborts the program on failure.
It returns the new address of the memory, which may have been moved.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>the type of the elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mem</parameter>&#160;:</term>
<listitem><simpara>the currently allocated memory
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>the number of elements to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the new allocated memory, cast to a pointer to <parameter>struct_type</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-malloc" role="function">
<title>g_malloc ()</title>
<indexterm zone="g-malloc"><primary sortas="malloc">g_malloc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_malloc                            (<link linkend="gsize">gsize</link> n_bytes);</programlisting>
<para>
Allocates <parameter>n_bytes</parameter> bytes of memory.
If <parameter>n_bytes</parameter> is 0 it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
<listitem><simpara>the number of bytes to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the allocated memory
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-malloc0" role="function">
<title>g_malloc0 ()</title>
<indexterm zone="g-malloc0"><primary sortas="malloc0">g_malloc0</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_malloc0                           (<link linkend="gsize">gsize</link> n_bytes);</programlisting>
<para>
Allocates <parameter>n_bytes</parameter> bytes of memory, initialized to 0's.
If <parameter>n_bytes</parameter> is 0 it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
<listitem><simpara>the number of bytes to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the allocated memory
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-realloc" role="function">
<title>g_realloc ()</title>
<indexterm zone="g-realloc"><primary sortas="realloc">g_realloc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_realloc                           (<link linkend="gpointer">gpointer</link> mem,
                                                         <link linkend="gsize">gsize</link> n_bytes);</programlisting>
<para>
Reallocates the memory pointed to by <parameter>mem</parameter>, so that it now has space for
<parameter>n_bytes</parameter> bytes of memory. It returns the new address of the memory, which may
have been moved. <parameter>mem</parameter> may be <link linkend="NULL--CAPS"><literal>NULL</literal></link>, in which case it's considered to
have zero-length. <parameter>n_bytes</parameter> may be 0, in which case <link linkend="NULL--CAPS"><literal>NULL</literal></link> will be returned
and <parameter>mem</parameter> will be freed unless it is <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>mem</parameter>&#160;:</term>
<listitem><simpara>the memory to reallocate
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
<listitem><simpara>new size of the memory in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new address of the allocated memory
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-try-malloc" role="function">
<title>g_try_malloc ()</title>
<indexterm zone="g-try-malloc"><primary sortas="try_malloc">g_try_malloc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_try_malloc                        (<link linkend="gsize">gsize</link> n_bytes);</programlisting>
<para>
Attempts to allocate <parameter>n_bytes</parameter>, and returns <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure.
Contrast with <link linkend="g-malloc"><function>g_malloc()</function></link>, which aborts the program on failure.
</para><variablelist role="params">
<varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
<listitem><simpara>number of bytes to allocate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the allocated memory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-try-malloc0" role="function" condition="since:2.8">
<title>g_try_malloc0 ()</title>
<indexterm zone="g-try-malloc0" role="2.8"><primary sortas="try_malloc0">g_try_malloc0</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_try_malloc0                       (<link linkend="gsize">gsize</link> n_bytes);</programlisting>
<para>
Attempts to allocate <parameter>n_bytes</parameter>, initialized to 0's, and returns <link linkend="NULL--CAPS"><literal>NULL</literal></link> on
failure. Contrast with <link linkend="g-malloc0"><function>g_malloc0()</function></link>, which aborts the program on failure.
</para><variablelist role="params">
<varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
<listitem><simpara>number of bytes to allocate
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the allocated memory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.8</para></refsect2>
<refsect2 id="g-try-realloc" role="function">
<title>g_try_realloc ()</title>
<indexterm zone="g-try-realloc"><primary sortas="try_realloc">g_try_realloc</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_try_realloc                       (<link linkend="gpointer">gpointer</link> mem,
                                                         <link linkend="gsize">gsize</link> n_bytes);</programlisting>
<para>
Attempts to realloc <parameter>mem</parameter> to a new size, <parameter>n_bytes</parameter>, and returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>
on failure. Contrast with <link linkend="g-realloc"><function>g_realloc()</function></link>, which aborts the program
on failure. If <parameter>mem</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, behaves the same as <link linkend="g-try-malloc"><function>g_try_malloc()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>mem</parameter>&#160;:</term>
<listitem><simpara>previously-allocated memory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
<listitem><simpara>number of bytes to allocate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the allocated memory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-free" role="function">
<title>g_free ()</title>
<indexterm zone="g-free"><primary sortas="free">g_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_free                              (<link linkend="gpointer">gpointer</link> mem);</programlisting>
<para>
Frees the memory pointed to by <parameter>mem</parameter>.
If <parameter>mem</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> it simply returns.
</para><variablelist role="params">
<varlistentry><term><parameter>mem</parameter>&#160;:</term>
<listitem><simpara>the memory to free
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mem-gc-friendly" role="variable">
<title>g_mem_gc_friendly</title>
<indexterm zone="g-mem-gc-friendly"><primary sortas="mem_gc_friendly">g_mem_gc_friendly</primary></indexterm><programlisting>extern gboolean g_mem_gc_friendly;
</programlisting>
<para>
This variable is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <envar>G_DEBUG</envar> environment variable
includes the key <link linkend="G_DEBUG">gc-friendly</link>.
</para></refsect2>
<refsect2 id="g-alloca" role="macro">
<title>g_alloca()</title>
<indexterm zone="g-alloca"><primary sortas="alloca">g_alloca</primary></indexterm><programlisting>#define             g_alloca(size)</programlisting>
<para>
Allocates <parameter>size</parameter> bytes on the stack; these bytes will be freed when the current
stack frame is cleaned up. This macro essentially just wraps the <link linkend="alloca"><function>alloca()</function></link>
function present on most UNIX variants.
Thus it provides the same advantages and pitfalls as <link linkend="alloca"><function>alloca()</function></link>:
<variablelist>
  <varlistentry><term></term><listitem><para>
    + <link linkend="alloca"><function>alloca()</function></link> is very fast, as on most systems it's implemented by just adjusting
    the stack pointer register.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    + It doesn't cause any memory fragmentation, within its scope, separate <link linkend="alloca"><function>alloca()</function></link>
    blocks just build up and are released together at function end.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Allocation sizes have to fit into the current stack frame. For instance in a
      threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
      so be sparse with <link linkend="alloca"><function>alloca()</function></link> uses.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Allocation failure due to insufficient stack space is not indicated with a <link linkend="NULL--CAPS"><literal>NULL</literal></link>
      return like e.g. with <link linkend="malloc"><function>malloc()</function></link>. Instead, most systems probably handle it the same
      way as out of stack space situations from infinite function recursion, i.e.
      with a segmentation fault.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Special care has to be taken when mixing <link linkend="alloca"><function>alloca()</function></link> with GNU C variable sized arrays.
      Stack space allocated with <link linkend="alloca"><function>alloca()</function></link> in the same scope as a variable sized array
      will be freed together with the variable sized array upon exit of that scope, and
      not upon exit of the enclosing function scope.
  </para></listitem></varlistentry>
</variablelist>
</para><variablelist role="params">
<varlistentry><term><parameter>size</parameter>&#160;:</term>
<listitem><simpara>   number of bytes to allocate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>space for <parameter>size</parameter> bytes, allocated on the stack
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-newa" role="macro">
<title>g_newa()</title>
<indexterm zone="g-newa"><primary sortas="newa">g_newa</primary></indexterm><programlisting>#define             g_newa(struct_type, n_structs)</programlisting>
<para>
Wraps <link linkend="g-alloca"><function>g_alloca()</function></link> in a more typesafe manner.
</para><variablelist role="params">
<varlistentry><term><parameter>struct_type</parameter>&#160;:</term>
<listitem><simpara>Type of memory chunks to be allocated
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_structs</parameter>&#160;:</term>
<listitem><simpara>  Number of chunks to be allocated
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>    Pointer to stack space for <parameter>n_structs</parameter> chunks of type <parameter>struct_type</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-memmove" role="macro">
<title>g_memmove()</title>
<indexterm zone="g-memmove"><primary sortas="memmove">g_memmove</primary></indexterm><programlisting>#define             g_memmove(dest,src,len)</programlisting>
<para>
Copies a block of memory <parameter>len</parameter> bytes long, from <parameter>src</parameter> to <parameter>dest</parameter>.
The source and destination areas may overlap.
</para>
<para>
In order to use this function, you must include 
<filename>string.h</filename> yourself, because this macro will 
typically simply resolve to <link linkend="memmove"><function>memmove()</function></link> and GLib does not include 
<filename>string.h</filename> for you.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter>&#160;:</term>
<listitem><simpara> the destination address to copy the bytes to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>src</parameter>&#160;:</term>
<listitem><simpara> the source address to copy the bytes from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara> the number of bytes to copy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-memdup" role="function">
<title>g_memdup ()</title>
<indexterm zone="g-memdup"><primary sortas="memdup">g_memdup</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_memdup                            (<link linkend="gconstpointer">gconstpointer</link> mem,
                                                         <link linkend="guint">guint</link> byte_size);</programlisting>
<para>
Allocates <parameter>byte_size</parameter> bytes of memory, and copies <parameter>byte_size</parameter> bytes into it
from <parameter>mem</parameter>. If <parameter>mem</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link> it returns <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>mem</parameter>&#160;:</term>
<listitem><simpara>the memory to copy.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>byte_size</parameter>&#160;:</term>
<listitem><simpara>the number of bytes to copy.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a pointer to the newly-allocated copy of the memory, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>mem</parameter>
is <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GMemVTable" role="struct">
<title>GMemVTable</title>
<indexterm zone="GMemVTable"><primary sortas="MemVTable">GMemVTable</primary></indexterm><programlisting>typedef struct {
  gpointer (*malloc)      (gsize    n_bytes);
  gpointer (*realloc)     (gpointer mem,
			   gsize    n_bytes);
  void     (*free)        (gpointer mem);
  /* optional; set to NULL if not used ! */
  gpointer (*calloc)      (gsize    n_blocks,
			   gsize    n_block_bytes);
  gpointer (*try_malloc)  (gsize    n_bytes);
  gpointer (*try_realloc) (gpointer mem,
			   gsize    n_bytes);
} GMemVTable;
</programlisting>
<para>
A set of functions used to perform memory allocation. The same <link linkend="GMemVTable"><type>GMemVTable</type></link> must
be used for all allocations in the same program; a call to <link linkend="g-mem-set-vtable"><function>g_mem_set_vtable()</function></link>,
if it exists, should be prior to any use of GLib.
</para><variablelist role="struct">
<varlistentry>
<term><structfield>malloc</structfield>&#160;()</term>
<listitem><simpara>function to use for allocating memory.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>realloc</structfield>&#160;()</term>
<listitem><simpara>function to use for reallocating memory.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>free</structfield>&#160;()</term>
<listitem><simpara>function to use to free memory.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>calloc</structfield>&#160;()</term>
<listitem><simpara>function to use for allocating zero-filled memory.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>try_malloc</structfield>&#160;()</term>
<listitem><simpara>function to use for allocating memory without a default error handler.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>try_realloc</structfield>&#160;()</term>
<listitem><simpara>function to use for reallocating memory without a default error handler.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mem-set-vtable" role="function">
<title>g_mem_set_vtable ()</title>
<indexterm zone="g-mem-set-vtable"><primary sortas="mem_set_vtable">g_mem_set_vtable</primary></indexterm><programlisting><link linkend="void">void</link>                g_mem_set_vtable                    (<link linkend="GMemVTable">GMemVTable</link> *vtable);</programlisting>
<para>
Sets the <link linkend="GMemVTable"><type>GMemVTable</type></link> to use for memory allocation. You can use this to provide
custom memory allocation routines. <emphasis>This function must be called
before using any other GLib functions.</emphasis> The <parameter>vtable</parameter> only needs to
provide <link linkend="malloc"><function>malloc()</function></link>, <link linkend="realloc"><function>realloc()</function></link>, and <link linkend="free"><function>free()</function></link> functions; GLib can provide default
implementations of the others. The <link linkend="malloc"><function>malloc()</function></link> and <link linkend="realloc"><function>realloc()</function></link> implementations
should return <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure, GLib will handle error-checking for you.
<parameter>vtable</parameter> is copied, so need not persist after this function has been called.
</para><variablelist role="params">
<varlistentry><term><parameter>vtable</parameter>&#160;:</term>
<listitem><simpara>table of memory allocation routines.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mem-is-system-malloc" role="function">
<title>g_mem_is_system_malloc ()</title>
<indexterm zone="g-mem-is-system-malloc"><primary sortas="mem_is_system_malloc">g_mem_is_system_malloc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_mem_is_system_malloc              (void);</programlisting>
<para>
Checks whether the allocator used by <link linkend="g-malloc"><function>g_malloc()</function></link> is the system's
malloc implementation. If it returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> memory allocated with
<link linkend="malloc"><function>malloc()</function></link> can be used interchangeable with memory allocated using <link linkend="g-malloc"><function>g_malloc()</function></link>. 
This function is useful for avoiding an extra copy of allocated memory returned
by a non-GLib-based API.
</para>
<para>
A different allocator can be set using <link linkend="g-mem-set-vtable"><function>g_mem_set_vtable()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, <link linkend="malloc"><function>malloc()</function></link> and <link linkend="g-malloc"><function>g_malloc()</function></link> can be mixed.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="glib-mem-profiler-table" role="variable">
<title>glib_mem_profiler_table</title>
<indexterm zone="glib-mem-profiler-table"><primary sortas="lib_mem_profiler_table">glib_mem_profiler_table</primary></indexterm><programlisting>extern GMemVTable	*glib_mem_profiler_table;
</programlisting>
<para>
A <link linkend="GMemVTable"><type>GMemVTable</type></link> containing profiling variants of the memory
allocation functions. Use them together with <link linkend="g-mem-profile"><function>g_mem_profile()</function></link>
in order to get information about the memory allocation pattern
of your program.
</para></refsect2>
<refsect2 id="g-mem-profile" role="function">
<title>g_mem_profile ()</title>
<indexterm zone="g-mem-profile"><primary sortas="mem_profile">g_mem_profile</primary></indexterm><programlisting><link linkend="void">void</link>                g_mem_profile                       (void);</programlisting>
<para>
Outputs a summary of memory usage.
</para>
<para>
It outputs the frequency of allocations of different sizes,
the total number of bytes which have been allocated,
the total number of bytes which have been freed,
and the difference between the previous two values, i.e. the number of bytes
still in use.
</para>
<para>
Note that this function will not output anything unless you have
previously installed the <link linkend="glib-mem-profiler-table"><type>glib_mem_profiler_table</type></link> with <link linkend="g-mem-set-vtable"><function>g_mem_set_vtable()</function></link>.
</para></refsect2>

</refsect1>




</refentry>
