mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-30 14:07:59 +00:00
Fix/improve some comments in buffer.h.
isc_buffer_dup now cannot fail as a result of c73e5866c479c71b2fb61e882c249cc2c3de3af0.
This commit is contained in:
Aaron Thompson
Ondřej Surý
parent
5a26673d49
commit
850d8ae019
@ -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:
|
||||
*
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user