Description

Note

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.

Note

It's important to match g_malloc() with g_free(), plain malloc() with free(),
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
g_mem_set_vtable().

Details

g_new()

#define g_new(struct_type, n_structs)

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.

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.

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

g_new0()

#define g_new0(struct_type, n_structs)

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.

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.

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.

g_renew()

#define g_renew(struct_type, mem, n_structs)

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.

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

g_try_new()

#define g_try_new(struct_type, n_structs)

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.

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

g_try_new0()

#define g_try_new0(struct_type, n_structs)

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.
The function returns NULL when n_structs is 0.

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

g_try_renew()

#define g_try_renew(struct_type, mem, n_structs)

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.

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

g_realloc ()

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
and mem will be freed unless it is NULL.

g_free ()

g_mem_gc_friendly

extern gboolean g_mem_gc_friendly;

This variable is TRUE if the G_DEBUG environment variable
includes the key gc-friendly.

g_alloca()

#define g_alloca(size)

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 alloca()
function present on most UNIX variants.
Thus it provides the same advantages and pitfalls as alloca():

+ alloca() is very fast, as on most systems it's implemented by just adjusting
the stack pointer register.

+ It doesn't cause any memory fragmentation, within its scope, separate alloca()
blocks just build up and are released together at function end.

- 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 alloca() uses.

- Allocation failure due to insufficient stack space is not indicated with a NULL
return like e.g. with malloc(). 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.

- Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
Stack space allocated with alloca() 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.

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.

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.

g_mem_set_vtable ()

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.

vtable :

table of memory allocation routines.

g_mem_is_system_malloc ()

Checks whether the allocator used by g_malloc() is the system's
malloc implementation. If it returns TRUE memory allocated with
malloc() can be used interchangeable with memory allocated using g_malloc().
This function is useful for avoiding an extra copy of allocated memory returned
by a non-GLib-based API.

glib_mem_profiler_table

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.

g_mem_profile ()

void g_mem_profile (void);

Outputs a summary of memory usage.

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.