Table of Contents

• UDP / Datagram Sockets
  • Class: dgram.Socket
    • Event: 'close'
    • Event: 'error'
    • Event: 'listening'
    • Event: 'message'
    • socket.addMembership(multicastAddress[, multicastInterface])
    • socket.address()
    • socket.bind([port][, address][, callback])
    • socket.bind(options[, callback])
    • socket.close([callback])
    • socket.dropMembership(multicastAddress[, multicastInterface])
    • socket.ref()
    • socket.send(msg, [offset, length,] port, address[, callback])
    • socket.setBroadcast(flag)
    • socket.setMulticastLoopback(flag)
    • socket.setMulticastTTL(ttl)
    • socket.setTTL(ttl)
    • socket.unref()
    • Change to asynchronous socket.bind() behavior
  • dgram module functions
    • dgram.createSocket(options[, callback])
    • dgram.createSocket(type[, callback])

UDP / Datagram Sockets#

Stability: 2 - Stable

The dgram 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', () => {
  var address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

server.bind(41234);
// server listening 0.0.0.0:41234

Class: dgram.Socket#

The dgram.Socket object is an EventEmitter that encapsulates the datagram functionality.

New instances of dgram.Socket are created using dgram.createSocket(). The new keyword is not to be used to create dgram.Socket instances.

Event: 'close'#

The 'close' event is emitted after a socket is closed with close(). Once triggered, no new 'message' events will be emitted on this socket.

Event: 'error'#

• exception <Error>

The 'error' event is emitted whenever any error occurs. The event handler function is passed a single Error object.

Event: 'listening'#

The 'listening' event is emitted whenever a socket begins listening for datagram messages. This occurs as soon as UDP sockets are created.

Event: 'message'#

The 'message' event is emitted when a new datagram is available on a socket. The event handler function is passed two arguments: msg and rinfo.

• msg <Buffer> - The message
• rinfo <Object> - Remote address information
  • address <string> The sender address
  • family <string> The address family ('IPv4' or 'IPv6')
  • port <number> The sender port
  • size <number> The message size

socket.addMembership(multicastAddress[, multicastInterface])#

• multicastAddress <string>
• multicastInterface <string>, Optional

Tells the kernel to join a multicast group at the given multicastAddress and multicastInterface using the IP_ADD_MEMBERSHIP socket option. If the multicastInterface argument is not specified, the operating system will choose one interface and will add membership to it. To add membership to every available interface, call addMembership multiple times, once per interface.

socket.address()#

Returns an object containing the address information for a socket. For UDP sockets, this object will contain address, family and port properties.

socket.bind([port][, address][, callback])#

• port <number> - Integer, Optional
• address <string>, Optional
• callback <Function> with no parameters, Optional. Called when binding is complete.

For UDP sockets, causes the dgram.Socket to listen for datagram messages on a named port and optional address. If port is not specified or is 0, the operating system will attempt to bind to a random port. If address is not specified, the operating system will attempt to listen on all addresses. Once binding is complete, a 'listening' event is emitted and the optional callback function is called.

Note that specifying both a 'listening' event listener and passing a callback to the socket.bind() method is not harmful but not very useful.

A bound datagram socket keeps the Node.js process running to receive datagram messages.

If binding fails, an 'error' event is generated. In rare case (e.g. attempting to bind with a closed socket), an Error 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', () => {
  var address = server.address();
  console.log(`server listening ${address.address}:${address.port}`);
});

server.bind(41234);
// server listening 0.0.0.0:41234

socket.bind(options[, callback])#

• options <Object> - Required. Supports the following properties:
  • port <number> - Optional.
  • address <string> - Optional.
  • exclusive <boolean> - Optional.
• callback <Function> - Optional.

For UDP sockets, causes the dgram.Socket to listen for datagram messages on a named port and optional address that are passed as properties of an options object passed as the first argument. If port is not specified or is 0, the operating system will attempt to bind to a random port. If address is not specified, the operating system will attempt to listen on all addresses. Once binding is complete, a 'listening' event is emitted and the optional callback function is called.

Note that specifying both a 'listening' event listener and passing a callback to the socket.bind() method is not harmful but not very useful.

The options object may contain an additional exclusive property that is use when using dgram.Socket objects with the cluster module. When exclusive is set to false (the default), cluster workers will use the same underlying socket handle allowing connection handling duties to be shared. When exclusive is true, however, the handle is not shared and attempted port sharing results in an error.

A bound datagram socket keeps the Node.js process running to receive datagram messages.

If binding fails, an 'error' event is generated. In rare case (e.g. attempting to bind with a closed socket), an Error may be thrown.

An example socket listening on an exclusive port is shown below.

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true
});

socket.close([callback])#

Close the underlying socket and stop listening for data on it. If a callback is provided, it is added as a listener for the 'close' event.

socket.dropMembership(multicastAddress[, multicastInterface])#

• multicastAddress <string>
• multicastInterface <string>, Optional

Instructs the kernel to leave a multicast group at multicastAddress using the IP_DROP_MEMBERSHIP socket option. This method is automatically called by the kernel when the socket is closed or the process terminates, so most apps will never have reason to call this.

If multicastInterface is not specified, the operating system will attempt to drop membership on all valid interfaces.

socket.ref()#

By default, binding a socket will cause it to block the Node.js process from exiting as long as the socket is open. The socket.unref() method can be used to exclude the socket from the reference counting that keeps the Node.js process active. The socket.ref() method adds the socket back to the reference counting and restores the default behavior.

Calling socket.ref() multiples times will have no additional effect.

The socket.ref() method returns a reference to the socket so calls can be chained.

socket.send(msg, [offset, length,] port, address[, callback])#

• msg <Buffer> | <string> | <array> Message to be sent
• offset <number> Integer. Optional. Offset in the buffer where the message starts.
• length <number> Integer. Optional. 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. Optional.

Broadcasts a datagram on the socket. The destination port and address must be specified.

The msg argument contains the message to be sent. Depending on its type, different behavior can apply. If msg is a Buffer, the offset and length specify the offset within the Buffer where the message begins and the number of bytes in the message, respectively. If msg is a String, then it is automatically converted to a Buffer with 'utf8' encoding. With messages that contain multi-byte characters, offset and length will be calculated with respect to byte length and not the character position. If msg is an array, offset and length must not be specified.