socket.bind() behaviordgram module functionsThedgram module provides an implementation of UDP Datagram sockets.
const dgram = require('dgram');const server = dgram.createSocket('udp4');server.on('error', (err) => { console.log(`server error:\n${err.stack}`); server.close();});server.on('message', (msg, rinfo) => { console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`);});server.on('listening', () => { const address = server.address(); console.log(`server listening ${address.address}:${address.port}`);});server.bind(41234);// server listening 0.0.0.0:41234Thedgram.Socket object is anEventEmitter that encapsulates thedatagram functionality.
New instances ofdgram.Socket are created usingdgram.createSocket().Thenew keyword is not to be used to createdgram.Socket instances.
The'close' event is emitted after a socket is closed withclose().Once triggered, no new'message' events will be emitted on this socket.
exception<Error>The'error' event is emitted whenever any error occurs. The event handlerfunction is passed a single Error object.
The'listening' event is emitted whenever a socket begins listening fordatagram messages. This occurs as soon as UDP sockets are created.
The'message' event is emitted when a new datagram is available on a socket.The event handler function is passed two arguments:msg andrinfo.
Tells the kernel to join a multicast group at the givenmulticastAddress andmulticastInterface using theIP_ADD_MEMBERSHIP socket option. If themulticastInterface argument is not specified, the operating system will chooseone interface and will add membership to it. To add membership to everyavailable interface, calladdMembership multiple times, once per interface.
When sharing a UDP socket across multiplecluster workers, thesocket.addMembership() function must be called only once or anEADDRINUSE error will occur:
const cluster = require('cluster');const dgram = require('dgram');if (cluster.isMaster) { cluster.fork(); // Works ok. cluster.fork(); // Fails with EADDRINUSE.} else { const s = dgram.createSocket('udp4'); s.bind(1234, () => { s.addMembership('224.0.0.114'); });}Returns an object containing the address information for a socket.For UDP sockets, this object will containaddress,family andportproperties.
port<number> Integer.address<string>callback<Function> with no parameters. Called when binding is complete.For UDP sockets, causes thedgram.Socket to listen for datagrammessages on a namedport and optionaladdress. Ifport is notspecified or is0, the operating system will attempt to bind to arandom port. Ifaddress is not specified, the operating system willattempt to listen on all addresses. Once binding is complete, a'listening' event is emitted and the optionalcallback function iscalled.
Note that specifying both a'listening' event listener and passing acallback to thesocket.bind() method is not harmful but not veryuseful.
A bound datagram socket keeps the Node.js process running to receivedatagram messages.
If binding fails, an'error' event is generated. In rare case (e.g.attempting to bind with a closed socket), anError may be thrown.
Example of a UDP server listening on port 41234:
const dgram = require('dgram');const server = dgram.createSocket('udp4');server.on('error', (err) => { console.log(`server error:\n${err.stack}`); server.close();});server.on('message', (msg, rinfo) => { console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`);});server.on('listening', () => { const address = server.address(); console.log(`server listening ${address.address}:${address.port}`);});server.bind(41234);// server listening 0.0.0.0:41234options<Object> Required. Supports the following properties:callback<Function>For UDP sockets, causes thedgram.Socket to listen for datagrammessages on a namedport and optionaladdress that are passed asproperties of anoptions object passed as the first argument. Ifport is not specified or is0, the operating system will attemptto bind to a random port. Ifaddress is not specified, the operatingsystem will attempt to listen on all addresses. Once binding iscomplete, a'listening' event is emitted and the optionalcallbackfunction is called.
Note that specifying both a'listening' event listener and passing acallback to thesocket.bind() method is not harmful but not veryuseful.
Theoptions object may contain an additionalexclusive property that isuse when usingdgram.Socket objects with thecluster module. Whenexclusive is set tofalse (the default), cluster workers will use the sameunderlying socket handle allowing connection handling duties to be shared.Whenexclusive istrue, however, the handle is not shared and attemptedport sharing results in an error.
A bound datagram socket keeps the Node.js process running to receivedatagram messages.
If binding fails, an'error' event is generated. In rare case (e.g.attempting to bind with a closed socket), anError may be thrown.
An example socket listening on an exclusive port is shown below.
socket.bind({ address: 'localhost', port: 8000, exclusive: true});Close the underlying socket and stop listening for data on it. If a callback isprovided, it is added as a listener for the'close' event.
Instructs the kernel to leave a multicast group atmulticastAddress using theIP_DROP_MEMBERSHIP socket option. This method is automatically called by thekernel when the socket is closed or the process terminates, so most apps willnever have reason to call this.
IfmulticastInterface is not specified, the operating system will attempt todrop membership on all valid interfaces.
SO_RCVBUF socket receive buffer size in bytes.SO_SNDBUF socket send buffer size in bytes.By default, binding a socket will cause it to block the Node.js process fromexiting as long as the socket is open. Thesocket.unref() method can be usedto exclude the socket from the reference counting that keeps the Node.jsprocess active. Thesocket.ref() method adds the socket back to the referencecounting and restores the default behavior.
Callingsocket.ref() multiples times will have no additional effect.
Thesocket.ref() method returns a reference to the socket so calls can bechained.
| Version | Changes |
|---|---|
| v8.0.0 | The |
| v8.0.0 | The |
| v6.0.0 | On success, |
| v5.7.0 | The |
| v0.1.99 | Added in: v0.1.99 |
msg<Buffer> |<Uint8Array> |<string> |<Array> Message to be sent.offset<number> Integer. Offset in the buffer where the message starts.length<number> Integer. Number of bytes in the message.port<number> Integer. Destination port.address<string> Destination hostname or IP address.callback<Function> Called when the message has been sent.Broadcasts a datagram on the socket. The destinationport andaddress mustbe specified.
Themsg argument contains the message to be sent.Depending on its type, different behavior can apply. Ifmsg is aBufferorUint8Array,theoffset andlength specify the offset within theBuffer where themessage begins and the number of bytes in the message, respectively.Ifmsg is aString, then it is automatically converted to aBufferwith'utf8' encoding. With messages thatcontain multi-byte characters,offset andlength will be calculated withrespect tobyte length and not the character position.Ifmsg is an array,offset andlength must not be specified.
Theaddress argument is a string. If the value ofaddress is a host name,DNS will be used to resolve the address of the host. Ifaddress is notprovided or otherwise falsy,'127.0.0.1' (forudp4 sockets) or'::1'(forudp6 sockets) will be used by default.
If the socket has not been previously bound with a call tobind, the socketis assigned a random port number and is bound to the "all interfaces" address('0.0.0.0' forudp4 sockets,'::0' forudp6 sockets.)
An optionalcallback function may be specified to as a way of reportingDNS errors or for determining when it is safe to reuse thebuf object.Note that DNS lookups delay the time to send for at least one tick of theNode.js event loop.
The only way to know for sure that the datagram has been sent is by using acallback. If an error occurs and acallback is given, the error will bepassed as the first argument to thecallback. If acallback is not given,the error is emitted as an'error' event on thesocket object.
Offset and length are optional but bothmust be set if either are used.They are supported only when the first argument is aBuffer orUint8Array.
Example of sending a UDP packet to a port onlocalhost;
const dgram = require('dgram');const message = Buffer.from('Some bytes');const client = dgram.createSocket('udp4');client.send(message, 41234, 'localhost', (err) => { client.close();});Example of sending a UDP packet composed of multiple buffers to a port on127.0.0.1;
const dgram = require('dgram');const buf1 = Buffer.from('Some ');const buf2 = Buffer.from('bytes');const client = dgram.createSocket('udp4');client.send([buf1, buf2], 41234, (err) => { client.close();});Sending multiple buffers might be faster or slower depending on theapplication and operating system. It is important to run benchmarks todetermine the optimal strategy on a case-by-case basis. Generally speaking,however, sending multiple buffers is faster.
A Note about UDP datagram size
The maximum size of anIPv4/v6 datagram depends on theMTU(Maximum Transmission Unit) and on thePayload Length field size.
ThePayload Length field is16 bits wide, which means that a normalpayload exceed 64K octetsincluding the internet header and data(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);this is generally true for loopback interfaces, but such long datagrammessages are impractical for most hosts and networks.
TheMTU is the largest size a given link layer technology can support fordatagram messages. For any link,IPv4 mandates a minimumMTU of68octets, while the recommendedMTU for IPv4 is576 (typically recommendedas theMTU for dial-up type applications), whether they arrive whole or infragments.
ForIPv6, the minimumMTU is1280 octets, however, the mandatory minimumfragment reassembly buffer size is1500 octets. The value of68 octets isvery small, since most current link layer technologies, like Ethernet, have aminimumMTU of1500.
It is impossible to know in advance the MTU of each link through whicha packet might travel. Sending a datagram greater than the receiverMTU willnot work because the packet will get silently dropped without informing thesource that the data did not reach its intended recipient.
flag<boolean>Sets or clears theSO_BROADCAST socket option. When set totrue, UDPpackets may be sent to a local interface's broadcast address.
multicastInterface<string>Note: All references to scope in this section are referring toIPv6 Zone Indices, which are defined byRFC 4007. In string form, an IPwith a scope index is written as'IP%scope' where scope is an interface name orinterface number.
Sets the default outgoing multicast interface of the socket to a choseninterface or back to system interface selection. ThemulticastInterface mustbe a valid string representation of an IP from the socket's family.
For IPv4 sockets, this should be the IP configured for the desired physicalinterface. All packets sent to multicast on the socket will be sent on theinterface determined by the most recent successful use of this call.
For IPv6 sockets,multicastInterface should include a scope to indicate theinterface as in the examples that follow. In IPv6, individualsend calls canalso use explicit scope in addresses, so only packets sent to a multicastaddress without specifying an explicit scope are affected by the most recentsuccessful use of this call.
On most systems, where scope format uses the interface name:
const socket = dgram.createSocket('udp6');socket.bind(1234, () => { socket.setMulticastInterface('::%eth1');});On Windows, where scope format uses an interface number:
const socket = dgram.createSocket('udp6');socket.bind(1234, () => { socket.setMulticastInterface('::%2');});All systems use an IP of the host on the desired physical interface:
const socket = dgram.createSocket('udp4');socket.bind(1234, () => { socket.setMulticastInterface('10.0.0.2');});A call on a socket that is not ready to send or no longer open may throw aNotrunningError.
IfmulticastInterface can not be parsed into an IP then anEINVALSystem Error is thrown.
On IPv4, ifmulticastInterface is a valid address but does not match anyinterface, or if the address does not match the family thenaSystem Error such asEADDRNOTAVAIL orEPROTONOSUP is thrown.
On IPv6, most errors with specifying or omitting scope will result in the socketcontinuing to use (or returning to) the system's default interface selection.
A socket's address family's ANY address (IPv4'0.0.0.0' or IPv6'::') can beused to return control of the sockets default outgoing interface to the systemfor future multicast packets.
flag<boolean>Sets or clears theIP_MULTICAST_LOOP socket option. When set totrue,multicast packets will also be received on the local interface.
ttl<number> Integer.Sets theIP_MULTICAST_TTL socket option. While TTL generally stands for"Time to Live", in this context it specifies the number of IP hops that apacket is allowed to travel through, specifically for multicast traffic. Eachrouter or gateway that forwards a packet decrements the TTL. If the TTL isdecremented to 0 by a router, it will not be forwarded.
The argument passed tosocket.setMulticastTTL() is a number of hopsbetween 0 and 255. The default on most systems is1 but can vary.
size<number> IntegerSets theSO_RCVBUF socket option. Sets the maximum socket receive bufferin bytes.
size<number> IntegerSets theSO_SNDBUF socket option. Sets the maximum socket send bufferin bytes.
ttl<number> Integer.Sets theIP_TTL socket option. While TTL generally stands for "Time to Live",in this context it specifies the number of IP hops that a packet is allowed totravel through. Each router or gateway that forwards a packet decrements theTTL. If the TTL is decremented to 0 by a router, it will not be forwarded.Changing TTL values is typically done for network probes or when multicasting.
The argument tosocket.setTTL() is a number of hops between 1 and 255.The default on most systems is 64 but can vary.
By default, binding a socket will cause it to block the Node.js process fromexiting as long as the socket is open. Thesocket.unref() method can be usedto exclude the socket from the reference counting that keeps the Node.jsprocess active, allowing the process to exit even if the socket is stilllistening.
Callingsocket.unref() multiple times will have no addition effect.
Thesocket.unref() method returns a reference to the socket so calls can bechained.
socket.bind() behavior#As of Node.js v0.10,dgram.Socket#bind() changed to an asynchronousexecution model. Legacy code that assumes synchronous behavior, as in thefollowing example:
const s = dgram.createSocket('udp4');s.bind(1234);s.addMembership('224.0.0.114');Must be changed to pass a callback function to thedgram.Socket#bind()function:
const s = dgram.createSocket('udp4');s.bind(1234, () => { s.addMembership('224.0.0.114');});dgram module functions#| Version | Changes |
|---|---|
| v8.7.0 | The |
| v8.6.0 | The |
| v0.11.13 | Added in: v0.11.13 |
options<Object> Available options are:type<string> The family of socket. Must be either'udp4' or'udp6'.Required.reuseAddr<boolean> Whentruesocket.bind() will reuse theaddress, even if another process has already bound a socket on it.Default:false.recvBufferSize<number> - Sets theSO_RCVBUF socket value.sendBufferSize<number> - Sets theSO_SNDBUF socket value.lookup<Function> Custom lookup function.Default:dns.lookup().callback<Function> Attached as a listener for'message' events. Optional.Creates adgram.Socket object. Once the socket is created, callingsocket.bind() will instruct the socket to begin listening for datagrammessages. Whenaddress andport are not passed tosocket.bind() themethod will bind the socket to the "all interfaces" address on a random port(it does the right thing for bothudp4 andudp6 sockets). The bound addressand port can be retrieved usingsocket.address().address andsocket.address().port.
type<string> - Either 'udp4' or 'udp6'.callback<Function> - Attached as a listener to'message' events.Creates adgram.Socket object of the specifiedtype. Thetype argumentcan be eitherudp4 orudp6. An optionalcallback function can be passedwhich is added as a listener for'message' events.
Once the socket is created, callingsocket.bind() will instruct thesocket to begin listening for datagram messages. Whenaddress andport arenot passed tosocket.bind() the method will bind the socket to the "allinterfaces" address on a random port (it does the right thing for bothudp4andudp6 sockets). The bound address and port can be retrieved usingsocket.address().address andsocket.address().port.