升级到 v8.4.0

README.md

@@ -1,4 +1,4 @@
 # node-api-cn
-Node.js API 中文文档 v8.3.0
+Node.js API 中文文档 v8.4.0
 
 http://nodejs.cn/api/

addons/void_atexit_callback_args.md

@@ -12,7 +12,6 @@ AtExit 有两个参数：一个退出时运行的回调函数的指针，和一
 
 ```cpp
 // addon.cc
-#undef NDEBUG
 #include <assert.h>
 #include <stdlib.h>
 #include <node.h>
@@ -49,10 +48,10 @@ static void sanity_check(void*) {
 }
 
 void init(Local<Object> exports) {
-  AtExit(sanity_check);
   AtExit(at_exit_cb2, cookie);
   AtExit(at_exit_cb2, cookie);
   AtExit(at_exit_cb1, exports->GetIsolate());
+  AtExit(sanity_check);
 }
 
 NODE_MODULE(addon, init)
@@ -64,6 +63,6 @@ NODE_MODULE(addon, init)
 
 ```js
 // test.js
-const addon = require('./build/Release/addon');
+require('./build/Release/addon');
 ```
 

buffer/buf_slice_start_end.md

@@ -18,6 +18,9 @@ changes:
 
 返回一个指向相同原始内存的新建的 `Buffer`，但做了偏移且通过 `start` 和 `end` 索引进行裁剪。
 
+Specifying `end` greater than [`buf.length`] will return the same result as
+that of `end` equal to [`buf.length`].
+
 **注意，修改这个新建的 `Buffer` 切片，也会同时修改原始的 `Buffer` 的内存，因为这两个对象所分配的内存是重叠的。**
 
 例子：创建一个包含 ASCII 字母表的 `Buffer`，并进行切片，然后修改原始 `Buffer` 上的一个字节。

cli/expose_http2.md

@@ -0,0 +1,6 @@
+<!-- YAML
+added: v8.4.0
+-->
+
+Enable the experimental `'http2'` module.
+

cli/node_options_options.md

@@ -2,10 +2,10 @@
 added: v8.0.0
 -->
 
-`options...` are interpreted as if they had been specified on the command line
-before the actual command line (so they can be overridden).  Node will exit with
-an error if an option that is not allowed in the environment is used, such as
-`-p` or a script file.
+A space-separated list of command line options. `options...` are interpreted as
+if they had been specified on the command line before the actual command line
+(so they can be overridden).  Node will exit with an error if an option that is
+not allowed in the environment is used, such as `-p` or a script file.
 
 Node options that are allowed are:
 - `--enable-fips`

errors/class_assertionerror.md

@@ -0,0 +1,11 @@
+
+A subclass of `Error` that indicates the failure of an assertion. Such errors
+commonly indicate inequality of actual and expected value.
+
+For example:
+
+```js
+assert.strictEqual(1, 2);
+// AssertionError [ERR_ASSERTION]: 1 === 2
+```
+

errors/err_falsy_value_rejection.md

@@ -2,4 +2,4 @@
 Used by the `util.callbackify()` API when a callbackified `Promise` is rejected
 with a falsy value (e.g. `null`).
 
-<a id="ERR_INVALID_ARG_TYPE"></a>
+<a id="ERR_HTTP_HEADERS_SENT"></a>

errors/err_http2_connect_authority.md

@@ -0,0 +1,5 @@
+
+For HTTP/2 requests using the `CONNECT` method, the `:authority` pseudo-header
+is required.
+
+<a id="ERR_HTTP2_CONNECT_PATH"></a>

errors/err_http2_connect_path.md

@@ -0,0 +1,5 @@
+
+For HTTP/2 requests using the `CONNECT` method, the `:path` pseudo-header is
+forbidden.
+
+<a id="ERR_HTTP2_CONNECT_SCHEME"></a>

errors/err_http2_connect_scheme.md

@@ -0,0 +1,5 @@
+
+The HTTP/2 requests using the `CONNECT` method, the `:scheme` pseudo-header is
+forbidden.
+
+<a id="ERR_HTTP2_ERROR"></a>

errors/err_http2_error.md

@@ -0,0 +1,4 @@
+
+A non-specific HTTP/2 error has occurred.
+
+<a id="ERR_HTTP2_FRAME_ERROR"></a>

errors/err_http2_frame_error.md

@@ -0,0 +1,5 @@
+
+Used when a failure occurs sending an individual frame on the HTTP/2
+session.
+
+<a id="ERR_HTTP2_HEADERS_OBJECT"></a>

errors/err_http2_header_single_value.md

@@ -0,0 +1,5 @@
+
+Used when multiple values have been provided for an HTTP header field that
+required to have only a single value.
+
+<a id="ERR_HTTP2_INFO_HEADERS_AFTER_RESPOND"></a>

errors/err_http2_headers_object.md

@@ -0,0 +1,4 @@
+
+Used when an HTTP/2 Headers Object is expected.
+
+<a id="ERR_HTTP2_HEADERS_SENT"></a>

errors/err_http2_headers_sent.md

@@ -0,0 +1,4 @@
+
+Used when an attempt is made to send multiple response headers.
+
+<a id="ERR_HTTP2_HEADER_SINGLE_VALUE"></a>

errors/err_http2_info_headers_after_respond.md

@@ -0,0 +1,5 @@
+
+HTTP/2 Informational headers must only be sent *prior* to calling the
+`Http2Stream.prototype.respond()` method.
+
+<a id="ERR_HTTP2_INFO_STATUS_NOT_ALLOWED"></a>

errors/err_http2_info_status_not_allowed.md

@@ -0,0 +1,5 @@
+
+Informational HTTP status codes (`1xx`) may not be set as the response status
+code on HTTP/2 responses.
+
+<a id="ERR_HTTP2_INVALID_CONNECTION_HEADERS"></a>

errors/err_http2_invalid_connection_headers.md

@@ -0,0 +1,5 @@
+
+HTTP/1 connection specific headers are forbidden to be used in HTTP/2
+requests and responses.
+
+<a id="ERR_HTTP2_INVALID_HEADER_VALUE"></a>

errors/err_http2_invalid_header_value.md

@@ -0,0 +1,4 @@
+
+Used to indicate that an invalid HTTP/2 header value has been specified.
+
+<a id="ERR_HTTP2_INVALID_INFO_STATUS"></a>

errors/err_http2_invalid_info_status.md

@@ -0,0 +1,11 @@
+
+An invalid HTTP informational status code has been specified. Informational
+status codes must be an integer between `100` and `199` (inclusive).
+
+<a id="ERR_HTTP2_INVALID_PACKED_SETTINGS_LENGTH"></a>
+
+Input `Buffer` and `Uint8Array` instances passed to the
+`http2.getUnpackedSettings()` API must have a length that is a multiple of
+six.
+
+<a id="ERR_HTTP2_INVALID_PSEUDOHEADER"></a>

errors/err_http2_invalid_pseudoheader.md

@@ -0,0 +1,5 @@
+
+Only valid HTTP/2 pseudoheaders (`:status`, `:path`, `:authority`, `:scheme`,
+and `:method`) may be used.
+
+<a id="ERR_HTTP2_INVALID_SESSION"></a>

errors/err_http2_invalid_session.md

@@ -0,0 +1,5 @@
+
+Used when any action is performed on an `Http2Session` object that has already
+been destroyed.
+
+<a id="ERR_HTTP2_INVALID_SETTING_VALUE"></a>

errors/err_http2_invalid_setting_value.md

@@ -0,0 +1,4 @@
+
+An invalid value has been specified for an HTTP/2 setting.
+
+<a id="ERR_HTTP2_INVALID_STREAM"></a>

errors/err_http2_invalid_stream.md

@@ -0,0 +1,5 @@
+
+Used when an operation has been performed on a stream that has already been
+destroyed.
+
+<a id="ERR_HTTP2_MAX_PENDING_SETTINGS_ACK"></a>

errors/err_http2_max_pending_settings_ack.md

@@ -0,0 +1,8 @@
+
+Whenever an HTTP/2 `SETTINGS` frame is sent to a connected peer, the peer is
+required to send an acknowledgement that it has received and applied the new
+SETTINGS. By default, a maximum number of un-acknowledged `SETTINGS` frame may
+be sent at any given time. This error code is used when that limit has been
+reached.
+
+<a id="ERR_HTTP2_OUT_OF_STREAMS"></a>

errors/err_http2_out_of_streams.md

@@ -0,0 +1,5 @@
+
+Used when the maximum number of streams on a single HTTP/2 session have been
+created.
+
+<a id="ERR_HTTP2_PAYLOAD_FORBIDDEN"></a>

errors/err_http2_payload_forbidden.md

@@ -0,0 +1,5 @@
+
+Used when a message payload is specified for an HTTP response code for which
+a payload is forbidden.
+
+<a id="ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED"></a>

errors/err_http2_pseudoheader_not_allowed.md

@@ -0,0 +1,5 @@
+
+Used to indicate that an HTTP/2 pseudo-header has been used inappropriately.
+Pseudo-headers are header key names that begin with the `:` prefix.
+
+<a id="ERR_HTTP2_PUSH_DISABLED"></a>

errors/err_http2_push_disabled.md

@@ -0,0 +1,5 @@
+
+Used when push streams have been disabled by the client but an attempt to
+create a push stream is made.
+
+<a id="ERR_HTTP2_SEND_FILE"></a>

errors/err_http2_send_file.md

@@ -0,0 +1,5 @@
+
+Used when an attempt is made to use the
+`Http2Stream.prototype.responseWithFile()` API to send a non-regular file.
+
+<a id="ERR_HTTP2_SOCKET_BOUND"></a>

errors/err_http2_socket_bound.md

@@ -0,0 +1,6 @@
+
+Used when an attempt is made to connect a `Http2Session` object to a
+`net.Socket` or `tls.TLSSocket` that has already been bound to another
+`Http2Session` object.
+
+<a id="ERR_HTTP2_STATUS_101"></a>

errors/err_http2_status_101.md

@@ -0,0 +1,4 @@
+
+Use of the `101` Informational status code is forbidden in HTTP/2.
+
+<a id="ERR_HTTP2_STATUS_INVALID"></a>

errors/err_http2_status_invalid.md

@@ -0,0 +1,5 @@
+
+An invalid HTTP status code has been specified. Status codes must be an integer
+between `100` and `599` (inclusive).
+
+<a id="ERR_HTTP2_STREAM_CLOSED"></a>

errors/err_http2_stream_closed.md

@@ -0,0 +1,5 @@
+
+Used when an action has been performed on an HTTP/2 Stream that has already
+been closed.
+
+<a id="ERR_HTTP2_STREAM_ERROR"></a>

errors/err_http2_stream_error.md

@@ -0,0 +1,4 @@
+
+Used when a non-zero error code has been specified in an `RST_STREAM` frame.
+
+<a id="ERR_HTTP2_STREAM_SELF_DEPENDENCY"></a>

errors/err_http2_stream_self_dependency.md

@@ -0,0 +1,6 @@
+
+When setting the priority for an HTTP/2 stream, the stream may be marked as
+a dependency for a parent stream. This error code is used when an attempt is
+made to mark a stream and dependent of itself.
+
+<a id="ERR_HTTP2_UNSUPPORTED_PROTOCOL"></a>

errors/err_http2_unsupported_protocol.md

@@ -0,0 +1,5 @@
+
+Used when `http2.connect()` is passed a URL that uses any protocol other than
+`http:` or `https:`.
+
+<a id="ERR_INDEX_OUT_OF_RANGE"></a>

errors/err_http_headers_sent.md

@@ -0,0 +1,5 @@
+
+Used when headers have already been sent and another attempt is made to add
+more headers.
+
+<a id="ERR_HTTP_INVALID_STATUS_CODE"></a>

errors/err_http_invalid_status_code.md

@@ -0,0 +1,4 @@
+
+Used for status codes outside the regular status code ranges (100-999).
+
+<a id="ERR_HTTP_TRAILER_INVALID"></a>

errors/err_http_trailer_invalid.md

@@ -0,0 +1,5 @@
+
+Used when the `Trailer` header is set even though the transfer encoding does not
+support that.
+
+<a id="ERR_HTTP2_CONNECT_AUTHORITY"></a>

errors/err_index_out_of_range.md

@@ -0,0 +1,4 @@
+
+Used when a given index is out of the accepted range (e.g. negative offsets).
+
+<a id="ERR_INVALID_ARG_TYPE"></a>

errors/err_missing_args.md

@@ -5,4 +5,4 @@ only used in the [WHATWG URL API][] for strict compliance with the specification
 native Node.js APIs, `func(undefined)` and `func()` are treated identically, and
 the [`ERR_INVALID_ARG_TYPE`][] error code may be used instead.
 
-<a id="ERR_SOCKET_ALREADY_BOUND"></a>
+<a id="ERR_NO_ICU"></a>

errors/err_no_icu.md

@@ -0,0 +1,5 @@
+
+Used when an attempt is made to use features that require [ICU][], while
+Node.js is not compiled with ICU support.
+
+<a id="ERR_SOCKET_ALREADY_BOUND"></a>

fs/fs_read_fd_buffer_offset_length_position_callback.md

@@ -24,8 +24,9 @@ changes:
 
 `length` 是一个整数，指定要读取的字节数。
 
-`position` 是一个整数，指定从文件中开始读取的位置。
-如果 `position` 为 `null`，则数据从当前文件位置开始读取。
+`position` 指定从文件中开始读取的位置。
+如果 `position` 为 `null`，则数据从当前文件读取位置开始读取，且文件读取位置会被更新。
+如果 `position` 为一个整数，则文件读取位置保持不变。
 
 回调有三个参数 `(err, bytesRead, buffer)`。
 

http2/alpn_negotiation.md

@@ -0,0 +1,36 @@
+
+ALPN negotiation allows to support both [HTTPS][] and HTTP/2 over
+the same socket. The `req` and `res` objects can be either HTTP/1 or
+HTTP/2, and an application **must** restrict itself to the public API of
+[HTTP/1][], and detect if it is possible to use the more advanced
+features of HTTP/2.
+
+The following example creates a server that supports both protocols:
+
+```js
+const { createSecureServer } = require('http2');
+const { readFileSync } = require('fs');
+
+const cert = fs.readFileSync('./cert.pem');
+const key = fs.readFileSync('./key.pem');
+
+const server = createSecureServer(
+  { cert, key, allowHTTP1: true },
+  onRequest
+).listen(4443);
+
+function onRequest(req, res) {
+  // detects if it is a HTTPS request or HTTP/2
+  const { socket: { alpnProtocol } } = request.httpVersion === '2.0' ?
+    request.stream.session : request;
+  response.writeHead(200, { 'content-type': 'application/json' });
+  response.end(JSON.stringify({
+    alpnProtocol,
+    httpVersion: request.httpVersion
+  }));
+}
+```
+
+The `'request'` event works identically on both [HTTPS](https) and
+HTTP/2.
+

http2/class_clienthttp2stream.md

@@ -0,0 +1,11 @@
+<!-- YAML
+added: v8.4.0
+-->
+
+* Extends {Http2Stream}
+
+The `ClientHttp2Stream` class is an extension of `Http2Stream` that is
+used exclusively on HTTP/2 Clients. `Http2Stream` instances on the client
+provide events such as `'response'` and `'push'` that are only relevant on
+the client.
+

http2/class_http2_http2serverrequest.md

@@ -0,0 +1,12 @@
+<!-- YAML
+added: v8.4.0
+-->
+
+A `Http2ServerRequest` object is created by [`http2.Server`][] or
+[`http2.SecureServer`][] and passed as the first argument to the
+[`'request'`][] event. It may be used to access a request status, headers and
+data.
+
+It implements the [Readable Stream][] interface, as well as the
+following additional events, methods, and properties.
+

http2/class_http2_http2serverresponse.md

@@ -0,0 +1,10 @@
+<!-- YAML
+added: v8.4.0
+-->
+
+This object is created internally by an HTTP server--not by the user. It is
+passed as the second parameter to the [`'request'`][] event.
+
+The response implements, but does not inherit from, the [Writable Stream][]
+interface. This is an [`EventEmitter`][] with the following events:
+

http2/class_http2secureserver.md

@@ -0,0 +1,6 @@
+<!-- YAML
+added: v8.4.0
+-->
+
+* Extends: {tls.Server}
+