IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael+i3@stapelberg.de>
-March 2010
+October 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.
+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.
-------------------------------------------------------------
use IO::Socket::UNIX;
-my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');
+chomp(my $path = qx(i3 --get-socketpath));
+my $sock = IO::Socket::UNIX->new(Peer => $path);
-------------------------------------------------------------
== Sending messages to i3
Gets the layout tree. i3 uses a tree as data structure which includes
every container. The reply will be the JSON-encoded tree (see the reply
section).
+GET_MARKS (5)::
+ Gets a list of marks (identifiers for containers to easily jump to them
+ later). The reply will be a JSON-encoded list of window marks (see
+ reply section).
+GET_BAR_CONFIG (6)::
+ 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.
So, a typical message could look like this:
--------------------------------------------------
Reply to the GET_OUTPUTS message.
GET_TREE (4)::
Reply to the GET_TREE message.
+GET_MARKS (5)::
+ Reply to the GET_MARKS message.
+GET_BAR_CONFIG (6)::
+ Reply to the GET_BAR_CONFIG message.
=== COMMAND reply
}
------------------------
+=== GET_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
+same mark, it will be represented multiple times in the reply (the array
+contents are not unique).
+
+If no window has a mark the response will be the empty array [].
+
+=== GET_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
+configuration from i3.
+
+Depending on the input, the reply is either:
+
+empty input::
+ An array of configured bar IDs
+Bar ID::
+ A JSON map containing the configuration for the specified bar.
+
+Each bar configuration has the following properties:
+
+id (string)::
+ The ID for this bar. Included in case you request multiple
+ configurations and want to differentiate the different replies.
+mode (string)::
+ Either +dock+ (the bar sets the dock window type) or +hide+ (the bar
+ does not show unless a specific key is pressed).
+position (string)::
+ Either +bottom+ or +top+ at the moment.
+status_command (string)::
+ Command which will be run to generate a statusline. Each line on stdout
+ of this command will be displayed in the bar. At the moment, no
+ formatting is supported.
+font (string)::
+ The font to use for text on the bar.
+workspace_buttons (boolean)::
+ Display workspace buttons or not? Defaults to true.
+verbose (boolean)::
+ 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 in HTML).
+
+The following colors can be configured at the moment:
+
+background::
+ Background color of the bar.
+statusline::
+ Text color to be used for the statusline.
+focused_workspace_text/focused_workspace_bg::
+ Text color/background color for a workspace button when the workspace
+ has focus.
+active_workspace_text/active_workspace_bg::
+ Text color/background color for a workspace button when the workspace
+ is active (visible) on some output, but the focus is on another one.
+ You can only tell this apart from the focused workspace when you are
+ using multiple monitors.
+inactive_workspace_text/inactive_workspace_bg::
+ Text color/background color for a workspace button when the workspace
+ does not have focus and is not active (visible) on any output. This
+ will be the case for most workspaces.
+urgent_workspace_text/urgent_workspace_bar::
+ Text color/background color for workspaces which contain at least one
+ window with the urgency hint set.
+
+
+*Example of configured bars:*
+--------------
+["bar-bxuqzf"]
+--------------
+
+*Example of bar configuration:*
+--------------
+{
+ "id": "bar-bxuqzf",
+ "mode": "dock",
+ "position": "bottom",
+ "status_command": "i3status",
+ "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
+ "workspace_buttons": true,
+ "verbose": false,
+ "colors": {
+ "background": "#c0c0c0",
+ "statusline": "#00ff00",
+ "focused_workspace_text": "#ffffff",
+ "focused_workspace_bg": "#000000"
+ }
+}
+--------------
== Events
projects / i3 / i3.github.io / blobdiff