IPC interface (interprocess communication)

This document describes how to interface with i3 from a separate process. This +is useful for example to remote-control i3 (to write test cases for example) or +to get various information like the current workspaces to implement an external +workspace bar.

The method of choice for IPC in our case is a unix socket because it has very +little overhead on both sides and is usually available without headaches in +most languages. In the default configuration file, no ipc-socket path is +specified and thus no socket is created. The standard path (which i3-msg and +i3-input use) is /tmp/i3-ipc.sock.

1. Establishing a connection

To establish a connection, simply open the IPC socket. The following code +snippet illustrates this in Perl:

use IO::Socket::UNIX;
+my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');

2. Sending messages to i3

To send a message to i3, you have to format in the binary message format which +i3 expects. This format specifies a magic string in the beginning to ensure +the integrity of messages (to prevent follow-up errors). Afterwards follows +the length of the payload of the message as 32-bit integer and the type of +the message as 32-bit integer (the integers are not converted, so they are +in native byte order).

The magic string currently is "i3-ipc" and will only be changed when a change +in the IPC API is done which breaks compatibility (we hope that we donât need +to do that).

Currently implemented message types are the following:

+0 (COMMAND) +: +
+ The payload of the message is a command for i3 (like the commands you + can bind to keys in the configuration file) and will be executed + directly after receiving it. There is no reply to this message. +
+
+1 (GET_WORKSPACES) +: +
+ Gets the current workspaces. The reply will be a JSON-encoded list of + workspaces (see the reply section). +
+

So, a typical message could look like this:

"i3-ipc" <message length> <message type> <payload>

Or, as a hexdump:

00000000  69 33 2d 69 70 63 04 00  00 00 00 00 00 00 65 78  |i3-ipc........ex|
+00000010  69 74 0a                                          |it.|

To generate and send such a message, you could use the following code in Perl:

sub format_ipc_command {
+    my ($msg) = @_;
+    my $len;
+    # Get the real byte count (vs. amount of characters)
+    { use bytes; $len = length($msg); }
+    return "i3-ipc" . pack("LL", $len, 0) . $msg;
+}
+
+$sock->write(format_ipc_command("exit"));

3. Receiving replies from i3

Replies of i3 usually consist of a simple string (the length of the string +is the message_length, so you can consider them length-prefixed) which in turn +contain the JSON serialization of a data structure. For example, the +GET_WORKSPACES message returns an array of workspaces (each workspace is a map +with certain attributes).

3.1. Reply format

The reply format is identical to the normal message format. There also is +the magic string, then the message length, then the message type and the +payload.

The following reply types are implemented:

+1 (GET_WORKSPACES) +: +
+ Reply to the GET_WORKSPACES message. +
+

3.2. GET_WORKSPACES reply

The reply consists of a serialized list of workspaces. Each workspace has the +following properties:

+num (integer) +: +
+ The internal number of the workspace. Corresponds to the command + to switch to this workspace. +
+
+name (string) +: +
+ The name of this workspace (by default num+1), as changed by the + user. Encoded in UTF-8. +
+
+visible (boolean) +: +
+ Whether this workspace is currently visible on an output (multiple + workspaces can be visible at the same time). +
+
+focused (boolean) +: +
+ Whether this workspace currently has the focus (only one workspace + can have the focus at the same time). +
+
+rect (map) +: +
+ The rectangle of this workspace (equals the rect of the output it + is on), consists of x, y, width, height. +
+
+output (string) +: +
+ The video output this workspace is on (LVDS1, VGA1, â¦). +
+

Example:

[
+ {
+  "num": 0,
+  "name": "1",
+  "visible": true,
+  "focused": true,
+  "rect": {
+   "x": 0,
+   "y": 0,
+   "width": 1280,
+   "height": 800
+  },
+  "output": "LVDS1"
+ },
+ {
+  "num": 1,
+  "name": "2",
+  "visible": false,
+  "focused": false,
+  "rect": {
+   "x": 0,
+   "y": 0,
+   "width": 1280,
+   "height": 800
+  },
+  "output": "LVDS1"
+ }
+]