From 850d8ae019f9295d9f7d96eafad7593ee9c084e5 Mon Sep 17 00:00:00 2001 From: Aaron Thompson Date: Sat, 28 Mar 2020 20:41:48 +0000 Subject: [PATCH] Fix/improve some comments in buffer.h. isc_buffer_dup now cannot fail as a result of c73e5866c479c71b2fb61e882c249cc2c3de3af0. --- lib/isc/include/isc/buffer.h | 62 +++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 25 deletions(-) diff --git a/lib/isc/include/isc/buffer.h b/lib/isc/include/isc/buffer.h index 46931a44bf..ba6cf1685f 100644 --- a/lib/isc/include/isc/buffer.h +++ b/lib/isc/include/isc/buffer.h @@ -21,7 +21,7 @@ * \brief A buffer is a region of memory, together with a set of related * subregions. Buffers are used for parsing and I/O operations. * - * The 'used region' and the 'available' region are disjoint, and their + * The 'used region' and the 'available region' are disjoint, and their * union is the buffer's region. The used region extends from the beginning * of the buffer region to the last used byte. The available region * extends from one byte greater than the last used byte to the end of the @@ -32,7 +32,7 @@ * 'consumed region' and the 'remaining region'. The union of these two * regions is the used region. The consumed region extends from the beginning * of the used region to the byte before the 'current' offset (if any). The - * 'remaining' region the current pointer to the end of the used + * 'remaining' region extends from the current offset to the end of the used * region. The size of the consumed region can be changed using various * buffer commands. Initially, the consumed region is empty. * @@ -496,7 +496,7 @@ isc_buffer_getuint8(isc_buffer_t *b); * *\li 'b' is a valid buffer. * - *\li The length of the available region of 'b' is at least 1. + *\li The length of the remaining region of 'b' is at least 1. * * Ensures: * @@ -515,7 +515,7 @@ isc__buffer_putuint8(isc_buffer_t *b, uint8_t val); * Requires: *\li 'b' is a valid buffer. * - *\li The length of the unused region of 'b' is at least 1 + *\li The length of the available region of 'b' is at least 1 * or the buffer has autoreallocation enabled. * * Ensures: @@ -532,8 +532,7 @@ isc_buffer_getuint16(isc_buffer_t *b); * *\li 'b' is a valid buffer. * - *\li The length of the available region of 'b' is at least 2 - * or the buffer has autoreallocation enabled. + *\li The length of the remaining region of 'b' is at least 2. * * Ensures: * @@ -553,7 +552,7 @@ isc__buffer_putuint16(isc_buffer_t *b, uint16_t val); * Requires: *\li 'b' is a valid buffer. * - *\li The length of the unused region of 'b' is at least 2 + *\li The length of the available region of 'b' is at least 2 * or the buffer has autoreallocation enabled. * * Ensures: @@ -570,7 +569,7 @@ isc_buffer_getuint32(isc_buffer_t *b); * *\li 'b' is a valid buffer. * - *\li The length of the available region of 'b' is at least 4. + *\li The length of the remaining region of 'b' is at least 4. * * Ensures: * @@ -590,7 +589,7 @@ isc__buffer_putuint32(isc_buffer_t *b, uint32_t val); * Requires: *\li 'b' is a valid buffer. * - *\li The length of the unused region of 'b' is at least 4 + *\li The length of the available region of 'b' is at least 4 * or the buffer has autoreallocation enabled. * * Ensures: @@ -607,7 +606,7 @@ isc_buffer_getuint48(isc_buffer_t *b); * *\li 'b' is a valid buffer. * - *\li The length of the available region of 'b' is at least 6. + *\li The length of the remaining region of 'b' is at least 6. * * Ensures: * @@ -627,7 +626,7 @@ isc__buffer_putuint48(isc_buffer_t *b, uint64_t val); * Requires: *\li 'b' is a valid buffer. * - *\li The length of the unused region of 'b' is at least 6 + *\li The length of the available region of 'b' is at least 6 * or the buffer has autoreallocation enabled. * * Ensures: @@ -643,7 +642,7 @@ isc__buffer_putuint24(isc_buffer_t *b, uint32_t val); * Requires: *\li 'b' is a valid buffer. * - * The length of the unused region of 'b' is at least 3 + *\li The length of the available region of 'b' is at least 3 * or the buffer has autoreallocation enabled. * * Ensures: @@ -657,11 +656,15 @@ isc__buffer_putmem(isc_buffer_t *b, const unsigned char *base, * \brief Copy 'length' bytes of memory at 'base' into 'b'. * * Requires: - *\li 'b' is a valid buffer, and it has at least 'length' - * or the buffer has autoreallocation enabled. + *\li 'b' is a valid buffer. * *\li 'base' points to 'length' bytes of valid memory. * + *\li The length of the available region of 'b' is at least 'length' + * or the buffer has autoreallocation enabled. + * + * Ensures: + *\li The used pointer in 'b' is advanced by 'length'. */ void @@ -672,9 +675,13 @@ isc__buffer_putstr(isc_buffer_t *b, const char *source); * Requires: *\li 'b' is a valid buffer. * - *\li 'source' to be a valid NULL terminated string. + *\li 'source' is a valid NULL terminated string. * - *\li strlen(source) <= isc_buffer_available(b) || b->mctx != NULL + *\li The length of the available region of 'b' is at least strlen('source') + * or the buffer has autoreallocation enabled. + * + * Ensures: + *\li The used pointer in 'b' is advanced by strlen('source'). */ void @@ -685,7 +692,11 @@ isc_buffer_putdecint(isc_buffer_t *b, int64_t v); * Requires: *\li 'b' is a valid buffer. * - *\li strlen(dec(v)) <= isc_buffer_available(b) || b->mctx != NULL + *\li The length of the available region of 'b' is at least strlen(dec('v')) + * or the buffer has autoreallocation enabled. + * + * Ensures: + *\li The used pointer in 'b' is advanced by strlen(dec('v')). */ isc_result_t @@ -693,13 +704,16 @@ isc_buffer_copyregion(isc_buffer_t *b, const isc_region_t *r); /*!< * \brief Copy the contents of 'r' into 'b'. * + * Notes: + *\li If 'b' has autoreallocation enabled, and the length of 'r' is greater + * than the length of the available region of 'b', 'b' is reallocated. + * * Requires: *\li 'b' is a valid buffer. * *\li 'r' is a valid region. * * Returns: - * *\li ISC_R_SUCCESS *\li ISC_R_NOSPACE The available region of 'b' is not * big enough. @@ -708,17 +722,14 @@ isc_buffer_copyregion(isc_buffer_t *b, const isc_region_t *r); isc_result_t isc_buffer_dup(isc_mem_t *mctx, isc_buffer_t **dstp, const isc_buffer_t *src); /*!< - * \brief Allocate 'dst' and copy used contents of 'src' into it + * \brief Allocate 'dst' and copy used contents of 'src' into it. * * Requires: - *\li 'dstp' is not NULL and *dst is NULL + *\li 'dstp' is not NULL and *dst is NULL. *\li 'src' is a valid buffer. * * Returns: - * *\li ISC_R_SUCCESS - *\li ISC_R_NOSPACE The available region of 'b' is not - * big enough. */ isc_result_t @@ -732,8 +743,9 @@ isc_buffer_printf(isc_buffer_t *b, const char *format, ...) *\li The 'format' argument is a printf(3) string, with additional arguments * as necessary. * - *\li If 'b' has autoreallocation enabled, and the formatted string - * would overrun the buffer, the buffer is reallocated. + *\li If 'b' has autoreallocation enabled, and the length of the formatted + * string is greater than the length of the available region of 'b', 'b' + * is reallocated. * * Requires: *