unix-dgram

What is unix-dgram?

The unix-dgram npm package provides a way to create and manage Unix domain datagram sockets in Node.js. This allows for inter-process communication (IPC) on the same host using the Unix domain socket protocol.

What are unix-dgram's main functionalities?

Creating a Unix Datagram Socket

This feature allows you to create a Unix datagram socket and bind it to a specific path. This is useful for setting up a communication endpoint for IPC.

const dgram = require('unix-dgram');
const socket = dgram.createSocket('unix_dgram');
socket.bind('/tmp/socket');
console.log('Socket bound to /tmp/socket');

Sending Messages

This feature allows you to send messages through the Unix datagram socket. The code sample demonstrates sending a simple 'Hello, World!' message to a specified socket path.

const dgram = require('unix-dgram');
const socket = dgram.createSocket('unix_dgram');
socket.send(Buffer.from('Hello, World!'), 0, 12, '/tmp/socket', (err) => {
  if (err) console.error(err);
  else console.log('Message sent');
});

Receiving Messages

This feature allows you to receive messages sent to the Unix datagram socket. The code sample shows how to set up an event listener for incoming messages and log them to the console.

const dgram = require('unix-dgram');
const socket = dgram.createSocket('unix_dgram');
socket.on('message', (msg, rinfo) => {
  console.log('Received message:', msg.toString());
});
socket.bind('/tmp/socket');

Other packages similar to unix-dgram

dgram

The dgram module is a built-in Node.js module that provides an implementation of UDP datagram sockets. While it is primarily used for network communication over IP, it can also be used for local IPC with Unix domain sockets. However, it is more general-purpose and not specifically tailored for Unix domain sockets like unix-dgram.

node-ipc

The node-ipc package provides a comprehensive set of tools for inter-process communication in Node.js, including support for Unix sockets, TCP, and UDP. It offers more features and flexibility compared to unix-dgram, but may be overkill if you only need basic Unix datagram socket functionality.

README

node-unix-dgram

Communicate over UNIX datagram sockets.

Usage

Server:

// One-shot server.  Note that the server cannot send a reply;
// UNIX datagram sockets are unconnected and the client is not addressable.
var unix = require('unix-dgram');
var server = unix.createSocket('unix_dgram', function(buf) {
  console.log('received ' + buf);
  server.close();
});
server.bind('/path/to/socket');

Client:

// Send a single message to the server.
var message = Buffer('ping');
var client = unix.createSocket('unix_dgram');
client.on('error', console.error);
client.send(message, 0, message.length, '/path/to/socket');
client.close();

API

Caveat emptor: events and callbacks are synchronous for efficiency reasons.

unix.createSocket(type, [listener])

Returns a new unix.Socket object. type should be 'unix_dgram'. Throws an exception if the socket(2) system call fails.

The optional listener argument is added as a listener for the 'message' event. The event listener receives the message as a Buffer object as its first argument.

socket.bind(path)

Create a server at path. Emits a 'listening' event on success or an 'error' event if the bind(2) system call fails.

socket.connect(remote_path)

Associate a socket with a remote path so you can send a message without setting the remote path. Once the socket is connected it emits a 'connect' event. It also allows to perform some kind of congestion control as it emits a 'congestion' event when the receiving buffer is full, and a 'writable' event when it stops being full.

socket.send(buf, [callback])

Only to be used with connected sockets. It sends a message to the remote path associated with the socket

Example:

var unix = require('unix-dgram');

var client = unix.createSocket('unix_dgram');

client.on('error', function(err) {
    console.error(err);
});

client.on('connect', function() {
    console.log('connected');
    client.on('congestion', function() {
        console.log('congestion');
        /* The server is not accepting data */
    });

    client.on('writable', function() {
        console.log('writable');
        /* The server can accept data */
    });

    var message = new Buffer('PING');
    client.send(message);
});

client.connect('/tmp/server');

socket.send_to(buf, offset, length, path, [callback]);

Send a message to the server listening at path.

buf is a Buffer object containing the message to send, offset is the offset into the buffer and length is the length of the message.

For backwards compatibility, you can still use the socket.send function with this same signature.

Example:

var buf = new Buffer('foobarbaz');
socket.send(buf, 3, 4, '/path/to/socket');  // Sends 'barb'.

socket.close()

Close the socket. If the socket was bound to a path with socket.bind(), then you will no longer receive new messages. The file system entity (the socket file) is not automatically unlinked.