talloc: Add a warning to talloc_reference() documentation.

[sfrench/samba-autobuild/.git] / lib / talloc / talloc.h

diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h
index 1b59390e33aa467811b00b04bc7d35ccab2d582c..5d29a8d5cf050f9ec5d4f16e81885e6437e6b9ee 100644 (file)
--- a/lib/talloc/talloc.h
+++ b/lib/talloc/talloc.h
@@ -961,6 +961,10 @@ size_t talloc_reference_count(const void *ptr);
  * @return              The original pointer 'ptr', NULL if talloc ran out of
  *                      memory in creating the reference.
  *
+ * @warning You should try to avoid using this interface. It turns a beautiful
+ *          talloc-tree into a graph. It is often really hard to debug if you
+ *          screw something up by accident.
+ *
  * Example:
  * @code
  *      unsigned int *a, *b, *c;
@@ -1001,6 +1005,10 @@ void *_talloc_reference_loc(const void *context, const void *ptr, const char *lo
  * this function will fail and will return -1.  Likewise, if ptr is NULL,
  * then the function will make no modifications and return -1.
  *
+ * @warning You should try to avoid using this interface. It turns a beautiful
+ *          talloc-tree into a graph. It is often really hard to debug if you
+ *          screw something up by accident.
+ *
  * Example:
  * @code
  *      unsigned int *a, *b, *c;