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"
- }
-]