From: Willy Tarreau <w@1wt.eu>
Date: Thu, 31 Jan 2019 06:21:42 +0000 (+0100)
Subject: DOC: htx: make it clear that htxbuf() and htx_from_buf() always return valid pointers
X-Git-Tag: v2.0-dev1~101
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=245d189cce724967d4709ab41365d909870be829;p=thirdparty%2Fhaproxy.git

DOC: htx: make it clear that htxbuf() and htx_from_buf() always return valid pointers

Update the comments above htxbuf() and htx_from_buf() to make it clear
that they always return valid htx pointers so that callers know they do
not have to test them. This is only true after the fix on b_is_null()
which was the only known corner case.

This should be backported to 1.9 if the b_is_null() patch is backported.
---

diff --git a/include/common/htx.h b/include/common/htx.h
index 94df4bbd48..36941401dc 100644
--- a/include/common/htx.h
+++ b/include/common/htx.h
@@ -690,7 +690,10 @@ static inline size_t buf_room_for_htx_data(const struct buffer *buf)
 
 
 /* Returns an HTX message using the buffer <buf>. Unlike htx_from_buf(), this
- * function does not update to the buffer. */
+ * function does not update to the buffer.
+ * Note that it always returns a valid pointer, either to an initialized buffer
+ * or to the empty buffer.
+ */
 static inline struct htx *htxbuf(const struct buffer *buf)
 {
 	struct htx *htx;
@@ -707,10 +710,10 @@ static inline struct htx *htxbuf(const struct buffer *buf)
 
 /* Returns an HTX message using the buffer <buf>. <buf> is updated to appear as
  * full. It is the caller responsibility to call htx_to_buf() when it finish to
- * manipulate the HTX message to update <buf> accordingly.
+ * manipulate the HTX message to update <buf> accordingly. The returned pointer
+ * is always valid.
  *
- * If the caller can call htxbuf() function to avoir any update of the
- * buffer.
+ * The caller can call htxbuf() function to avoid any update of the buffer.
  */
 static inline struct htx *htx_from_buf(struct buffer *buf)
 {