Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: mention errors thrown by methods called on an unbound dgram.Socket #33983

Closed
wants to merge 3 commits into from
Closed

doc: mention errors thrown by methods called on an unbound dgram.Socket #33983

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
935eb1b
doc: mention errors thrown by methods called on an unbound dgram.Socket
mkrawczuk Jun 19, 2020
23ad265
fixup! add subject to sentences.
mkrawczuk Jun 20, 2020
9199da6
fixup! It -> this method.
mkrawczuk Jun 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 35 additions & 4 deletions doc/api/dgram.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,9 @@ Tells the kernel to join a multicast group at the given `multicastAddress` and
one interface and will add membership to it. To add membership to every
available interface, call `addMembership` multiple times, once per interface.

When called on an unbound socket, this method will implicitly bind to a random
port, listening on all interfaces.

When sharing a UDP socket across multiple `cluster` workers, the
`socket.addMembership()` function must be called only once or an
`EADDRINUSE` error will occur:
Expand Down Expand Up @@ -143,6 +146,9 @@ is not specified, the operating system will choose one interface and will add
membership to it. To add membership to every available interface, call
`socket.addSourceSpecificMembership()` multiple times, once per interface.

When called on an unbound socket, this method will implicitly bind to a random
port, listening on all interfaces.

### `socket.address()`
<!-- YAML
added: v0.1.99
Expand All @@ -154,6 +160,8 @@ Returns an object containing the address information for a socket.
For UDP sockets, this object will contain `address`, `family` and `port`
properties.

This method throws `EBADF` if called on an unbound socket.
mkrawczuk marked this conversation as resolved.
Show resolved Hide resolved

### `socket.bind([port][, address][, callback])`
<!-- YAML
added: v0.1.99
Expand Down Expand Up @@ -298,8 +306,9 @@ added: v12.0.0
-->

A synchronous function that disassociates a connected `dgram.Socket` from
its remote address. Trying to call `disconnect()` on an already disconnected
socket will result in an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception.
its remote address. Trying to call `disconnect()` on an unbound or already
disconnected socket will result in an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][]
exception.

### `socket.dropMembership(multicastAddress[, multicastInterface])`
<!-- YAML
Expand Down Expand Up @@ -344,13 +353,17 @@ added: v8.7.0

* Returns: {number} the `SO_RCVBUF` socket receive buffer size in bytes.

This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.

### `socket.getSendBufferSize()`
<!-- YAML
added: v8.7.0
-->

* Returns: {number} the `SO_SNDBUF` socket send buffer size in bytes.

This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.

### `socket.ref()`
<!-- YAML
added: v0.9.1
Expand All @@ -377,8 +390,8 @@ added: v12.0.0
* Returns: {Object}

Returns an object containing the `address`, `family`, and `port` of the remote
endpoint. It throws an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception if the
socket is not connected.
endpoint. This method throws an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception
if the socket is not connected.

### `socket.send(msg[, offset, length][, port][, address][, callback])`
<!-- YAML
Expand Down Expand Up @@ -452,6 +465,8 @@ Offset and length are optional but both *must* be set if either are used.
They are supported only when the first argument is a `Buffer`, a `TypedArray`,
or a `DataView`.

This method throws [`ERR_SOCKET_BAD_PORT`][] if called on an unbound socket.

Example of sending a UDP packet to a port on `localhost`;

```js
Expand Down Expand Up @@ -532,6 +547,8 @@ added: v0.6.9
Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP
packets may be sent to a local interface's broadcast address.

This method throws `EBADF` if called on an unbound socket.

### `socket.setMulticastInterface(multicastInterface)`
<!-- YAML
added: v8.6.0
Expand All @@ -558,6 +575,8 @@ also use explicit scope in addresses, so only packets sent to a multicast
address without specifying an explicit scope are affected by the most recent
successful use of this call.

This method throws `EBADF` if called on an unbound socket.

#### Example: IPv6 outgoing multicast interface

On most systems, where scope format uses the interface name:
Expand Down Expand Up @@ -620,6 +639,8 @@ added: v0.3.8
Sets or clears the `IP_MULTICAST_LOOP` socket option. When set to `true`,
multicast packets will also be received on the local interface.

This method throws `EBADF` if called on an unbound socket.

### `socket.setMulticastTTL(ttl)`
<!-- YAML
added: v0.3.8
Expand All @@ -635,6 +656,8 @@ decremented to 0 by a router, it will not be forwarded.

The `ttl` argument may be between 0 and 255. The default on most systems is `1`.

This method throws `EBADF` if called on an unbound socket.

### `socket.setRecvBufferSize(size)`
<!-- YAML
added: v8.7.0
Expand All @@ -645,6 +668,8 @@ added: v8.7.0
Sets the `SO_RCVBUF` socket option. Sets the maximum socket receive buffer
in bytes.

This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.

### `socket.setSendBufferSize(size)`
<!-- YAML
added: v8.7.0
Expand All @@ -655,6 +680,8 @@ added: v8.7.0
Sets the `SO_SNDBUF` socket option. Sets the maximum socket send buffer
in bytes.

This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.

### `socket.setTTL(ttl)`
<!-- YAML
added: v0.1.101
Expand All @@ -671,6 +698,8 @@ Changing TTL values is typically done for network probes or when multicasting.
The `ttl` argument may be between between 1 and 255. The default on most systems
is 64.

This method throws `EBADF` if called on an unbound socket.

### `socket.unref()`
<!-- YAML
added: v0.9.1
Expand Down Expand Up @@ -749,6 +778,8 @@ and `udp6` sockets). The bound address and port can be retrieved using
[`socket.address().address`][] and [`socket.address().port`][].

[`'close'`]: #dgram_event_close
[`ERR_SOCKET_BAD_PORT`]: errors.html#errors_err_socket_bad_port
[`ERR_SOCKET_BUFFER_SIZE`]: errors.html#errors_err_socket_buffer_size
[`ERR_SOCKET_DGRAM_IS_CONNECTED`]: errors.html#errors_err_socket_dgram_is_connected
[`ERR_SOCKET_DGRAM_NOT_CONNECTED`]: errors.html#errors_err_socket_dgram_not_connected
[`Error`]: errors.html#errors_class_error
Expand Down