Commit c691f1f2 authored by Ondřej Surý's avatar Ondřej Surý

Merge branch '1763-improve-isc_buffer-API-documentation' into 'master'

Fix/improve some comments in buffer.h.

Closes #1763

See merge request isc-projects/bind9!3388
parents 5a26673d 850d8ae0
......@@ -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 The length of the available region of 'b' is at least strlen('source')
* or the buffer has autoreallocation enabled.
*
*\li strlen(source) <= isc_buffer_available(b) || b->mctx != NULL
* 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:
*
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment