IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael+i3@stapelberg.de>
-October 2011
+December 2011
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
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, the ipc-socket gets created
-in +/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the
-PID of i3. You can get the socketpath from i3 by calling +i3 --get-socketpath+.
+in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
+the PID of i3 and XXXXXX is a string of random characters from the portable
+filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
+calling +i3 --get-socketpath+.
All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
X11 property, stored on the X11 root window.
COMMAND (0)::
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.
+ directly after receiving it.
GET_WORKSPACES (1)::
Gets the current workspaces. The reply will be a JSON-encoded list of
workspaces (see the reply section).
Gets the configuration (as JSON map) of the workspace bar with the
given ID. If no ID is provided, an array with all configured bar IDs is
returned instead.
+GET_LOG_MARKERS (7)::
+ Gets the SHM log markers for the current position, the last wrap, the
+ SHM segment name and segment size. This is necessary for tools like
+ i3-dump-log which want to display the SHM log.
So, a typical message could look like this:
--------------------------------------------------
COMMAND (0)::
Confirmation/Error code for the COMMAND message.
-GET_WORKSPACES (1)::
+WORKSPACES (1)::
Reply to the GET_WORKSPACES message.
SUBSCRIBE (2)::
Confirmation/Error code for the SUBSCRIBE message.
-GET_OUTPUTS (3)::
+OUTPUTS (3)::
Reply to the GET_OUTPUTS message.
-GET_TREE (4)::
+TREE (4)::
Reply to the GET_TREE message.
-GET_MARKS (5)::
+MARKS (5)::
Reply to the GET_MARKS message.
-GET_BAR_CONFIG (6)::
+BAR_CONFIG (6)::
Reply to the GET_BAR_CONFIG message.
+LOG_MARKERS (7)::
+ Reply to the GET_LOG_MARKERS message.
=== COMMAND reply
{ "success": true }
-------------------
-=== GET_WORKSPACES reply
+=== WORKSPACES reply
The reply consists of a serialized list of workspaces. Each workspace has the
following properties:
]
-------------------
-=== GET_TREE reply
+=== TREE reply
The reply consists of a serialized tree. Each node in the tree (representing
one container) has at least the properties listed below. While the nodes might
}
------------------------
-=== GET_MARKS reply
+=== MARKS reply
The reply consists of a single array of strings for each container that has a
mark. The order of that array is undefined. If more than one container has the
If no window has a mark the response will be the empty array [].
-=== GET_BAR_CONFIG reply
+=== BAR_CONFIG reply
This can be used by third-party workspace bars (especially i3bar, but others
are free to implement compatible alternatives) to get the +bar+ block
Should the bar enable verbose output for debugging? Defaults to false.
colors (map)::
Contains key/value pairs of colors. Each value is a color code in hex,
- formatted rrggbb (like used in HTML).
+ formatted #rrggbb (like in HTML).
The following colors can be configured at the moment:
"workspace_buttons": true,
"verbose": false,
"colors": {
- "background": "c0c0c0",
- "statusline": "00ff00",
- "focused_workspace_text": "ffffff",
- "focused_workspace_bg": "000000"
+ "background": "#c0c0c0",
+ "statusline": "#00ff00",
+ "focused_workspace_text": "#ffffff",
+ "focused_workspace_bg": "#000000"
}
}
--------------
+=== LOG_MARKERS reply
+
+Gets the SHM log markers for the current position, the last wrap, the
+SHM segment name and segment size. This is necessary for tools like
+i3-dump-log which want to display the SHM log.
+
+The reply is a JSON map with the following entries:
+
+shmname (string)::
+ The name of the SHM segment, will be of the format +/i3-log-<pid>+.
+size (integer)::
+ The size (in bytes) of the SHM segment. If this is 0, SHM logging is
+ disabled.
+offset_next_write (integer)::
+ The offset in the SHM segment at which the next write will happen.
+ Tools should start printing lines from here, since the bytes following
+ this offset are the oldest log lines. However, the first line might be
+ garbled, so it makes sense to skip all bytes until the first \0.
+offset_last_wrap (integer)::
+ The offset in the SHM segment at which the last wrap occured. i3 only
+ stores entire messages in the SHM log, so it might waste a few bytes at
+ the end to be more efficient. Tools should not print content after the
+ offset_last_wrap.
+
+*Example*:
+-----------------------------
+{
+ "offset_next_write":132839,
+ "offset_last_wrap":26214400,
+ "shmname":"/i3-log-3392",
+ "size":26214400
+}
+-----------------------------
+
== Events
[[events]]
projects / i3 / i3 / blobdiff