Commit b934058
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: #11025
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>1 parent faa55fb commit b934058
1 file changed
Lines changed: 26 additions & 14 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -112,12 +112,13 @@ added: v0.1.99 | |||
| 112 | 112 | * `callback` {Function} with no parameters, Optional. Called when | |
| 113 | 113 | binding is complete. | |
| 114 | 114 | ||
| 115 | - For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a | ||
| 116 | - named `port` and optional `address`. If `port` is not specified, the operating | ||
| 117 | - system will attempt to bind to a random port. If `address` is not specified, | ||
| 118 | - the operating system will attempt to listen on all addresses. Once binding is | ||
| 119 | - complete, a `'listening'` event is emitted and the optional `callback` function | ||
| 120 | - is called. | ||
| 115 | + For UDP sockets, causes the `dgram.Socket` to listen for datagram | ||
| 116 | + messages on a named `port` and optional `address`. If `port` is not | ||
| 117 | + specified or is `0`, the operating system will attempt to bind to a | ||
| 118 | + random port. If `address` is not specified, the operating system will | ||
| 119 | + attempt to listen on all addresses. Once binding is complete, a | ||
| 120 | + `'listening'` event is emitted and the optional `callback` function is | ||
| 121 | + called. | ||
| 121 | 122 | ||
| 122 | 123 | Note that specifying both a `'listening'` event listener and passing a | |
| 123 | 124 | `callback` to the `socket.bind()` method is not harmful but not very | |
@@ -159,18 +160,23 @@ added: v0.11.14 | |||
| 159 | 160 | --> | |
| 160 | 161 | ||
| 161 | 162 | * `options` {Object} - Required. Supports the following properties: | |
| 162 | - * `port` {Number} - Required. | ||
| 163 | + * `port` {Number} - Optional. | ||
| 163 | 164 | * `address` {String} - Optional. | |
| 164 | 165 | * `exclusive` {Boolean} - Optional. | |
| 165 | 166 | * `callback` {Function} - Optional. | |
| 166 | 167 | ||
| 167 | - For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a | ||
| 168 | - named `port` and optional `address` that are passed as properties of an | ||
| 169 | - `options` object passed as the first argument. If `port` is not specified, the | ||
| 170 | - operating system will attempt to bind to a random port. If `address` is not | ||
| 171 | - specified, the operating system will attempt to listen on all addresses. Once | ||
| 172 | - binding is complete, a `'listening'` event is emitted and the optional | ||
| 173 | - `callback` function is called. | ||
| 168 | + For UDP sockets, causes the `dgram.Socket` to listen for datagram | ||
| 169 | + messages on a named `port` and optional `address` that are passed as | ||
| 170 | + properties of an `options` object passed as the first argument. If | ||
| 171 | + `port` is not specified or is `0`, the operating system will attempt | ||
| 172 | + to bind to a random port. If `address` is not specified, the operating | ||
| 173 | + system will attempt to listen on all addresses. Once binding is | ||
| 174 | + complete, a `'listening'` event is emitted and the optional `callback` | ||
| 175 | + function is called. | ||
| 176 | + | ||
| 177 | + Note that specifying both a `'listening'` event listener and passing a | ||
| 178 | + `callback` to the `socket.bind()` method is not harmful but not very | ||
| 179 | + useful. | ||
| 174 | 180 | ||
| 175 | 181 | The `options` object may contain an additional `exclusive` property that is | |
| 176 | 182 | 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. | |||
| 179 | 185 | When `exclusive` is `true`, however, the handle is not shared and attempted | |
| 180 | 186 | port sharing results in an error. | |
| 181 | 187 | ||
| 188 | + A bound datagram socket keeps the Node.js process running to receive | ||
| 189 | + datagram messages. | ||
| 190 | + | ||
| 191 | + If binding fails, an `'error'` event is generated. In rare case (e.g. | ||
| 192 | + attempting to bind with a closed socket), an [`Error`][] may be thrown. | ||
| 193 | + | ||
| 182 | 194 | An example socket listening on an exclusive port is shown below. | |
| 183 | 195 | ||
| 184 | 196 | ```js | |
0 commit comments