From 798b3fbb53fb229c93b841e380a4439d6575d75a Mon Sep 17 00:00:00 2001 From: Andrew Tridgell Date: Mon, 24 Aug 2009 16:01:18 +1000 Subject: updated XML source for talloc man page --- lib/talloc/talloc.3.xml | 74 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) (limited to 'lib') diff --git a/lib/talloc/talloc.3.xml b/lib/talloc/talloc.3.xml index 67de15bfc8..3e895b20b5 100644 --- a/lib/talloc/talloc.3.xml +++ b/lib/talloc/talloc.3.xml @@ -135,6 +135,29 @@ talloc_free() operates recursively on its children. + + As a special case, talloc_free() is refused on pointers that + have more than one parent, as talloc would have no way of knowing + which parent should be removed. To free a pointer that has more than + one parent please use talloc_unlink(). + + + To help you find problems in your code caused by this behaviour, if + you do try and free a pointer with more than one parent then the + talloc logging function will be called to give output like this: + + + + ERROR: talloc_free with references at some_dir/source/foo.c:123 + reference at some_dir/source/other.c:325 + reference at some_dir/source/third.c:121 + + + + Please see the documentation for talloc_set_log_fn() and + talloc_set_log_stderr() for more information on talloc logging + functions. + void *talloc_reference(const void *ctx, const void *ptr); @@ -381,11 +404,48 @@ talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr); It does not have any failure modes. - NOTE: It is possible to produce loops in the parent/child + It is possible to produce loops in the parent/child relationship if you are not careful with talloc_steal(). No guarantees are provided as to your sanity or the safety of your data if you do this. + + Note that if you try and call talloc_steal() on a pointer that has + more than one parent then the result is ambiguous. Talloc will choose + to remove the parent that is currently indicated by talloc_parent() + and replace it with the chosen parent. You will also get a message + like this via the talloc logging functions: + + + + WARNING: talloc_steal with references at some_dir/source/foo.c:123 + reference at some_dir/source/other.c:325 + reference at some_dir/source/third.c:121 + + + + To unambiguously change the parent of a pointer please see + the + function talloc_reparent(). See + the talloc_set_log_fn() documentation for more information + on talloc logging. + TYPE *talloc_reparent(const void *<emphasis role="italic">old_parent</emphasis>, const void *<emphasis role="italic">new_parent</emphasis>, const TYPE *<emphasis role="italic">ptr</emphasis>); + + The talloc_reparent() function changes the parent context of a talloc + pointer. It is typically used when the context that the pointer is + currently a child of is going to be freed and you wish to keep the + memory for a longer time. + + + The talloc_reparent() function returns the pointer that you pass it. It + does not have any failure modes. + + + The difference between talloc_reparent() and talloc_steal() is that + talloc_reparent() can specify which parent you wish to change. This is + useful when a pointer has multiple parents via references. + TYPE *talloc_move(const void *<emphasis role="italic">new_ctx</emphasis>, TYPE **<emphasis role="italic">ptr</emphasis>); @@ -696,6 +756,18 @@ if (ptr) memcpy(ptr, p, strlen(p)+1); talloc_set_name_const(ptr, #type) + talloc_set_log_fn(void (*log_fn)(const char *message)); + + This function sets a logging function that talloc will use for + warnings and errors. By default talloc will not print any warnings or + errors. + + + talloc_set_log_stderr(void); + + This sets the talloc log function to write log messages to stderr + + PERFORMANCE -- cgit