diff options
| -rw-r--r-- | lib/talloc/talloc.h | 31 | ||||
| -rw-r--r-- | lib/talloc/talloc_guide.txt | 9 |
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 |