diff options
author | Mateusz Krawczuk <krawczukmat@gmail.com> | 2020-06-20 02:52:55 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2020-06-24 03:04:26 +0300 |
commit | 91d9cdfffc61be3c537d220f6b58e7087873a964 (patch) | |
tree | 1a3e025fdf63a62448ed44f25457a64d7bfe7a74 /doc/api/dgram.md | |
parent | af83dcd5f46ecc6c3662cd0c18100a61118ca5e7 (diff) |
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>
Diffstat (limited to 'doc/api/dgram.md')
-rw-r--r-- | doc/api/dgram.md | 39 |
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 |