From: Arran Cudbard-Bell <a.cudbardb@freeradius.org>
Date: Thu, 12 Nov 2020 22:43:00 +0000 (-0600)
Subject: Make the warnings around caching pointers clearer
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3981239e2baa6376bb4e56b653e104f81c4e4bb5;p=thirdparty%2Ffreeradius-server.git

Make the warnings around caching pointers clearer
---

diff --git a/src/lib/util/dbuff.h b/src/lib/util/dbuff.h
index a4813593f9d..b6e99154af2 100644
--- a/src/lib/util/dbuff.h
+++ b/src/lib/util/dbuff.h
@@ -616,10 +616,9 @@ size_t	fr_dbuff_extend_talloc(fr_dbuff_t *dbuff, size_t extension);
 
 /** @name Accessors
  *
- * Caching the values of pointers returned by the accessors, the pointer values
- * take directly from the dbuff directly is strongly discouraged, as the pointers
- * can become invalidated during stream reading or writing to/from an
- * extensible buffer.
+ * Caching the pointers returned by the accessors is strongly discouraged.
+ * Cached pointers can become invalidated if the dbuff is extended, as the
+ * extensions callback may use realloc or memmove on the underlying buffer.
  *
  @code{.c}
  fr_dbuff_t dbuff;
@@ -636,8 +635,8 @@ size_t	fr_dbuff_extend_talloc(fr_dbuff_t *dbuff, size_t extension);
  @endcode
  *
  * If offsets of a dbuff need to be accessed, markers should be used.  If a dbuff
- * is extended, all markers associated with it will be updated so that their values
- * remain valid.
+ * is extended all markers associated with it will be updated so that the data they
+ * point to remains constant.
  *
  @code{.c}
  fr_dbuff_t dbuff;