Merge branch 'master' into next

[i3/i3] / docs / ipc

diff --git a/docs/ipc b/docs/ipc
index e73ca6f85f66f7c2a9f4bbbad4dafb46af8a69a9..1ac97fecab020220b12e4e4629894c1cdb08bec3 100644 (file)
--- a/docs/ipc
+++ b/docs/ipc
@@ -1,7 +1,7 @@
 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
@@ -11,8 +11,10 @@ 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, 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.
@@ -68,10 +70,6 @@ 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.
-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:
 --------------------------------------------------
@@ -127,8 +125,6 @@ MARKS (5)::
        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
 
@@ -530,40 +526,6 @@ urgent_workspace_text/urgent_workspace_bar::
 }
 --------------
 
-=== 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]]
@@ -662,3 +624,4 @@ Perl::
        http://search.cpan.org/search?query=AnyEvent::I3
 Python::
        http://github.com/thepub/i3ipc
+       http://github.com/jzib/i3-py (includes higher-level features)