From 79131d73c3ccb3f24ef4fe9ccc6a24c6fa411d36 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sun, 27 Mar 2016 08:34:13 -0700 Subject: [PATCH 1/2] doc: document unspecified behavior for buf.write* methods Per https://github.com/nodejs/node/issues/1161, when the buf.write*() methods are given anything other than what they expect, indicate that the behavior is unspecified. Fixes: https://github.com/nodejs/node/issues/1161 --- doc/api/buffer.markdown | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index a2462e1bc4cb2f..0f42de73aaac6c 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -1397,7 +1397,8 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little -endian). The `value` argument must be a valid 64-bit double. +endian). The `value` argument *should* be a valid 64-bit double. Behavior is +unspecified if `value` is anything other than a 64-bit double. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1459,8 +1460,9 @@ console.log(buf); * `noAssert` {Boolean} Default: false * Return: {Number} The offset plus the number of written bytes -Writes `value` to the Buffer at the specified `offset`. The `value` must be a -valid signed 8-bit integer. +Writes `value` to the Buffer at the specified `offset`. The `value` should be a +valid signed 8-bit integer. Behavior is unspecified if `value` is anything +other than a signed 8-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1487,7 +1489,8 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little -endian). The `value` must be a valid signed 16-bit integer. +endian). The `value` should be a valid signed 16-bit integer. Behavior is +unspecified if `value` is anything other than a signed 16-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1514,7 +1517,8 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little -endian). The `value` must be a valid signed 32-bit integer. +endian). The `value` should be a valid signed 32-bit integer. Behavior is +unspecified if `value` is anything other than a signed 32-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1560,6 +1564,8 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. +Behavior is unspecified if `value` is anything other than an integer. + ### buf.writeUInt8(value, offset[, noAssert]) * `value` {Number} Bytes to be written to Buffer @@ -1567,8 +1573,9 @@ should not be used unless you are certain of correctness. * `noAssert` {Boolean} Default: false * Return: {Number} The offset plus the number of written bytes -Writes `value` to the Buffer at the specified `offset`. The `value` must be a -valid unsigned 8-bit integer. +Writes `value` to the Buffer at the specified `offset`. The `value` should be a +valid unsigned 8-bit integer. Behavior is unspecified if `value` is anything +other than an unsigned 8-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1598,7 +1605,8 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little -endian). The `value` must be a valid unsigned 16-bit integer. +endian). The `value` should be a valid unsigned 16-bit integer. Behavior is +unspecified if `value` is anything other than an unsigned 16-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1632,7 +1640,8 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little -endian). The `value` must be a valid unsigned 32-bit integer. +endian). The `value` should be a valid unsigned 32-bit integer. Behavior is +unspecified if `value` is anything other than an unsigned 32-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1678,6 +1687,8 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. +Behavior is unspecified if `value` is anything other than an unsigned integer. + ## buffer.INSPECT_MAX_BYTES * {Number} Default: 50 From 1aeb24f44a58fcf02460cd22fb7f5bdf9c4e7baa Mon Sep 17 00:00:00 2001 From: James M Snell Date: Fri, 1 Apr 2016 20:46:12 -0700 Subject: [PATCH 2/2] Address nits --- doc/api/buffer.markdown | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 0f42de73aaac6c..ce4fda84ea41b0 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -1398,7 +1398,7 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeDoubleBE()` writes big endian, `writeDoubleLE()` writes little endian). The `value` argument *should* be a valid 64-bit double. Behavior is -unspecified if `value` is anything other than a 64-bit double. +not defined when `value` is anything other than a 64-bit double. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1430,7 +1430,7 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeFloatBE()` writes big endian, `writeFloatLE()` writes little -endian). Behavior is unspecified if `value` is anything other than a 32-bit +endian). Behavior is not defined when `value` is anything other than a 32-bit float. Set `noAssert` to true to skip validation of `value` and `offset`. This means @@ -1461,7 +1461,7 @@ console.log(buf); * Return: {Number} The offset plus the number of written bytes Writes `value` to the Buffer at the specified `offset`. The `value` should be a -valid signed 8-bit integer. Behavior is unspecified if `value` is anything +valid signed 8-bit integer. Behavior is not defined when `value` is anything other than a signed 8-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means @@ -1490,7 +1490,7 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeInt16BE()` writes big endian, `writeInt16LE()` writes little endian). The `value` should be a valid signed 16-bit integer. Behavior is -unspecified if `value` is anything other than a signed 16-bit integer. +not defined when `value` is anything other than a signed 16-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1518,7 +1518,7 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeInt32BE()` writes big endian, `writeInt32LE()` writes little endian). The `value` should be a valid signed 32-bit integer. Behavior is -unspecified if `value` is anything other than a signed 32-bit integer. +not defined when `value` is anything other than a signed 32-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1564,7 +1564,7 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. -Behavior is unspecified if `value` is anything other than an integer. +Behavior is not defined when `value` is anything other than an integer. ### buf.writeUInt8(value, offset[, noAssert]) @@ -1574,7 +1574,7 @@ Behavior is unspecified if `value` is anything other than an integer. * Return: {Number} The offset plus the number of written bytes Writes `value` to the Buffer at the specified `offset`. The `value` should be a -valid unsigned 8-bit integer. Behavior is unspecified if `value` is anything +valid unsigned 8-bit integer. Behavior is not defined when `value` is anything other than an unsigned 8-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means @@ -1606,7 +1606,7 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeUInt16BE()` writes big endian, `writeUInt16LE()` writes little endian). The `value` should be a valid unsigned 16-bit integer. Behavior is -unspecified if `value` is anything other than an unsigned 16-bit integer. +not defined when `value` is anything other than an unsigned 16-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1641,7 +1641,7 @@ console.log(buf); Writes `value` to the Buffer at the specified `offset` with specified endian format (`writeUInt32BE()` writes big endian, `writeUInt32LE()` writes little endian). The `value` should be a valid unsigned 32-bit integer. Behavior is -unspecified if `value` is anything other than an unsigned 32-bit integer. +not defined when `value` is anything other than an unsigned 32-bit integer. Set `noAssert` to true to skip validation of `value` and `offset`. This means that `value` may be too large for the specific function and `offset` may be @@ -1687,7 +1687,7 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the Buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. -Behavior is unspecified if `value` is anything other than an unsigned integer. +Behavior is not defined when `value` is anything other than an unsigned integer. ## buffer.INSPECT_MAX_BYTES