Skip to main content
Socket.prototype.send - dgram - Node documentation
method Socket.prototype.send

Usage in Deno

import { Socket } from "node:dgram";
Socket.prototype.send(
msg:
string
| Uint8Array
| readonly any[]
,
port?: number,
address?: string,
callback?: (
error: Error | null,
bytes: number,
) => void
,
): void

Broadcasts a datagram on the socket. For connectionless sockets, the destination port and address must be specified. Connected sockets, on the other hand, will use their associated remote endpoint, so the port and address arguments must not be set.

The msg argument contains the message to be sent. Depending on its type, different behavior can apply. If msg is a Buffer, any TypedArray or a DataView, 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.

The address argument is a string. If the value of address is a host name, DNS will be used to resolve the address of the host. If address is not provided or otherwise nullish, '127.0.0.1' (for udp4 sockets) or '::1' (for udp6 sockets) will be used by default.

If the socket has not been previously bound with a call to bind, the socket is assigned a random port number and is bound to the "all interfaces" address ('0.0.0.0' for udp4 sockets, '::0' for udp6 sockets.)

An optional callback function may be specified to as a way of reporting DNS errors or for determining when it is safe to reuse the buf object. DNS lookups delay the time to send for at least one tick of the Node.js event loop.

The only way to know for sure that the datagram has been sent is by using a callback. If an error occurs and a callback is given, the error will be passed as the first argument to the callback. If a callback is not given, 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, 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;

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

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;

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

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 the application and operating system. Run benchmarks to determine the optimal strategy on a case-by-case basis. Generally speaking, however, sending multiple buffers is faster.

Example of sending a UDP packet using a socket connected to a port on localhost:

import dgram from 'node:dgram';
import { Buffer } from 'node:buffer';

const message = Buffer.from('Some bytes');
const client = dgram.createSocket('udp4');
client.connect(41234, 'localhost', (err) => {
  client.send(message, (err) => {
    client.close();
  });
});

Parameters

msg:
string
| Uint8Array
| readonly any[]

Message to be sent.

optional
port: number

Destination port.

optional
address: string

Destination host name or IP address.

optional
callback: (
error: Error | null,
bytes: number,
) => void

Called when the message has been sent.

Return Type

void
Socket.prototype.send(
msg:
string
| Uint8Array
| readonly any[]
,
port?: number,
callback?: (
error: Error | null,
bytes: number,
) => void
,
): void

Parameters

msg:
string
| Uint8Array
| readonly any[]
optional
port: number
optional
callback: (
error: Error | null,
bytes: number,
) => void

Return Type

void
Socket.prototype.send(
msg:
string
| Uint8Array
| readonly any[]
,
callback?: (
error: Error | null,
bytes: number,
) => void
,
): void

Parameters

msg:
string
| Uint8Array
| readonly any[]
optional
callback: (
error: Error | null,
bytes: number,
) => void

Return Type

void
Socket.prototype.send(
msg: string | Uint8Array,
offset: number,
length: number,
port?: number,
address?: string,
callback?: (
error: Error | null,
bytes: number,
) => void
,
): void

Parameters

msg: string | Uint8Array
offset: number
length: number
optional
port: number
optional
address: string
optional
callback: (
error: Error | null,
bytes: number,
) => void

Return Type

void
Socket.prototype.send(
msg: string | Uint8Array,
offset: number,
length: number,
port?: number,
callback?: (
error: Error | null,
bytes: number,
) => void
,
): void

Parameters

msg: string | Uint8Array
offset: number
length: number
optional
port: number
optional
callback: (
error: Error | null,
bytes: number,
) => void

Return Type

void
Socket.prototype.send(
msg: string | Uint8Array,
offset: number,
length: number,
callback?: (
error: Error | null,
bytes: number,
) => void
,
): void

Parameters

msg: string | Uint8Array
offset: number
length: number
optional
callback: (
error: Error | null,
bytes: number,
) => void

Return Type

void