10. UNIXSocket

The unixsocket object is a built-in object that provides process communication functions between external applications using UNIX domain sockets.

Functional overview:

• Provides the UNIX socket server function.
• Provides the UNIX socket client function.
• The socket type is SOCK_STREAM (Stream Oriented).
• Any path name can be specified. Abstract socket addresses are also available.

Limitations:

• The number of UNIX socket resources that can be used is 3.
• The maximum number of clients that can connect to a UNIX socket server is 3.

---

unixsocket Global Object

Methods()/Properties	Summary	Version	Note
unixsocket.create()	Create a UNIX socket instance.

---

Details

unixsocket.create(mode,path[,options])

Create a UNIX socket instance.

Name	Type	M/O	Summary	Note
mode	string	mandatory	Specify 'server' or 'client'.
path	string	mandatory	Specify the socket path. Ex) /tmp/test.unixsocket To specify an abstract socket address, insert '@' at the beginning of the path. Ex) @/tmp/test.unixsocket
options	Object	optional	Options Refer to Options for details.
return	{Server}, {Client}, null	-	{Server} : Generated {Server} {Client} : Generated {Client} null : If instance creation fails due to lack of resources, if an instance of the specified path has already been created (at server), or if the specified path does not exist (at client)

Options

Name	Type	M/O	Summary	Note
recvBuffSize	number	optional	Receive buffer size [Byte] Range: 1 - 2,147,483,647 The default value is 4096.

---

{Server}

Methods()/Properties	Summary	Version	Note
.on()	Registers an event handler.
.listen()	Starts waiting for the socket connection from the client.
.read()	Reads data received from the client.
.write()	Sends data to the client.
.isConnected()	Gets the connection status of the socket.
.close()	Disconnects the socket.
.release()	Releases a server resource.

---

Details

.on(event,callback)

Registers an event handler.

Name	Type	M/O	Summary	Note
event	string	mandatory	Event name Names that can be used are: accept, readable, close
callback()	function	mandatory	Executes callback processing when an event occurs.
return	undefined	-	-	If the parameter is abnormal, an exception occurs.

event : ’accept’

Executes callback processing when a client connects to the socket.

Arguments	Type	Summary	Note
index	number	Assigned client index

event : ’readable’

Executes callback processing if data exists in the socket receive buffer.

Arguments	Type	Summary	Note
index	number	Client index where event occurred

event : ’close’

Executes callback processing when a socket disconnection occurs.

Note that if the client disconnects the socket while data is still in the socket receive buffer, the callback process will not be executed immediately. It is necessary to read all data with the .read() method.

Arguments	Type	Summary	Note
index	number	Client index where event occurred

.listen()

Starts waiting for the socket connection from the client.

This method executes only once after the instance is created.
Thereafter, a client management number (Client index) is assigned each time a client connects. The client index can be found using the 'accept' event notification or the .isConnected() method. This index will be one of the range 0 to "Maximum number of client connections - 1".

Name	Type	M/O	Summary	Note
return	boolean	-	true: Success false: Failure

.read(index[,isBin])

Reads data received from the client.

Name	Type	M/O	Summary	Note
index	number	mandatory	Specify the target client index.
isBin	boolean	optional	Specify the readout data format. true: Readout in binary data format false: Readout in string format The default value is false.
return	ArrayBuffer, string	-	Readout data The return type is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string.	The readout data will be less than or equal to the size specified by recvBuffSize. If there is no readout data, the size will be 0. If the parameter is abnormal, an exception occurs.

.write(index,data)

Sends data to the client.

Name	Type	M/O	Summary	Note
index	number	mandatory	Specify the target client index.
data	string, ArrayBuffer	mandatory	Sent data
return	number	-	Sent data size If the sending fails, -1 is returned.	If the parameter is abnormal, an exception occurs.

.isConnected(index)

Gets the connection status of the socket.

Name	Type	M/O	Summary	Note
index	number	mandatory	Specify the target client index.
return	boolean	-	Socket connection state true: Socket connected false: Socket not connected	If the parameter is abnormal, an exception occurs.

.close(index)

Disconnects the socket.

Name	Type	M/O	Summary	Note
index	number	mandatory	Specify the target client index.
return	undefined	-	-	If the parameter is abnormal, an exception occurs.

.release()

Releases a server resource.
All sockets while connected will be disconnected.

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

{Client}

Methods()/Properties	Summary	Version	Note
.on()	Registers an event handler.
.connect()	Connects a socket to the server.
.read()	Reads data received from the server.
.write()	Send data to the server.
.isConnected()	Gets the connection status of the socket.
.close()	Disconnects the socket.
.release()	Releases a client resource.

---

Details

.on(event,callback)

Registers an event handler.

Name	Type	M/O	Summary	Note
event	string	mandatory	Event name Names that can be used are: connect, readable, close
callback()	function	mandatory	Executes callback processing when an event occurs.
return	undefined	-	-	If the parameter is abnormal, an exception occurs.

event : ’connect’

Executes callback processing when a socket is connected.

event : ’readable’

Executes callback processing if data exists in the socket receive buffer.

event : ’close’

Executes callback processing when a socket disconnection occurs.
To reconnect, the .connect() method must be executed.

Note that if the server disconnects the socket while data is still in the socket receive buffer, the callback process will not be executed immediately. It is necessary to read all data with the .read() method.

.connect()

Connects a socket to the server.

Name	Type	M/O	Summary	Note
return	boolean	-	true: Success false: Failure

.read([isBin])

Reads data received from the server.

Name	Type	M/O	Summary	Note
isBin	boolean	optional	Specify the readout data format. true: Readout in binary data format false: Readout in string format The default value is false.
return	ArrayBuffer, string	-	Readout data The return type is determined by isBin. If isBin is true, the type is ArrayBuffer; otherwise, the type is string.	The readout data will be less than or equal to the size specified by recvBuffSize. If there is no readout data, the size will be 0. If the parameter is abnormal, an exception occurs.

.write(data)

Send data to the server.

Name	Type	M/O	Summary	Note
data	string, ArrayBuffer	mandatory	Sent data
return	number	-	Sent data size If the sending fails, -1 is returned.	If the parameter is abnormal, an exception occurs.

.isConnected()

Gets the connection status of the socket.

Name	Type	M/O	Summary	Note
return	boolean	-	Socket connection state true: Socket connected false: Socket not connected

.close()

Disconnects the socket.
To reconnect, the .connect() method must be executed.

Name	Type	M/O	Summary	Note
return	undefined	-	-

.release()

Releases a client resource.
A socket while connected will be disconnected.

Name	Type	M/O	Summary	Note
return	undefined	-	-

---

Object Usage Examples

Sample 1

This is a sample of UNIX Socket Server.
Receives data from the client and sends it loopback.

//The maximum number of clients that can connect to a UNIX socket server is 3
var readEvt = [false,false,false];

var path ='/tmp/test.unixsocket'
var server = unixsocket.create('server', path);
if(!server) throw new Error('Failed to create server instance');

server.on('accept', function(index) {
    print('accept', index);
});
server.on('readable', function(index) {
    print('readable', index);
    readEvt[index] = true;
});
server.on('close', function(index) {
    print('close', index);
});

if(!server.listen()) throw new Error('Failed to start server listening'); 

print('Server listening started! [' + path + ']');

while(1) {
    for(var i=0; i<readEvt.length; i++) {
        if(readEvt[i]) {
            readEvt[i] = false;
            var rStr = server.read(i);
            print('recv ' + i + ': ' + rStr.replace(/[\x00-\x1F\x7F-\x9F]/g,'\\') + ' (' + rStr.length + ')');
             //Loopback
            if(server.write(i, rStr) == rStr.length) {
                print('send ' + i + ': OK');
            }
        }
    }
}

Sample 2

This is a sample of UNIX socket client.
While connected to the server, data will be sent in 1-second cycles. It also constantly waits for incoming data from the server.

var path ='/tmp/test.unixsocket'
var client = unixsocket.create('client', path);
if(!client) throw new Error('Failed to create client instance');

client.on('connect', function() {
    print('connect');
});
client.on('readable', function() {
    print('readable');
});
client.on('close', function() {
    print('close');
});

var sendEvt = false;
var tmobj = setInterval(function() { sendEvt = true; }, 1000);

while(1) {
    if(!client.isConnected()) {
        print('Connecting... [' + path + ']');
        if(!client.connect()) {
            setTimeout(1000).wait(); //1sec wait
        }
    } else {
        if(sendEvt) {
            sendEvt = false;
            var sStr = Date.now() + ' to server\n';
            if(client.write(sStr) == sStr.length) {
                print('send: OK');
            }
        }
        var rStr = client.read();
        if(rStr.length) {
            print('recv: ' + rStr.replace(/[\x00-\x1F\x7F-\x9F]/g,'\\') + ' (' + rStr.length + ')');
        }
    }
}

---

Updated: 2022-10-25