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

PR-URL: #33983
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: mkrawczuk

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:
@@ -141,6 +144,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
@@ -152,6 +158,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
@@ -296,8 +304,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
@@ -340,13 +349,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
@@ -373,8 +386,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
@@ -444,6 +457,8 @@ the error is emitted as an `'error'` event on the `socket` object.
 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` or `Uint8Array`.
 
+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
@@ -524,6 +539,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
@@ -550,6 +567,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:
@@ -612,6 +631,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
@@ -627,6 +648,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
@@ -637,6 +660,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
@@ -647,6 +672,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
@@ -663,6 +690,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
@@ -741,6 +770,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