IPC interface (interprocess communication)
==========================================
-Michael Stapelberg <michael+i3@stapelberg.de>
-December 2011
+Michael Stapelberg <michael@i3wm.org>
+February 2012
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:
--------------------------------------------------
Reply to the GET_MARKS message.
BAR_CONFIG (6)::
Reply to the GET_BAR_CONFIG message.
-LOG_MARKERS (7)::
- Reply to the GET_LOG_MARKERS message.
=== COMMAND reply
}
--------------
-=== 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]]
Perl::
http://search.cpan.org/search?query=AnyEvent::I3
Python::
- http://github.com/thepub/i3ipc
+ https://github.com/whitelynx/i3ipc
+ https://github.com/ziberna/i3-py (includes higher-level features)