MINOR: log/tools: fix ambiguous comments for some log encoding helpers

Some log encoding helpers are not text oriented, and they will use all
available space since they will not try to write a terminating NULL
byte at the end of the produced output themselves. But since they
work similarly to text oriented ones, they return the address of
the byte immediately following the payload (where we expect
following bytes to be written). For text oriented ones this corresponds
in fact to the terminating NULL byte which was accounted in the
available space, while for non text-oriented ones, which doesn't reserve
space for the terminating NULL byte this corresponds to 1 byte past the
payload. If available space is strictly the size of the produced output,
then it means the returned address will be 1 byte PAST the stop limit so
no extra bytes could be written anymore. When using this helpers, callers
have to be very careful to reserve bytes (ie: terminating NULL byte) if
they need to.

It may be backported up to 3.0. Before that such ambiguities didn't exist
as logging features were strictly text-oriented and log encoders were not
available.

diff --git a/src/log.c b/src/log.c
index 8b06061156a2ec9daac0fa78cd2b943f18f869b5..c48e0a7c5c58e30a52d05d9c8d95e86b2ab90220 100644 (file)
--- a/src/log.c
+++ b/src/log.c
@@ -2028,8 +2028,8 @@ static THREAD_LOCAL char lf_buildbuf[256]; /* fixed size buffer for building sma
 
 /* helper to encode a single byte in hex form
  *
- * Returns the position of the last written byte on success and NULL on
- * error.
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static char *_encode_byte_hex(char *start, char *stop, unsigned char byte)
 {
@@ -2046,8 +2046,8 @@ static char *_encode_byte_hex(char *start, char *stop, unsigned char byte)
  * The function may only be called under CBOR context (that is when
  * LOG_OPT_ENCODE_CBOR option is set).
  *
- * Returns the position of the last written byte on success and NULL on
- * error.
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static char *_lf_cbor_encode_byte(struct cbor_encode_ctx *cbor_ctx,
                                   char *start, char *stop, unsigned char byte)
@@ -2093,6 +2093,9 @@ static inline void lf_buildctx_prepare(struct lf_buildctx *ctx,
 
 /* helper function for _lf_encode_bytes() to escape a single byte
  * with <escape>
+ *
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static inline char *_lf_escape_byte(char *start, char *stop,
                                     char byte, const char escape)
@@ -2108,6 +2111,9 @@ static inline char *_lf_escape_byte(char *start, char *stop,
 
 /* helper function for _lf_encode_bytes() to escape a single byte
  * with <escape> and deal with cbor-specific encoding logic
+ *
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static inline char *_lf_cbor_escape_byte(char *start, char *stop,
                                          char byte, const char escape,
@@ -2132,8 +2138,8 @@ static inline char *_lf_cbor_escape_byte(char *start, char *stop,
  *
  * The function assumes that at least 1 byte is available for writing
  *
- * Returns the address of the last written byte on success, or NULL
- * on error
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static inline char *_lf_map_escape_byte(char *start, char *stop,
                                         const char *byte,
@@ -2155,8 +2161,8 @@ static inline char *_lf_map_escape_byte(char *start, char *stop,
  *
  * The function assumes that at least 1 byte is available for writing
  *
- * Returns the address of the last written byte on success, or NULL
- * on error
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static inline char *_lf_cbor_map_escape_byte(char *start, char *stop,
                                              const char *byte,
@@ -2199,8 +2205,8 @@ static inline char *_lf_cbor_map_escape_byte(char *start, char *stop,
  *
  * The function assumes that at least 1 byte is available for writing
  *
- * Returns the address of the last written byte on success, or NULL
- * on error
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static inline char *_lf_rfc5424_escape_byte(char *start, char *stop,
                                             const char *byte,
@@ -2230,8 +2236,8 @@ static inline char *_lf_rfc5424_escape_byte(char *start, char *stop,
  *
  * The function assumes that at least 1 byte is available for writing
  *
- * Returns the address of the last written byte on success, or NULL
- * on error
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. It will not append terminating NULL byte.
  */
 static inline char *_lf_json_escape_byte(char *start, char *stop,
                                          const char *byte,

diff --git a/src/tools.c b/src/tools.c
index 08dbc78d366cc261e356f0b9663b1fc68552d35a..c19f6fc2792a85c6f1941fcaee83989028a7ae3d 100644 (file)
--- a/src/tools.c
+++ b/src/tools.c
@@ -2198,8 +2198,9 @@ int chunk_escape_string(struct buffer *chunk, const char *str, size_t len)
  *
  * CBOR encode ctx is provided in <ctx>
  *
- * Returns the position of the last written byte on success and NULL on
- * error. The function cannot write past <stop>
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. The function cannot write past <stop>.
+ * It will not append terminating NULL byte.
  */
 char *cbor_encode_uint64_prefix(struct cbor_encode_ctx *ctx,
                                 char *start, char *stop, uint64_t value,
@@ -2260,8 +2261,9 @@ char *cbor_encode_uint64_prefix(struct cbor_encode_ctx *ctx,
  *
  * CBOR encode ctx is provided in <ctx>
  *
- * Returns the position of the last written byte on success and NULL on
- * error. The function cannot write past <stop>
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. The function cannot write past <stop>.
+ * It will not append terminating NULL byte.
  */
 char *cbor_encode_int64(struct cbor_encode_ctx *ctx,
                         char *start, char *stop, int64_t value)
@@ -2291,8 +2293,9 @@ char *cbor_encode_int64(struct cbor_encode_ctx *ctx,
  *
  * CBOR encode ctx is provided in <ctx>
  *
- * Returns the position of the last written byte on success and NULL on
- * error. The function cannot write past <stop>
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. The function cannot write past <stop>.
+ * It will not append terminating NULL byte.
  */
 char *cbor_encode_bytes_prefix(struct cbor_encode_ctx *ctx,
                                char *start, char *stop,
@@ -2324,8 +2327,9 @@ char *cbor_encode_bytes_prefix(struct cbor_encode_ctx *ctx,
  *
  * CBOR encode ctx is provided in <ctx>
  *
- * Returns the position of the last written byte on success and NULL on
- * error. The function cannot write past <stop>
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. The function cannot write past <stop>.
+ * It will not append terminating NULL byte.
  */
 char *cbor_encode_text(struct cbor_encode_ctx *ctx,
                        char *start, char *stop,
@@ -2341,8 +2345,9 @@ char *cbor_encode_text(struct cbor_encode_ctx *ctx,
  *
  * CBOR encode ctx is provided in <ctx>
  *
- * Returns the position of the last written byte on success and NULL on
- * error. The function cannot write past <stop>
+ * Returns the address of the byte immediately after the last written byte
+ * on success, or NULL on error. The function cannot write past <stop>.
+ * It will not append terminating NULL byte.
  */
 char *cbor_encode_bytes(struct cbor_encode_ctx *ctx,
                         char *start, char *stop,