Function Macro

GLibsteal_pointer

Declaration [src]

#define g_steal_pointer (
  pp
)

Description [src]

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

Parameters

pp -
 

A pointer to a pointer.