git.sur5r.net Git - i3/i3/blob - docs/ipc

   1 IPC interface (interprocess communication)
   2 ==========================================
   3 Michael Stapelberg <michael@i3wm.org>
   4 August 2012
   5
   6 This document describes how to interface with i3 from a separate process. This
   7 is useful for example to remote-control i3 (to write test cases for example) or
   8 to get various information like the current workspaces to implement an external
   9 workspace bar.
  10
  11 The method of choice for IPC in our case is a unix socket because it has very
  12 little overhead on both sides and is usually available without headaches in
  13 most languages. In the default configuration file, the ipc-socket gets created
  14 in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
  15 the PID of i3 and XXXXXX is a string of random characters from the portable
  16 filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
  17 calling +i3 --get-socketpath+.
  18
  19 All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
  20 X11 property, stored on the X11 root window.
  21
  22 == Establishing a connection
  23
  24 To establish a connection, simply open the IPC socket. The following code
  25 snippet illustrates this in Perl:
  26
  27 -------------------------------------------------------------
  28 use IO::Socket::UNIX;
  29 chomp(my $path = qx(i3 --get-socketpath));
  30 my $sock = IO::Socket::UNIX->new(Peer => $path);
  31 -------------------------------------------------------------
  32
  33 == Sending messages to i3
  34
  35 To send a message to i3, you have to format in the binary message format which
  36 i3 expects. This format specifies a magic string in the beginning to ensure
  37 the integrity of messages (to prevent follow-up errors). Following the magic
  38 string comes the length of the payload of the message as 32-bit integer, and
  39 the type of the message as 32-bit integer (the integers are not converted, so
  40 they are in native byte order).
  41
  42 The magic string currently is "i3-ipc" and will only be changed when a change
  43 in the IPC API is done which breaks compatibility (we hope that we don’t need
  44 to do that).
  45
  46 Currently implemented message types are the following:
  47
  48 COMMAND (0)::
  49         The payload of the message is a command for i3 (like the commands you
  50         can bind to keys in the configuration file) and will be executed
  51         directly after receiving it.
  52 GET_WORKSPACES (1)::
  53         Gets the current workspaces. The reply will be a JSON-encoded list of
  54         workspaces (see the reply section).
  55 SUBSCRIBE (2)::
  56         Subscribes your connection to certain events. See <<events>> for a
  57         description of this message and the concept of events.
  58 GET_OUTPUTS (3)::
  59         Gets the current outputs. The reply will be a JSON-encoded list of outputs
  60         (see the reply section).
  61 GET_TREE (4)::
  62         Gets the layout tree. i3 uses a tree as data structure which includes
  63         every container. The reply will be the JSON-encoded tree (see the reply
  64         section).
  65 GET_MARKS (5)::
  66         Gets a list of marks (identifiers for containers to easily jump to them
  67         later). The reply will be a JSON-encoded list of window marks (see
  68         reply section).
  69 GET_BAR_CONFIG (6)::
  70         Gets the configuration (as JSON map) of the workspace bar with the
  71         given ID. If no ID is provided, an array with all configured bar IDs is
  72         returned instead.
  73 GET_VERSION (7)::
  74         Gets the version of i3. The reply will be a JSON-encoded dictionary
  75         with the major, minor, patch and human-readable version.
  76
  77 So, a typical message could look like this:
  78 --------------------------------------------------
  79 "i3-ipc" <message length> <message type> <payload>
  80 --------------------------------------------------
  81
  82 Or, as a hexdump:
  83 ------------------------------------------------------------------------------
  84 00000000  69 33 2d 69 70 63 04 00  00 00 00 00 00 00 65 78  |i3-ipc........ex|
  85 00000010  69 74 0a                                          |it.|
  86 ------------------------------------------------------------------------------
  87
  88 To generate and send such a message, you could use the following code in Perl:
  89 ------------------------------------------------------------
  90 sub format_ipc_command {
  91     my ($msg) = @_;
  92     my $len;
  93     # Get the real byte count (vs. amount of characters)
  94     { use bytes; $len = length($msg); }
  95     return "i3-ipc" . pack("LL", $len, 0) . $msg;
  96 }
  97
  98 $sock->write(format_ipc_command("exit"));
  99 ------------------------------------------------------------------------------
 100
 101 == Receiving replies from i3
 102
 103 Replies from i3 usually consist of a simple string (the length of the string
 104 is the message_length, so you can consider them length-prefixed) which in turn
 105 contain the JSON serialization of a data structure. For example, the
 106 GET_WORKSPACES message returns an array of workspaces (each workspace is a map
 107 with certain attributes).
 108
 109 === Reply format
 110
 111 The reply format is identical to the normal message format. There also is
 112 the magic string, then the message length, then the message type and the
 113 payload.
 114
 115 The following reply types are implemented:
 116
 117 COMMAND (0)::
 118         Confirmation/Error code for the COMMAND message.
 119 WORKSPACES (1)::
 120         Reply to the GET_WORKSPACES message.
 121 SUBSCRIBE (2)::
 122         Confirmation/Error code for the SUBSCRIBE message.
 123 OUTPUTS (3)::
 124         Reply to the GET_OUTPUTS message.
 125 TREE (4)::
 126         Reply to the GET_TREE message.
 127 MARKS (5)::
 128         Reply to the GET_MARKS message.
 129 BAR_CONFIG (6)::
 130         Reply to the GET_BAR_CONFIG message.
 131 VERSION (7)::
 132         Reply to the GET_VERSION message.
 133
 134 === COMMAND reply
 135
 136 The reply consists of a single serialized map. At the moment, the only
 137 property is +success (bool)+, but this will be expanded in future versions.
 138
 139 *Example:*
 140 -------------------
 141 { "success": true }
 142 -------------------
 143
 144 === WORKSPACES reply
 145
 146 The reply consists of a serialized list of workspaces. Each workspace has the
 147 following properties:
 148
 149 num (integer)::
 150         The logical number of the workspace. Corresponds to the command
 151         to switch to this workspace.
 152 name (string)::
 153         The name of this workspace (by default num+1), as changed by the
 154         user. Encoded in UTF-8.
 155 visible (boolean)::
 156         Whether this workspace is currently visible on an output (multiple
 157         workspaces can be visible at the same time).
 158 focused (boolean)::
 159         Whether this workspace currently has the focus (only one workspace
 160         can have the focus at the same time).
 161 urgent (boolean)::
 162         Whether a window on this workspace has the "urgent" flag set.
 163 rect (map)::
 164         The rectangle of this workspace (equals the rect of the output it
 165         is on), consists of x, y, width, height.
 166 output (string)::
 167         The video output this workspace is on (LVDS1, VGA1, …).
 168
 169 *Example:*
 170 -------------------
 171 [
 172  {
 173   "num": 0,
 174   "name": "1",
 175   "visible": true,
 176   "focused": true,
 177   "urgent": false,
 178   "rect": {
 179    "x": 0,
 180    "y": 0,
 181    "width": 1280,
 182    "height": 800
 183   },
 184   "output": "LVDS1"
 185  },
 186  {
 187   "num": 1,
 188   "name": "2",
 189   "visible": false,
 190   "focused": false,
 191   "urgent": false,
 192   "rect": {
 193    "x": 0,
 194    "y": 0,
 195    "width": 1280,
 196    "height": 800
 197   },
 198   "output": "LVDS1"
 199  }
 200 ]
 201 -------------------
 202
 203 === SUBSCRIBE reply
 204
 205 The reply consists of a single serialized map. The only property is
 206 +success (bool)+, indicating whether the subscription was successful (the
 207 default) or whether a JSON parse error occurred.
 208
 209 *Example:*
 210 -------------------
 211 { "success": true }
 212 -------------------
 213
 214 === OUTPUTS reply
 215
 216 The reply consists of a serialized list of outputs. Each output has the
 217 following properties:
 218
 219 name (string)::
 220         The name of this output (as seen in +xrandr(1)+). Encoded in UTF-8.
 221 active (boolean)::
 222         Whether this output is currently active (has a valid mode).
 223 current_workspace (integer)::
 224         The current workspace which is visible on this output. +null+ if the
 225         output is not active.
 226 rect (map)::
 227         The rectangle of this output (equals the rect of the output it
 228         is on), consists of x, y, width, height.
 229
 230 *Example:*
 231 -------------------
 232 [
 233  {
 234   "name": "LVDS1",
 235   "active": true,
 236   "current_workspace": 4,
 237   "rect": {
 238    "x": 0,
 239    "y": 0,
 240    "width": 1280,
 241    "height": 800
 242   }
 243  },
 244  {
 245   "name": "VGA1",
 246   "active": true,
 247   "current_workspace": 1,
 248   "rect": {
 249    "x": 1280,
 250    "y": 0,
 251    "width": 1280,
 252    "height": 1024
 253   },
 254  }
 255 ]
 256 -------------------
 257
 258 === TREE reply
 259
 260 The reply consists of a serialized tree. Each node in the tree (representing
 261 one container) has at least the properties listed below. While the nodes might
 262 have more properties, please do not use any properties which are not documented
 263 here. They are not yet finalized and will probably change!
 264
 265 id (integer)::
 266         The internal ID (actually a C pointer value) of this container. Do not
 267         make any assumptions about it. You can use it to (re-)identify and
 268         address containers when talking to i3.
 269 name (string)::
 270         The internal name of this container. For all containers which are part
 271         of the tree structure down to the workspace contents, this is set to a
 272         nice human-readable name of the container.
 273         For all other containers, the content is not defined (yet).
 274 border (string)::
 275         Can be either "normal", "none" or "1pixel", dependending on the
 276         container’s border style.
 277 current_border_width (integer)::
 278         Number of pixels of the border width.
 279 layout (string)::
 280         Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or
 281         "output".
 282         Other values might be possible in the future, should we add new
 283         layouts.
 284 orientation (string)::
 285         Can be either "none" (for non-split containers), "horizontal" or
 286         "vertical".
 287         THIS FIELD IS OBSOLETE. It is still present, but your code should not
 288         use it. Instead, rely on the layout field.
 289 percent (float)::
 290         The percentage which this container takes in its parent. A value of
 291         +null+ means that the percent property does not make sense for this
 292         container, for example for the root container.
 293 rect (map)::
 294         The absolute display coordinates for this container. Display
 295         coordinates means that when you have two 1600x1200 monitors on a single
 296         X11 Display (the standard way), the coordinates of the first window on
 297         the second monitor are +{ "x": 1600, "y": 0, "width": 1600, "height":
 298         1200 }+.
 299 window_rect (map)::
 300         The coordinates of the *actual client window* inside its container.
 301         These coordinates are relative to the container and do not include the
 302         window decoration (which is actually rendered on the parent container).
 303         So, when using the +default+ layout, you will have a 2 pixel border on
 304         each side, making the window_rect +{ "x": 2, "y": 0, "width": 632,
 305         "height": 366 }+ (for example).
 306 geometry (map)::
 307         The original geometry the window specified when i3 mapped it. Used when
 308         switching a window to floating mode, for example.
 309 window (integer)::
 310         The X11 window ID of the *actual client window* inside this container.
 311         This field is set to null for split containers or otherwise empty
 312         containers. This ID corresponds to what xwininfo(1) and other
 313         X11-related tools display (usually in hex).
 314 urgent (bool)::
 315         Whether this container (window or workspace) has the urgency hint set.
 316 focused (bool)::
 317         Whether this container is currently focused.
 318
 319 Please note that in the following example, I have left out some keys/values
 320 which are not relevant for the type of the node. Otherwise, the example would
 321 be by far too long (it already is quite long, despite showing only 1 window and
 322 one dock window).
 323
 324 It is useful to have an overview of the structure before taking a look at the
 325 JSON dump:
 326
 327 * root
 328 ** LVDS1
 329 *** topdock
 330 *** content
 331 **** workspace 1
 332 ***** window 1
 333 *** bottomdock
 334 **** dock window 1
 335 ** VGA1
 336
 337 *Example:*
 338 -----------------------
 339 {
 340  "id": 6875648,
 341  "name": "root",
 342  "rect": {
 343    "x": 0,
 344    "y": 0,
 345    "width": 1280,
 346    "height": 800
 347  },
 348  "nodes": [
 349
 350    {
 351     "id": 6878320,
 352     "name": "LVDS1",
 353     "layout": "output",
 354     "rect": {
 355       "x": 0,
 356       "y": 0,
 357       "width": 1280,
 358       "height": 800
 359     },
 360     "nodes": [
 361
 362       {
 363        "id": 6878784,
 364        "name": "topdock",
 365        "layout": "dockarea",
 366        "orientation": "vertical",
 367        "rect": {
 368          "x": 0,
 369          "y": 0,
 370          "width": 1280,
 371          "height": 0
 372        },
 373       },
 374
 375       {
 376        "id": 6879344,
 377        "name": "content",
 378        "rect": {
 379          "x": 0,
 380          "y": 0,
 381          "width": 1280,
 382          "height": 782
 383        },
 384        "nodes": [
 385
 386          {
 387           "id": 6880464,
 388           "name": "1",
 389           "orientation": "horizontal",
 390           "rect": {
 391             "x": 0,
 392             "y": 0,
 393             "width": 1280,
 394             "height": 782
 395           },
 396           "floating_nodes": [],
 397           "nodes": [
 398
 399             {
 400              "id": 6929968,
 401              "name": "#aa0000",
 402              "border": "normal",
 403              "percent": 1,
 404              "rect": {
 405                "x": 0,
 406                "y": 18,
 407                "width": 1280,
 408                "height": 782
 409              }
 410             }
 411
 412           ]
 413          }
 414
 415        ]
 416       },
 417
 418       {
 419        "id": 6880208,
 420        "name": "bottomdock",
 421        "layout": "dockarea",
 422        "orientation": "vertical",
 423        "rect": {
 424          "x": 0,
 425          "y": 782,
 426          "width": 1280,
 427          "height": 18
 428        },
 429        "nodes": [
 430
 431          {
 432           "id": 6931312,
 433           "name": "#00aa00",
 434           "percent": 1,
 435           "rect": {
 436             "x": 0,
 437             "y": 782,
 438             "width": 1280,
 439             "height": 18
 440           }
 441          }
 442
 443        ]
 444       }
 445     ]
 446    }
 447  ]
 448 }
 449 ------------------------
 450
 451 === MARKS reply
 452
 453 The reply consists of a single array of strings for each container that has a
 454 mark. The order of that array is undefined. If more than one container has the
 455 same mark, it will be represented multiple times in the reply (the array
 456 contents are not unique).
 457
 458 If no window has a mark the response will be the empty array [].
 459
 460 === BAR_CONFIG reply
 461
 462 This can be used by third-party workspace bars (especially i3bar, but others
 463 are free to implement compatible alternatives) to get the +bar+ block
 464 configuration from i3.
 465
 466 Depending on the input, the reply is either:
 467
 468 empty input::
 469         An array of configured bar IDs
 470 Bar ID::
 471         A JSON map containing the configuration for the specified bar.
 472
 473 Each bar configuration has the following properties:
 474
 475 id (string)::
 476         The ID for this bar. Included in case you request multiple
 477         configurations and want to differentiate the different replies.
 478 mode (string)::
 479         Either +dock+ (the bar sets the dock window type) or +hide+ (the bar
 480         does not show unless a specific key is pressed).
 481 position (string)::
 482         Either +bottom+ or +top+ at the moment.
 483 status_command (string)::
 484         Command which will be run to generate a statusline. Each line on stdout
 485         of this command will be displayed in the bar. At the moment, no
 486         formatting is supported.
 487 font (string)::
 488         The font to use for text on the bar.
 489 workspace_buttons (boolean)::
 490         Display workspace buttons or not? Defaults to true.
 491 verbose (boolean)::
 492         Should the bar enable verbose output for debugging? Defaults to false.
 493 colors (map)::
 494         Contains key/value pairs of colors. Each value is a color code in hex,
 495         formatted #rrggbb (like in HTML).
 496
 497 The following colors can be configured at the moment:
 498
 499 background::
 500         Background color of the bar.
 501 statusline::
 502         Text color to be used for the statusline.
 503 focused_workspace_text/focused_workspace_bg::
 504         Text color/background color for a workspace button when the workspace
 505         has focus.
 506 active_workspace_text/active_workspace_bg::
 507         Text color/background color for a workspace button when the workspace
 508         is active (visible) on some output, but the focus is on another one.
 509         You can only tell this apart from the focused workspace when you are
 510         using multiple monitors.
 511 inactive_workspace_text/inactive_workspace_bg::
 512         Text color/background color for a workspace button when the workspace
 513         does not have focus and is not active (visible) on any output. This
 514         will be the case for most workspaces.
 515 urgent_workspace_text/urgent_workspace_bar::
 516         Text color/background color for workspaces which contain at least one
 517         window with the urgency hint set.
 518
 519
 520 *Example of configured bars:*
 521 --------------
 522 ["bar-bxuqzf"]
 523 --------------
 524
 525 *Example of bar configuration:*
 526 --------------
 527 {
 528  "id": "bar-bxuqzf",
 529  "mode": "dock",
 530  "position": "bottom",
 531  "status_command": "i3status",
 532  "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
 533  "workspace_buttons": true,
 534  "verbose": false,
 535  "colors": {
 536    "background": "#c0c0c0",
 537    "statusline": "#00ff00",
 538    "focused_workspace_text": "#ffffff",
 539    "focused_workspace_bg": "#000000"
 540  }
 541 }
 542 --------------
 543
 544 === VERSION reply
 545
 546 The reply consists of a single JSON dictionary with the following keys:
 547
 548 major (integer)::
 549         The major version of i3, such as +4+.
 550 minor (integer)::
 551         The minor version of i3, such as +2+. Changes in the IPC interface (new
 552         features) will only occur with new minor (or major) releases. However,
 553         bugfixes might be introduced in patch releases, too.
 554 patch (integer)::
 555         The patch version of i3, such as +1+ (when the complete version is
 556         +4.2.1+). For versions such as +4.2+, patch will be set to +0+.
 557 human_readable (string)::
 558         A human-readable version of i3 containing the precise git version,
 559         build date and branch name. When you need to display the i3 version to
 560         your users, use the human-readable version whenever possible (since
 561         this is what +i3 --version+ displays, too).
 562
 563 *Example:*
 564 -------------------
 565 {
 566    "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
 567    "minor" : 2,
 568    "patch" : 0,
 569    "major" : 4
 570 }
 571 -------------------
 572
 573 == Events
 574
 575 [[events]]
 576
 577 To get informed when certain things happen in i3, clients can subscribe to
 578 events. Events consist of a name (like "workspace") and an event reply type
 579 (like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format
 580 as replies to specific commands. However, the highest bit of the message type
 581 is set to 1 to indicate that this is an event reply instead of a normal reply.
 582
 583 Caveat: As soon as you subscribe to an event, it is not guaranteed any longer
 584 that the requests to i3 are processed in order. This means, the following
 585 situation can happen: You send a GET_WORKSPACES request but you receive a
 586 "workspace" event before receiving the reply to GET_WORKSPACES. If your
 587 program does not want to cope which such kinds of race conditions (an
 588 event based library may not have a problem here), I suggest you create a
 589 separate connection to receive events.
 590
 591 === Subscribing to events
 592
 593 By sending a message of type SUBSCRIBE with a JSON-encoded array as payload
 594 you can register to an event.
 595
 596 *Example:*
 597 ---------------------------------
 598 type: SUBSCRIBE
 599 payload: [ "workspace", "focus" ]
 600 ---------------------------------
 601
 602
 603 === Available events
 604
 605 The numbers in parenthesis is the event type (keep in mind that you need to
 606 strip the highest bit first).
 607
 608 workspace (0)::
 609         Sent when the user switches to a different workspace, when a new
 610         workspace is initialized or when a workspace is removed (because the
 611         last client vanished).
 612 output (1)::
 613         Sent when RandR issues a change notification (of either screens,
 614         outputs, CRTCs or output properties).
 615 mode (2)::
 616         Sent whenever i3 changes its binding mode.
 617
 618 *Example:*
 619 --------------------------------------------------------------------
 620 # the appropriate 4 bytes read from the socket are stored in $input
 621
 622 # unpack a 32-bit unsigned integer
 623 my $message_type = unpack("L", $input);
 624
 625 # check if the highest bit is 1
 626 my $is_event = (($message_type >> 31) == 1);
 627
 628 # use the other bits
 629 my $event_type = ($message_type & 0x7F);
 630
 631 if ($is_event) {
 632   say "Received event of type $event_type";
 633 }
 634 --------------------------------------------------------------------
 635
 636 === workspace event
 637
 638 This event consists of a single serialized map containing a property
 639 +change (string)+ which indicates the type of the change ("focus", "init",
 640 "empty", "urgent").
 641
 642 *Example:*
 643 ---------------------
 644 { "change": "focus" }
 645 ---------------------
 646
 647 === output event
 648
 649 This event consists of a single serialized map containing a property
 650 +change (string)+ which indicates the type of the change (currently only
 651 "unspecified").
 652
 653 *Example:*
 654 ---------------------------
 655 { "change": "unspecified" }
 656 ---------------------------
 657
 658 === mode event
 659
 660 This event consists of a single serialized map containing a property
 661 +change (string)+ which holds the name of current mode in use. The name
 662 is the same as specified in config when creating a mode. The default
 663 mode is simply named default.
 664
 665 *Example:*
 666 ---------------------------
 667 { "change": "default" }
 668 ---------------------------
 669
 670 == See also
 671
 672 For some languages, libraries are available (so you don’t have to implement
 673 all this on your own). This list names some (if you wrote one, please let me
 674 know):
 675
 676 C::
 677         i3 includes a headerfile +i3/ipc.h+ which provides you all constants.
 678         However, there is no library yet.
 679 Ruby::
 680         http://github.com/badboy/i3-ipc
 681 Perl::
 682         https://metacpan.org/module/AnyEvent::I3
 683 Python::
 684         * https://github.com/whitelynx/i3ipc
 685         * https://github.com/ziberna/i3-py (includes higher-level features)