GLibsteal_pointer

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.