summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Dieter Wallnöfer <mdw@samba.org>2010-08-14 18:36:49 +0200
committerMatthias Dieter Wallnöfer <mdw@samba.org>2010-08-14 18:48:20 +0200
commit2de63aa2801a907905b3e05557074af5b896d486 (patch)
tree728094b47b5b26c0c073bf927db3c0443148d142
parent07af3f289e403396a9ddef744cf42e2badc1f1cc (diff)
downloadsamba-2de63aa2801a907905b3e05557074af5b896d486.tar.gz
samba-2de63aa2801a907905b3e05557074af5b896d486.tar.bz2
samba-2de63aa2801a907905b3e05557074af5b896d486.zip
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.
-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