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

PR-URL: https://github.com/nodejs/node/pull/33983
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 35 insertions, 4 deletions

diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index 05cab4e9b60..38072d71aa6 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -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:
@@ -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
@@ -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.
+
 ### `socket.bind([port][, address][, callback])`
 <!-- YAML
 added: v0.1.99
@@ -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
@@ -344,6 +353,8 @@ 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
@@ -351,6 +362,8 @@ 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
@@ -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
@@ -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
@@ -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
@@ -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:
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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