Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js socket.send() method (dgram)
Reference for socket.send() on a dgram socket in Node.js: argument forms, buffers and arrays, offset and length, connected sockets, callbacks and error codes.
socket.send() transmits one datagram from a UDP socket. The message can be a string, a Buffer, a typed array, a DataView, or an array of those (joined into a single datagram). The destination is a port and optional host, unless the socket was connected with socket.connect(), in which case you leave them out.
Sending is asynchronous. The optional callback runs when the operating system has accepted the data, which is not the same as the peer having received it. UDP gives no acknowledgement, so a successful callback only means "handed to the network stack".
import dgram from 'node:dgram'; const socket = dgram.createSocket('udp4'); socket.send('ping', 41234, '127.0.0.1', (error, bytes) => { console.log(error, bytes); socket.close(); });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
socket.send(msg, port?, address?, callback?) socket.send(msg, offset, length, port?, address?, callback?) socket.send(msg: string | Buffer | TypedArray | DataView | Array, ...): void // callback signature (error: Error | null, bytes: number) => void
| Name | Description |
|---|---|
msg |
The data. An array concatenates its elements into one datagram. Offset and length are not allowed with an array or a string. |
offset, length |
Start position and byte count inside a buffer, typed array or DataView. |
port |
Destination port, 1 to 65535. Omit on a connected socket. |
address |
Destination host name or IP. Default '127.0.0.1' for udp4 and '::1' for udp6. A name is resolved with dns.lookup() first. |
callback |
Called with (error, bytes) when sending finishes. error is null on success. If omitted, errors are emitted as 'error' events. |
Returns: nothing (undefined).
Errors and edge cases: an invalid port throws ERR_SOCKET_BAD_PORT; a closed socket throws ERR_SOCKET_DGRAM_NOT_RUNNING; giving a destination on a connected socket throws ERR_SOCKET_DGRAM_IS_CONNECTED; omitting it on an unconnected one throws ERR_SOCKET_DGRAM_NOT_CONNECTED. Asynchronous failures come through the callback: EMSGSIZE for a payload above 65,507 bytes (IPv4), EACCES for a broadcast address without setBroadcast(true), ENETUNREACH, or ENOTFOUND for a host name that does not resolve.
Usage notes
- One call, one datagram. The receiver sees the message exactly as sent, or not at all. Arrays are joined, not split.
- Unbound sockets are bound automatically. The first
send()binds to a random port on all interfaces, so replies reach you through'message'. - A callback is not an acknowledgement. Implement your own replies, sequence numbers and retries if delivery matters.
- Queued sends. Several
send()calls without waiting are queued by the kernel and library; checksocket.getSendQueueCount()in tight loops, and expect that order is not guaranteed on the network. - Connected sockets receive ICMP errors. After
connect(), a closed remote port can produce anECONNREFUSED'error'event on the socket. Handle'error'or such events crash the process. - Names cost a lookup. Pass IP addresses in hot paths to avoid a DNS lookup per datagram, or supply your own
lookupoption tocreateSocket(). - Keep payloads below the MTU (around 1,200 to 1,400 bytes for internet traffic) to avoid fragmentation.