From: Alex Rousskov <rousskov@measurement-factory.com>
Date: Thu, 18 Jul 2013 02:07:31 +0000 (-0600)
Subject: Documented space() methods to explain why bugs like 3869 keep happening.
X-Git-Tag: SQUID_3_4_0_1~14
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3aa3d38538c277cc49641fb3edbe0ac35f34d8a7;p=thirdparty%2Fsquid.git

Documented space() methods to explain why bugs like 3869 keep happening.

Hopefully we will not repeat these mistakes with StringNG.
---

diff --git a/src/MemBuf.h b/src/MemBuf.h
index c12fb761d8..571c8c3762 100644
--- a/src/MemBuf.h
+++ b/src/MemBuf.h
@@ -62,9 +62,14 @@ public:
      */
     bool hasContent() const { return size > 0; }
 
-    /// these space-related methods assume no growth and allow 0-termination
-    char *space() { return buf + size; } // space to add data
-    char *space(mb_size_t required) { if (size + required >= capacity) grow(size + required +1); return buf + size; } // space to add data
+    /// returns buffer after data; does not check space existence
+    char *space() { return buf + size; } ///< space to add data
+
+    /// Returns buffer following data, after possibly growing the buffer to
+    /// accommodate addition of the required bytes PLUS a 0-terminator char.
+    /// The caller is not required to terminate the buffer, but MemBuf does
+    /// terminate internally, trading termination for size calculation bugs.
+    char *space(mb_size_t required) { if (size + required >= capacity) grow(size + required + 1); return buf + size; }
 
     mb_size_t spaceSize() const;