Functions
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.
Care is taken to avoid overflow when calculating the size of the allocated block.
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.
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.
Care is taken to avoid overflow when calculating the size of the allocated block.
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.
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.
Care is taken to avoid overflow when calculating the size of the allocated block.
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.
The function returns NULL when n_structs
is 0 of if an overflow occurs.
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 or if an overflow occurs.
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.
The function returns NULL if an overflow occurs.
Returns
a pointer to the new allocated memory, cast to a pointer to struct_type
Since: 2.8
g_malloc ()
gpointer
g_malloc (gsize n_bytes);
Allocates n_bytes
bytes of memory.
If n_bytes
is 0 it returns NULL.
Returns
a pointer to the allocated memory
g_malloc0 ()
gpointer
g_malloc0 (gsize n_bytes);
Allocates n_bytes
bytes of memory, initialized to 0's.
If n_bytes
is 0 it returns NULL.
Returns
a pointer to the allocated memory
g_realloc ()
gpointer
g_realloc (gpointer mem,
gsize n_bytes);
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.
Returns
the new address of the allocated memory
g_try_malloc ()
gpointer
g_try_malloc (gsize n_bytes);
Attempts to allocate n_bytes
, and returns NULL on failure.
Contrast with g_malloc(), which aborts the program on failure.
Returns
the allocated memory, or NULL.
g_try_malloc0 ()
gpointer
g_try_malloc0 (gsize n_bytes);
Attempts to allocate n_bytes
, initialized to 0's, and returns NULL on
failure. Contrast with g_malloc0(), which aborts the program on failure.
Returns
the allocated memory, or NULL
Since: 2.8
g_try_realloc ()
gpointer
g_try_realloc (gpointer mem,
gsize n_bytes);
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().
Returns
the allocated memory, or NULL.
g_malloc_n ()
gpointer
g_malloc_n (gsize n_blocks,
gsize n_block_bytes);
This function is similar to g_malloc(), allocating (n_blocks
* n_block_bytes
) bytes,
but care is taken to detect possible overflow during multiplication.
Returns
a pointer to the allocated memory
Since: 2.24
g_malloc0_n ()
gpointer
g_malloc0_n (gsize n_blocks,
gsize n_block_bytes);
This function is similar to g_malloc0(), allocating (n_blocks
* n_block_bytes
) bytes,
but care is taken to detect possible overflow during multiplication.
Returns
a pointer to the allocated memory
Since: 2.24
g_realloc_n ()
gpointer
g_realloc_n (gpointer mem,
gsize n_blocks,
gsize n_block_bytes);
This function is similar to g_realloc(), allocating (n_blocks
* n_block_bytes
) bytes,
but care is taken to detect possible overflow during multiplication.
Returns
the new address of the allocated memory
Since: 2.24
g_try_malloc_n ()
gpointer
g_try_malloc_n (gsize n_blocks,
gsize n_block_bytes);
This function is similar to g_try_malloc(), allocating (n_blocks
* n_block_bytes
) bytes,
but care is taken to detect possible overflow during multiplication.
Returns
the allocated memory, or NULL.
Since: 2.24
g_try_malloc0_n ()
gpointer
g_try_malloc0_n (gsize n_blocks,
gsize n_block_bytes);
This function is similar to g_try_malloc0(), allocating (n_blocks
* n_block_bytes
) bytes,
but care is taken to detect possible overflow during multiplication.
Returns
the allocated memory, or NULL
Since: 2.24
g_try_realloc_n ()
gpointer
g_try_realloc_n (gpointer mem,
gsize n_blocks,
gsize n_block_bytes);
This function is similar to g_try_realloc(), allocating (n_blocks
* n_block_bytes
) bytes,
but care is taken to detect possible overflow during multiplication.
Returns
the allocated memory, or NULL.
Since: 2.24
g_free ()
void
g_free (gpointer mem);
Frees the memory pointed to by mem
.
If mem
is NULL it simply returns, so there is no need to check mem
against NULL before calling this function.
g_clear_pointer ()
void
g_clear_pointer (gpointer *pp,
GDestroyNotify destroy);
Clears a reference to a variable.
pp
must not be NULL.
If the reference is NULL then this function does nothing.
Otherwise, the variable is destroyed using destroy
and the
pointer is set to NULL.
A macro is also included that allows this function to be used without
pointer casts. This will mask any warnings about incompatible function types
or calling conventions, so you must ensure that your destroy
function is
compatible with being called as GDestroyNotify using the standard calling
convention for the platform that GLib was compiled for; otherwise the program
will experience undefined behaviour.
[skip]
Since: 2.34
g_steal_pointer ()
gpointer
g_steal_pointer (gpointer pp);
Sets pp
to NULL, returning the value that was there before.
Conceptually, this transfers the ownership of the pointer from the
referenced variable to the "caller" of the macro (ie: "steals" the
reference).
The return value will be properly typed, according to the type of
pp
.
This can be very useful when combined with g_autoptr() to prevent the
return value of a function from being automatically freed. Consider
the following example (which only works on GCC and clang):
It can also be used in similar ways for 'out' parameters and is
particularly useful for dealing with optional out parameters:
In the above example, the object will be automatically freed in the
early error case and also in the case that NULL was given for
obj_out
.
Since: 2.44
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.
Returns
space for size
bytes, allocated on the stack
g_newa()
#define g_newa(struct_type, n_structs)
Wraps g_alloca() in a more typesafe manner.
Returns
Pointer to stack space for n_structs
chunks of type struct_type
g_memmove()
#define g_memmove(dest,src,len)
g_memmove has been deprecated since version 2.40 and should not be used in newly-written code.
Just use memmove().
Copies a block of memory len
bytes long, from src
to dest
.
The source and destination areas may overlap.
g_memdup ()
gpointer
g_memdup (gconstpointer mem,
guint byte_size);
Allocates byte_size
bytes of memory, and copies byte_size
bytes into it
from mem
. If mem
is NULL it returns NULL.
Returns
a pointer to the newly-allocated copy of the memory, or NULL if mem
is NULL.
g_mem_set_vtable ()
void
g_mem_set_vtable (GMemVTable *vtable);
g_mem_set_vtable has been deprecated since version 2.46 and should not be used in newly-written code.
This function now does nothing. Use other memory
profiling tools instead
This function used to let you override the memory allocation function.
However, its use was incompatible with the use of global constructors
in GLib and GIO, because those use the GLib allocators before main is
reached. Therefore this function is now deprecated and is just a stub.
g_mem_is_system_malloc ()
gboolean
g_mem_is_system_malloc (void);
g_mem_is_system_malloc has been deprecated since version 2.46 and should not be used in newly-written code.
GLib always uses the system malloc, so this function always
returns TRUE.
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 interchangeably 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.
g_mem_profile ()
void
g_mem_profile (void);
g_mem_profile has been deprecated since version 2.46 and should not be used in newly-written code.
Use other memory profiling tools instead
GLib used to support some tools for memory profiling, but this
no longer works. There are many other useful tools for memory
profiling these days which can be used instead.