GLib.steal_pointer (original) (raw)

Function

GLibsteal_pointer

since: 2.44

Declaration [src]

static inline gpointer
g_steal_pointer (
  gpointer 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 ofpp.

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 forobj_out.

Available since: 2.44

This function is not directly available to language bindings.

Parameters

pp

Type: gpointer

A pointer to a pointer.

The data is owned by the caller of the function.

Return value

Type: gpointer

No description available.