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.

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.

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.

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.

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.

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.

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.

If the allocation fails (because the system is out of memory), the program is terminated.

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.

If the allocation fails (because the system is out of memory), the program is terminated.

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.

If the allocation fails (because the system is out of memory), the program is terminated.

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.

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.

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

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.

If the allocation fails (because the system is out of memory), the program is terminated.

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.

If the allocation fails (because the system is out of memory), the program is terminated.

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.

If the allocation fails (because the system is out of memory), the program is terminated.

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.

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.

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.

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):

1
2
3
4
5
6
7
8
9
10

GObject *
create_object (void)
{
  g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);

  if (early_error_case)
    return NULL;

  return g_steal_pointer (&obj);
}

It can also be used in similar ways for 'out' parameters and is particularly useful for dealing with optional out parameters:

1
2
3
4
5
6
7
8
9
10
11
12
13

gboolean
get_object (GObject **obj_out)
{
  g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);

  if (early_error_case)
    return FALSE;

  if (obj_out)
    *obj_out = g_steal_pointer (&obj);

  return TRUE;
}

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():

g_alloca0()

#define             g_alloca0(size)

Wraps g_alloca() and initializes allocated memory to zeroes. If size is 0 it returns NULL.

Note that the size argument will be evaluated multiple times.

Since: 2.72

g_newa()

#define             g_newa(struct_type, n_structs)

Wraps g_alloca() in a more typesafe manner.

As mentioned in the documentation for g_alloca(), n_structs must always be entirely under the control of the program, or you may introduce a denial of service vulnerability. In addition, the multiplication of struct_type by n_structs is not checked, so an overflow may lead to a remote code execution vulnerability.

g_newa0()

#define             g_newa0(struct_type, n_structs)

Wraps g_alloca0() in a more typesafe manner.

Since: 2.72

g_aligned_alloc ()

gpointer
g_aligned_alloc (gsize n_blocks,
                 gsize n_block_bytes,
                 gsize alignment);

This function is similar to g_malloc(), allocating (n_blocks * n_block_bytes ) bytes, but care is taken to align the allocated memory to with the given alignment value. Additionally, it will detect possible overflow during multiplication.

If the allocation fails (because the system is out of memory), the program is terminated.

Aligned memory allocations returned by this function can only be freed using g_aligned_free().

Since: 2.72

g_aligned_alloc0 ()

gpointer
g_aligned_alloc0 (gsize n_blocks,
                  gsize n_block_bytes,
                  gsize alignment);

This function is similar to g_aligned_alloc(), but it will also clear the allocated memory before returning it.

Since: 2.72

g_aligned_free ()

void
g_aligned_free (gpointer mem);

Frees the memory allocated by g_aligned_alloc().

Since: 2.72

g_memmove()

#define             g_memmove(dest,src,len)

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.

g_memdup2 ()

gpointer
g_memdup2 (gconstpointer mem,
           gsize byte_size);

Allocates byte_size bytes of memory, and copies byte_size bytes into it from mem . If mem is NULL it returns NULL.

This replaces g_memdup(), which was prone to integer overflows when converting the argument from a gsize to a guint.

Since: 2.68

g_mem_set_vtable ()

void
g_mem_set_vtable (GMemVTable *vtable);

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);

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);

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.

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.

struct GMemVTable

struct GMemVTable {
  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);
};

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.

This functions related to this has been deprecated in 2.46, and no longer work.

glib_mem_profiler_table

extern GMemVTable *glib_mem_profiler_table;

Used to be a GMemVTable containing profiling variants of the memory allocation functions, but this variable shouldn't be modified anymore.