Skip to content

Commit

Permalink
doc: correct and complete dgram's Socket.bind docs
Browse files Browse the repository at this point in the history
`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>
  • Loading branch information
strugee authored and evanlucas committed Jan 31, 2017
1 parent fe80bd9 commit cfc4c62
Showing 1 changed file with 26 additions and 14 deletions.
40 changes: 26 additions & 14 deletions doc/api/dgram.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit cfc4c62

Please sign in to comment.