talloc:documentation - explain that "talloc_free" works also with "NULL" pointers

(talloc.c)
...
> static inline int _talloc_free_internal(void *ptr, const char *location)
> {
>        struct talloc_chunk *tc;
>
>        if (unlikely(ptr == NULL)) {
>                return -1;
>        }
>
>        tc = talloc_chunk_from_ptr(ptr);
...

Obviously this never had been documented before.

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