summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--lib/talloc/talloc.h31
-rw-r--r--lib/talloc/talloc_guide.txt9
2 files changed, 26 insertions, 14 deletions
diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h
index c59fd352ed..187d7e7816 100644
--- a/lib/talloc/talloc.h
+++ b/lib/talloc/talloc.h
@@ -158,16 +158,25 @@ void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
/**
* @brief Free a chunk of talloc memory.
*
- * This function frees a piece of talloc memory, and all its children. It
- * operates recursively on its children. You can call talloc_free() on any
- * pointer returned by talloc().
+ * The talloc_free() function frees a piece of talloc memory, and all its
+ * children. You can call talloc_free() on any pointer returned by
+ * talloc().
*
- * If this pointer has an additional parent when talloc_free() is called then
- * the memory is not actually released, but instead the most recently
- * established parent is destroyed. See talloc_reference() for details on
- * establishing additional parents.
+ * The return value of talloc_free() indicates success or failure, with 0
+ * returned for success and -1 for failure. A possible failure condition
+ * is if the pointer had a destructor attached to it and the destructor
+ * returned -1. See talloc_set_destructor() for details on
+ * destructors. Likewise, if "ptr" is NULL, then the function will make
+ * no modifications and return -1.
*
- * For more control on which parent is removed, see talloc_unlink().
+ * If this pointer has an additional parent when talloc_free() is called
+ * then the memory is not actually released, but instead the most
+ * recently established parent is destroyed. See talloc_reference() for
+ * details on establishing additional parents.
+ *
+ * For more control on which parent is removed, see talloc_unlink()
+ *
+ * talloc_free() operates recursively on its children.
*
* From the 2.0 version of talloc, as a special case, talloc_free() is
* refused on pointers that have more than one parent, as talloc would
@@ -190,9 +199,11 @@ void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
*
* @param[in] ptr The chunk to be freed.
*
- * @return Returns 0 on success and -1 on error. The only possible
+ * @return Returns 0 on success and -1 on error. A possible
* failure condition is if the pointer had a destructor
- * attached to it and the destructor returned -1.
+ * attached to it and the destructor returned -1. Likewise,
+ * if "ptr" is NULL, then the function will make no
+ * modifications and returns -1.
*
* Example:
* @code
diff --git a/lib/talloc/talloc_guide.txt b/lib/talloc/talloc_guide.txt
index 79387bfd46..a79fd03a83 100644
--- a/lib/talloc/talloc_guide.txt
+++ b/lib/talloc/talloc_guide.txt
@@ -117,10 +117,11 @@ children. You can call talloc_free() on any pointer returned by
talloc().
The return value of talloc_free() indicates success or failure, with 0
-returned for success and -1 for failure. The only possible failure
-condition is if the pointer had a destructor attached to it and the
-destructor returned -1. See talloc_set_destructor() for details on
-destructors.
+returned for success and -1 for failure. A possible failure condition
+is if the pointer had a destructor attached to it and the destructor
+returned -1. See talloc_set_destructor() for details on
+destructors. Likewise, if "ptr" is NULL, then the function will make
+no modifications and returns -1.
If this pointer has an additional parent when talloc_free() is called
then the memory is not actually released, but instead the most