From cfc4c622491268c43a3d60ec1971adc23409f756 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Thu, 26 Jan 2017 16:17:05 -0500 Subject: [PATCH] doc: correct and complete dgram's Socket.bind docs `port` was listed as required, but as described in the following paragraphs, it's actually not. Also, note that setting `port` to `0` will also cause the OS to assign a a random port and sync up the docs of both forms. PR-URL: https://github.com/nodejs/node/pull/11025 Reviewed-By: Sam Roberts Reviewed-By: James M Snell --- doc/api/dgram.md | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/doc/api/dgram.md b/doc/api/dgram.md index c059b6dc2ba4ff..65a89913ba1bdf 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -112,12 +112,13 @@ added: v0.1.99 * `callback` {Function} with no parameters, Optional. Called when binding is complete. -For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a -named `port` and optional `address`. If `port` is not specified, the operating -system will attempt to bind to a random port. If `address` is not specified, -the operating system will attempt to listen on all addresses. Once binding is -complete, a `'listening'` event is emitted and the optional `callback` function -is called. +For UDP sockets, causes the `dgram.Socket` to listen for datagram +messages on a named `port` and optional `address`. If `port` is not +specified or is `0`, the operating system will attempt to bind to a +random port. If `address` is not specified, the operating system will +attempt to listen on all addresses. Once binding is complete, a +`'listening'` event is emitted and the optional `callback` function is +called. Note that specifying both a `'listening'` event listener and passing a `callback` to the `socket.bind()` method is not harmful but not very @@ -159,18 +160,23 @@ added: v0.11.14 --> * `options` {Object} - Required. Supports the following properties: - * `port` {Number} - Required. + * `port` {Number} - Optional. * `address` {String} - Optional. * `exclusive` {Boolean} - Optional. * `callback` {Function} - Optional. -For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a -named `port` and optional `address` that are passed as properties of an -`options` object passed as the first argument. If `port` is not specified, the -operating system will attempt to bind to a random port. If `address` is not -specified, the operating system will attempt to listen on all addresses. Once -binding is complete, a `'listening'` event is emitted and the optional -`callback` function is called. +For UDP sockets, causes the `dgram.Socket` to listen for datagram +messages on a named `port` and optional `address` that are passed as +properties of an `options` object passed as the first argument. If +`port` is not specified or is `0`, the operating system will attempt +to bind to a random port. If `address` is not specified, the operating +system will attempt to listen on all addresses. Once binding is +complete, a `'listening'` event is emitted and the optional `callback` +function is called. + +Note that specifying both a `'listening'` event listener and passing a +`callback` to the `socket.bind()` method is not harmful but not very +useful. The `options` object may contain an additional `exclusive` property that is use when using `dgram.Socket` objects with the [`cluster`] module. When @@ -179,6 +185,12 @@ underlying socket handle allowing connection handling duties to be shared. When `exclusive` is `true`, however, the handle is not shared and attempted port sharing results in an error. +A bound datagram socket keeps the Node.js process running to receive +datagram messages. + +If binding fails, an `'error'` event is generated. In rare case (e.g. +attempting to bind with a closed socket), an [`Error`][] may be thrown. + An example socket listening on an exclusive port is shown below. ```js