From d8cda173bb56916a38ea4b2185fe0b95aa19e5af Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 23 Mar 2018 14:52:55 -0700 Subject: [PATCH 1/3] doc: change v-notation for version in buffer.md Change v6 to 6.0.0. We abandoned v-notation for versions to avoid confusion between v8 (version 8.0.0) and V8 (the JavaScript engine). --- doc/api/buffer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 750d112737471f..4d01f958f43e32 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -48,7 +48,7 @@ const buf6 = Buffer.from('tést', 'latin1'); ## `Buffer.from()`, `Buffer.alloc()`, and `Buffer.allocUnsafe()` -In versions of Node.js prior to v6, `Buffer` instances were created using the +In versions of Node.js prior to 6.0.0, `Buffer` instances were created using the `Buffer` constructor function, which allocates the returned `Buffer` differently based on what arguments are provided: From 8c212724103476f685349d775a6a174ba6c726b3 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 23 Mar 2018 15:02:35 -0700 Subject: [PATCH 2/3] doc: fix run-on sentence in buffer.md --- doc/api/buffer.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 4d01f958f43e32..3223bde1db3248 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -68,11 +68,10 @@ differently based on what arguments are provided: * Passing an [`ArrayBuffer`] or a [`SharedArrayBuffer`] returns a `Buffer` that shares allocated memory with the given array buffer. -Because the behavior of `new Buffer()` changes significantly based on the type -of value passed as the first argument, applications that do not properly -validate the input arguments passed to `new Buffer()`, or that fail to -appropriately initialize newly allocated `Buffer` content, can inadvertently -introduce security and reliability issues into their code. +Because the behavior of `new Buffer()` is different depending on the type of the +first argument, security and reliability issues can be inadvertantly introduced +into applications when argument validation or `Buffer` initialization are not +performed. To make the creation of `Buffer` instances more reliable and less error prone, the various forms of the `new Buffer()` constructor have been **deprecated** From 8c184d8974f70e68131a9dfaa509c04d71c02b38 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 23 Mar 2018 15:13:13 -0700 Subject: [PATCH 3/3] doc: improve Buffer() text Rewording, punctuation, consistent sentence structure and italics, wrap section at 80 characters. --- doc/api/buffer.md | 48 +++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 3223bde1db3248..165a1aff437dc0 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -52,28 +52,27 @@ In versions of Node.js prior to 6.0.0, `Buffer` instances were created using the `Buffer` constructor function, which allocates the returned `Buffer` differently based on what arguments are provided: -* Passing a number as the first argument to `Buffer()` (e.g. `new Buffer(10)`), +* Passing a number as the first argument to `Buffer()` (e.g. `new Buffer(10)`) allocates a new `Buffer` object of the specified size. Prior to Node.js 8.0.0, the memory allocated for such `Buffer` instances is *not* initialized and *can contain sensitive data*. Such `Buffer` instances *must* be subsequently initialized by using either [`buf.fill(0)`][`buf.fill()`] or by writing to the - `Buffer` completely. While this behavior is *intentional* to improve - performance, development experience has demonstrated that a more explicit - distinction is required between creating a fast-but-uninitialized `Buffer` - versus creating a slower-but-safer `Buffer`. Starting in Node.js 8.0.0, - `Buffer(num)` and `new Buffer(num)` will return a `Buffer` with initialized - memory. + entire `Buffer`. While this behavior is *intentional* to improve performance, + development experience has demonstrated that a more explicit distinction is + required between creating a fast-but-uninitialized `Buffer` versus creating a + slower-but-safer `Buffer`. Starting in Node.js 8.0.0, `Buffer(num)` and + `new Buffer(num)` will return a `Buffer` with initialized memory. * Passing a string, array, or `Buffer` as the first argument copies the passed object's data into the `Buffer`. * Passing an [`ArrayBuffer`] or a [`SharedArrayBuffer`] returns a `Buffer` that shares allocated memory with the given array buffer. Because the behavior of `new Buffer()` is different depending on the type of the -first argument, security and reliability issues can be inadvertantly introduced -into applications when argument validation or `Buffer` initialization are not +first argument, security and reliability issues can be inadvertently introduced +into applications when argument validation or `Buffer` initialization is not performed. -To make the creation of `Buffer` instances more reliable and less error prone, +To make the creation of `Buffer` instances more reliable and less error-prone, the various forms of the `new Buffer()` constructor have been **deprecated** and replaced by separate `Buffer.from()`, [`Buffer.alloc()`], and [`Buffer.allocUnsafe()`] methods. @@ -81,24 +80,25 @@ and replaced by separate `Buffer.from()`, [`Buffer.alloc()`], and *Developers should migrate all existing uses of the `new Buffer()` constructors to one of these new APIs.* -* [`Buffer.from(array)`] returns a new `Buffer` containing a *copy* of the provided - octets. +* [`Buffer.from(array)`] returns a new `Buffer` that *contains a copy* of the + provided octets. * [`Buffer.from(arrayBuffer[, byteOffset [, length]])`][`Buffer.from(arrayBuffer)`] - returns a new `Buffer` that *shares* the same allocated memory as the given + returns a new `Buffer` that *shares the same allocated memory* as the given [`ArrayBuffer`]. -* [`Buffer.from(buffer)`] returns a new `Buffer` containing a *copy* of the +* [`Buffer.from(buffer)`] returns a new `Buffer` that *contains a copy* of the contents of the given `Buffer`. -* [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] returns a new `Buffer` - containing a *copy* of the provided string. -* [`Buffer.alloc(size[, fill[, encoding]])`][`Buffer.alloc()`] returns a "filled" - `Buffer` instance of the specified size. This method can be significantly - slower than [`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] but ensures - that newly created `Buffer` instances never contain old and potentially - sensitive data. +* [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] returns a new + `Buffer` that *contains a copy* of the provided string. +* [`Buffer.alloc(size[, fill[, encoding]])`][`Buffer.alloc()`] returns a new + initialized `Buffer` of the specified size. This method is slower than + [`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] but guarantees that newly + created `Buffer` instances never contain old data that is potentially + sensitive. * [`Buffer.allocUnsafe(size)`][`Buffer.allocUnsafe()`] and [`Buffer.allocUnsafeSlow(size)`][`Buffer.allocUnsafeSlow()`] each return a - new `Buffer` of the specified `size` whose content *must* be initialized - using either [`buf.fill(0)`][`buf.fill()`] or written to completely. + new uninitialized `Buffer` of the specified `size`. Because the `Buffer` is + uninitialized, the allocated segment of memory might contain old data that is + potentially sensitive. `Buffer` instances returned by [`Buffer.allocUnsafe()`] *may* be allocated off a shared internal memory pool if `size` is less than or equal to half @@ -117,7 +117,7 @@ force all newly allocated `Buffer` instances created using either this flag *changes the default behavior* of these methods and *can have a significant impact* on performance. Use of the `--zero-fill-buffers` option is recommended only when necessary to enforce that newly allocated `Buffer` instances cannot -contain potentially sensitive data. +contain old data that is potentially sensitive. Example: