GLibsteal_pointer

staticinlinegpointer
g_steal_pointer(
gpointerpp
)

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

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:

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.

Available since: 2.44

This function is not directly available to language bindings.

pp

Type: gpointer

A pointer to a pointer.

The data is owned by the caller of the function.