Skip to content

Commit 2ca6a45

Browse files
mkrawczukMylesBorins
authored andcommitted
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]>
1 parent b8a17cc commit 2ca6a45

File tree

1 file changed

+35
-4
lines changed

1 file changed

+35
-4
lines changed

doc/api/dgram.md

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,9 @@ Tells the kernel to join a multicast group at the given `multicastAddress` and
108108
one interface and will add membership to it. To add membership to every
109109
available interface, call `addMembership` multiple times, once per interface.
110110

111+
When called on an unbound socket, this method will implicitly bind to a random
112+
port, listening on all interfaces.
113+
111114
When sharing a UDP socket across multiple `cluster` workers, the
112115
`socket.addMembership()` function must be called only once or an
113116
`EADDRINUSE` error will occur:
@@ -143,6 +146,9 @@ is not specified, the operating system will choose one interface and will add
143146
membership to it. To add membership to every available interface, call
144147
`socket.addSourceSpecificMembership()` multiple times, once per interface.
145148

149+
When called on an unbound socket, this method will implicitly bind to a random
150+
port, listening on all interfaces.
151+
146152
### `socket.address()`
147153
<!-- YAML
148154
added: v0.1.99
@@ -154,6 +160,8 @@ Returns an object containing the address information for a socket.
154160
For UDP sockets, this object will contain `address`, `family` and `port`
155161
properties.
156162

163+
This method throws `EBADF` if called on an unbound socket.
164+
157165
### `socket.bind([port][, address][, callback])`
158166
<!-- YAML
159167
added: v0.1.99
@@ -298,8 +306,9 @@ added: v12.0.0
298306
-->
299307

300308
A synchronous function that disassociates a connected `dgram.Socket` from
301-
its remote address. Trying to call `disconnect()` on an already disconnected
302-
socket will result in an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception.
309+
its remote address. Trying to call `disconnect()` on an unbound or already
310+
disconnected socket will result in an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][]
311+
exception.
303312

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

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

356+
This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.
357+
347358
### `socket.getSendBufferSize()`
348359
<!-- YAML
349360
added: v8.7.0
350361
-->
351362

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

365+
This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.
366+
354367
### `socket.ref()`
355368
<!-- YAML
356369
added: v0.9.1
@@ -377,8 +390,8 @@ added: v12.0.0
377390
* Returns: {Object}
378391

379392
Returns an object containing the `address`, `family`, and `port` of the remote
380-
endpoint. It throws an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception if the
381-
socket is not connected.
393+
endpoint. This method throws an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception
394+
if the socket is not connected.
382395

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

468+
This method throws [`ERR_SOCKET_BAD_PORT`][] if called on an unbound socket.
469+
455470
Example of sending a UDP packet to a port on `localhost`;
456471

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

550+
This method throws `EBADF` if called on an unbound socket.
551+
535552
### `socket.setMulticastInterface(multicastInterface)`
536553
<!-- YAML
537554
added: v8.6.0
@@ -558,6 +575,8 @@ also use explicit scope in addresses, so only packets sent to a multicast
558575
address without specifying an explicit scope are affected by the most recent
559576
successful use of this call.
560577

578+
This method throws `EBADF` if called on an unbound socket.
579+
561580
#### Example: IPv6 outgoing multicast interface
562581

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

642+
This method throws `EBADF` if called on an unbound socket.
643+
623644
### `socket.setMulticastTTL(ttl)`
624645
<!-- YAML
625646
added: v0.3.8
@@ -635,6 +656,8 @@ decremented to 0 by a router, it will not be forwarded.
635656

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

659+
This method throws `EBADF` if called on an unbound socket.
660+
638661
### `socket.setRecvBufferSize(size)`
639662
<!-- YAML
640663
added: v8.7.0
@@ -645,6 +668,8 @@ added: v8.7.0
645668
Sets the `SO_RCVBUF` socket option. Sets the maximum socket receive buffer
646669
in bytes.
647670

671+
This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.
672+
648673
### `socket.setSendBufferSize(size)`
649674
<!-- YAML
650675
added: v8.7.0
@@ -655,6 +680,8 @@ added: v8.7.0
655680
Sets the `SO_SNDBUF` socket option. Sets the maximum socket send buffer
656681
in bytes.
657682

683+
This method throws [`ERR_SOCKET_BUFFER_SIZE`][] if called on an unbound socket.
684+
658685
### `socket.setTTL(ttl)`
659686
<!-- YAML
660687
added: v0.1.101
@@ -671,6 +698,8 @@ Changing TTL values is typically done for network probes or when multicasting.
671698
The `ttl` argument may be between between 1 and 255. The default on most systems
672699
is 64.
673700

701+
This method throws `EBADF` if called on an unbound socket.
702+
674703
### `socket.unref()`
675704
<!-- YAML
676705
added: v0.9.1
@@ -749,6 +778,8 @@ and `udp6` sockets). The bound address and port can be retrieved using
749778
[`socket.address().address`][] and [`socket.address().port`][].
750779

751780
[`'close'`]: #dgram_event_close
781+
[`ERR_SOCKET_BAD_PORT`]: errors.html#errors_err_socket_bad_port
782+
[`ERR_SOCKET_BUFFER_SIZE`]: errors.html#errors_err_socket_buffer_size
752783
[`ERR_SOCKET_DGRAM_IS_CONNECTED`]: errors.html#errors_err_socket_dgram_is_connected
753784
[`ERR_SOCKET_DGRAM_NOT_CONNECTED`]: errors.html#errors_err_socket_dgram_not_connected
754785
[`Error`]: errors.html#errors_class_error

0 commit comments

Comments
 (0)