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.