path: root/docs/reference/glib/tmpl/memory.sgml

<!-- ##### SECTION Title ##### -->
Memory Allocation

<!-- ##### SECTION Short_Description ##### -->
general memory-handling.

<!-- ##### SECTION Long_Description ##### -->
<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>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### MACRO g_new ##### -->
<para>
Allocates @n_structs elements of type @struct_type.
The returned pointer is cast to a pointer to the given type.
If @n_structs is 0 it returns %NULL.
</para>

@struct_type: the type of the elements to allocate.
@n_structs: the number of elements to allocate.
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.


<!-- ##### MACRO g_new0 ##### -->
<para>
Allocates @n_structs elements of type @struct_type, initialized to 0's.
The returned pointer is cast to a pointer to the given type.
If @n_structs is 0 it returns %NULL.
</para>

@struct_type: the type of the elements to allocate.
@n_structs: the number of elements to allocate.
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.


<!-- ##### MACRO g_renew ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
@n_structs elements of type @struct_type. It returns the new address of 
the memory, which may have been moved.
</para>

@struct_type: the type of the elements to allocate.
@mem: the currently allocated memory.
@n_structs: the number of elements to allocate.
@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.


<!-- ##### MACRO g_try_new ##### -->
<para>
Attempts to allocate @n_structs elements of type @struct_type, and returns 
%NULL on failure. Contrast with g_new(), which aborts the program on failure.
The returned pointer is cast to a pointer to the given type. 
If @n_structs is 0 it returns %NULL.
</para>

@struct_type: the type of the elements to allocate.
@n_structs: the number of elements to allocate.
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
@Since: 2.8


<!-- ##### MACRO g_try_new0 ##### -->
<para>
Attempts to allocate @n_structs elements of type @struct_type, initialized 
to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts 
the program on failure.
The returned pointer is cast to a pointer to the given type.
If @n_counts is 0 it returns %NULL.
</para>

@struct_type: the type of the elements to allocate.
@n_structs: the number of elements to allocate.
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
@Since: 2.8


<!-- ##### MACRO g_try_renew ##### -->
<para>
Attempts to reallocate the memory pointed to by @mem, so that it now has 
space for @n_structs elements of type @struct_type, and returns %NULL on 
failure. Contrast with g_renew(), which aborts the program on failure.
It returns the new address of the memory, which may have been moved.
</para>

@struct_type: the type of the elements to allocate.
@mem: the currently allocated memory.
@n_structs: the number of elements to allocate.
@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
@Since: 2.8


<!-- ##### FUNCTION g_malloc ##### -->
<para>
Allocates @n_bytes bytes of memory.
If @n_bytes is 0 it returns %NULL.
</para>

@n_bytes: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.


<!-- ##### FUNCTION g_malloc0 ##### -->
<para>
Allocates @n_bytes bytes of memory, initialized to 0's.
If @n_bytes is 0 it returns %NULL.
</para>

@n_bytes: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.


<!-- ##### FUNCTION g_realloc ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
@n_bytes bytes of memory. It returns the new address of the memory, which may
have been moved. @mem may be %NULL, in which case it's considered to 
have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
</para>

@mem: the memory to reallocate.
@n_bytes: new size of the memory in bytes.
@Returns: the new address of the allocated memory.


<!-- ##### FUNCTION g_try_malloc ##### -->
<para>
Attempts to allocate @n_bytes, and returns %NULL on failure. 
Contrast with g_malloc(), which aborts the program on failure.
</para>

@n_bytes: number of bytes to allocate.
@Returns: the allocated memory, or %NULL.


<!-- ##### FUNCTION g_try_malloc0 ##### -->
<para>
Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on 
failure. Contrast with g_malloc0(), which aborts the program on failure.
</para>

@n_bytes: number of bytes to allocate.
@Returns: the allocated memory, or %NULL.
@Since: 2.8


<!-- ##### FUNCTION g_try_realloc ##### -->
<para>
Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
on failure. Contrast with g_realloc(), which aborts the program
on failure. If @mem is %NULL, behaves the same as g_try_malloc().
</para>

@mem: previously-allocated memory, or %NULL.
@n_bytes: number of bytes to allocate.
@Returns: the allocated memory, or %NULL.


<!-- ##### FUNCTION g_free ##### -->
<para>
Frees the memory pointed to by @mem.
If @mem is %NULL it simply returns.
</para>

@mem: the memory to free.


<!-- ##### MACRO g_alloca ##### -->
<para>
Allocates @size bytes on the stack; these bytes will be freed when the current
stack frame is cleaned up. This macro essentially just wraps the 
<function>alloca()</function> function present on most UNIX variants. 
Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
<variablelist>
  <varlistentry><term></term><listitem><para>
    + <function>alloca()</function> 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 <function>alloca()</function>
    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 <function>alloca()</function> uses.
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
    - Allocation failure due to insufficient stack space is not indicated with a %NULL
      return like e.g. with <function>malloc()</function>. 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 <function>alloca()</function> with GNU C variable sized arrays.
      Stack space allocated with <function>alloca()</function> 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>

@size:    number of bytes to allocate.
@Returns: space for @size bytes, allocated on the stack


<!-- ##### MACRO g_newa ##### -->
<para>
Wraps g_alloca() in a more typesafe manner.
</para>

@struct_type: Type of memory chunks to be allocated
@n_structs:   Number of chunks to be allocated
@Returns:     Pointer to stack space for @n_structs chunks of type @struct_type


<!-- ##### MACRO g_memmove ##### -->
<para>

</para>

@dest: 
@src: 
@len: 


<!-- ##### FUNCTION g_memdup ##### -->
<para>
Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
from @mem. If @mem is %NULL it returns %NULL.
</para>

@mem: the memory to copy.
@byte_size: the number of bytes to copy.
@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
is %NULL.


<!-- ##### STRUCT GMemVTable ##### -->
<para>
A set of functions used to perform memory allocation. The same #GMemVTable must
be used for all allocations in the same program; a call to g_mem_set_vtable(),
if it exists, should be prior to any use of GLib.
</para>

@malloc: function to use for allocating memory.
@realloc: function to use for reallocating memory.
@free: function to use to free memory.
@calloc: function to use for allocating zero-filled memory.
@try_malloc: function to use for allocating memory without a default error handler.
@try_realloc: function to use for reallocating memory without a default error handler.

<!-- ##### FUNCTION g_mem_set_vtable ##### -->
<para>
Sets the #GMemVTable 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 @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
functions; GLib can provide default implementations of the others.  The <function>malloc()</function>
and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
error-checking for you. @vtable is copied, so need not persist after this 
function has been called.
</para>

@vtable: table of memory allocation routines.


<!-- ##### FUNCTION g_mem_is_system_malloc ##### -->
<para>

</para>

@Returns: 


<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
<para>
A #GMemVTable containing profiling variants of the memory
allocation functions. Use them together with g_mem_profile()
in order to get information about the memory allocation pattern
of your program.
</para>


<!-- ##### FUNCTION g_mem_profile ##### -->
<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 #glib_mem_profiler_table with g_mem_set_vtable().
</para>