From d74919cc1a47f4f40766ba7f37ab434db246e700 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 23 Mar 2018 15:13:13 -0700 Subject: [PATCH] doc: improve Buffer() text Rewording, punctuation, consistent sentence structure and italics, wrap section at 80 characters. PR-URL: https://github.com/nodejs/node/pull/19567 Reviewed-By: Vse Mozhet Byt Reviewed-By: Trivikram Kamat Reviewed-By: Luigi Pinca Reviewed-By: James M Snell Reviewed-By: Gibson Fahnestock --- 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 2897a32f969baa..bcde11de66314b 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. ```txt $ node --zero-fill-buffers