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

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

@struct_type: 
@n_structs: 
@Returns: a pointer to the allocated memory, cast to a pointer to @type.
<!-- # Unused Parameters # -->
@type: the type of the elements to allocate.
@count: the number of elements to allocate.


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

@struct_type: 
@n_structs: 
@Returns: a pointer to the allocated memory, cast to a pointer to @type.
<!-- # Unused Parameters # -->
@type: the type of the elements to allocate.
@count: the number of elements to allocate.


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

@struct_type: 
@mem: the currently allocated memory.
@n_structs: 
@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
<!-- # Unused Parameters # -->
@type: the type of the elements to allocate.
@count: the number of elements to allocate.


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

@n_bytes: 
@Returns: a pointer to the allocated memory.
<!-- # Unused Parameters # -->
@size: the number of bytes to allocate.


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

@n_bytes: 
@Returns: a pointer to the allocated memory.
<!-- # Unused Parameters # -->
@size: the number of bytes to allocate.


<!-- ##### FUNCTION g_realloc ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
@size 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.
<!-- # Unused Parameters # -->
@size: the new size of the allocated memory, in bytes.


<!-- ##### 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_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.
</para>

@size: number of bytes to allocate


<!-- ##### MACRO g_memmove ##### -->
<para>
Copies a block of memory @n bytes long, from @s to @d.
The source and destination areas may overlap.
</para>
<para>
In order to use this function, you must include string.h
yourself, because this macro will typically simply resolve
to memmove() and GLib does not include string.h for you.
</para>

@d: the destination address to copy the bytes to.
@s: the source address to copy the bytes from.
@n: the number of bytes to copy.


<!-- ##### 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. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
OTHER GLIB FUNCTIONS. The vtable only needs to provide malloc, realloc, and free
functions; GLib can provide default implementations of the others.  The malloc
and realloc 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.


<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
<para>

</para>


<!-- ##### FUNCTION g_mem_profile ##### -->
<para>
Outputs a summary of memory usage.
To use this function you must configure glib with the flag
'--enable-mem-profile=yes' before compiling.
</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>



