Function Macro


since: 2.44


#define g_steal_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:

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.



Type: -

A pointer to a pointer.