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 layout (string)::
 278         Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or
 279         "output".
 280         Other values might be possible in the future, should we add new
 281         layouts.
 282 orientation (string)::
 283         Can be either "none" (for non-split containers), "horizontal" or
 284         "vertical".
 285         THIS FIELD IS OBSOLETE. It is still present, but your code should not
 286         use it. Instead, rely on the layout field.
 287 percent (float)::
 288         The percentage which this container takes in its parent. A value of
 289         +null+ means that the percent property does not make sense for this
 290         container, for example for the root container.
 291 rect (map)::
 292         The absolute display coordinates for this container. Display
 293         coordinates means that when you have two 1600x1200 monitors on a single
 294         X11 Display (the standard way), the coordinates of the first window on
 295         the second monitor are +{ "x": 1600, "y": 0, "width": 1600, "height":
 296         1200 }+.
 297 window_rect (map)::
 298         The coordinates of the *actual client window* inside its container.
 299         These coordinates are relative to the container and do not include the
 300         window decoration (which is actually rendered on the parent container).
 301         So, when using the +default+ layout, you will have a 2 pixel border on
 302         each side, making the window_rect +{ "x": 2, "y": 0, "width": 632,
 303         "height": 366 }+ (for example).
 304 geometry (map)::
 305         The original geometry the window specified when i3 mapped it. Used when
 306         switching a window to floating mode, for example.
 307 window (integer)::
 308         The X11 window ID of the *actual client window* inside this container.
 309         This field is set to null for split containers or otherwise empty
 310         containers. This ID corresponds to what xwininfo(1) and other
 311         X11-related tools display (usually in hex).
 312 urgent (bool)::
 313         Whether this container (window or workspace) has the urgency hint set.
 314 focused (bool)::
 315         Whether this container is currently focused.
 316
 317 Please note that in the following example, I have left out some keys/values
 318 which are not relevant for the type of the node. Otherwise, the example would
 319 be by far too long (it already is quite long, despite showing only 1 window and
 320 one dock window).
 321
 322 It is useful to have an overview of the structure before taking a look at the
 323 JSON dump:
 324
 325 * root
 326 ** LVDS1
 327 *** topdock
 328 *** content
 329 **** workspace 1
 330 ***** window 1
 331 *** bottomdock
 332 **** dock window 1
 333 ** VGA1
 334
 335 *Example:*
 336 -----------------------
 337 {
 338  "id": 6875648,
 339  "name": "root",
 340  "rect": {
 341    "x": 0,
 342    "y": 0,
 343    "width": 1280,
 344    "height": 800
 345  },
 346  "nodes": [
 347
 348    {
 349     "id": 6878320,
 350     "name": "LVDS1",
 351     "layout": "output",
 352     "rect": {
 353       "x": 0,
 354       "y": 0,
 355       "width": 1280,
 356       "height": 800
 357     },
 358     "nodes": [
 359
 360       {
 361        "id": 6878784,
 362        "name": "topdock",
 363        "layout": "dockarea",
 364        "orientation": "vertical",
 365        "rect": {
 366          "x": 0,
 367          "y": 0,
 368          "width": 1280,
 369          "height": 0
 370        },
 371       },
 372
 373       {
 374        "id": 6879344,
 375        "name": "content",
 376        "rect": {
 377          "x": 0,
 378          "y": 0,
 379          "width": 1280,
 380          "height": 782
 381        },
 382        "nodes": [
 383
 384          {
 385           "id": 6880464,
 386           "name": "1",
 387           "orientation": "horizontal",
 388           "rect": {
 389             "x": 0,
 390             "y": 0,
 391             "width": 1280,
 392             "height": 782
 393           },
 394           "floating_nodes": [],
 395           "nodes": [
 396
 397             {
 398              "id": 6929968,
 399              "name": "#aa0000",
 400              "border": "normal",
 401              "percent": 1,
 402              "rect": {
 403                "x": 0,
 404                "y": 18,
 405                "width": 1280,
 406                "height": 782
 407              }
 408             }
 409
 410           ]
 411          }
 412
 413        ]
 414       },
 415
 416       {
 417        "id": 6880208,
 418        "name": "bottomdock",
 419        "layout": "dockarea",
 420        "orientation": "vertical",
 421        "rect": {
 422          "x": 0,
 423          "y": 782,
 424          "width": 1280,
 425          "height": 18
 426        },
 427        "nodes": [
 428
 429          {
 430           "id": 6931312,
 431           "name": "#00aa00",
 432           "percent": 1,
 433           "rect": {
 434             "x": 0,
 435             "y": 782,
 436             "width": 1280,
 437             "height": 18
 438           }
 439          }
 440
 441        ]
 442       }
 443     ]
 444    }
 445  ]
 446 }
 447 ------------------------
 448
 449 === MARKS reply
 450
 451 The reply consists of a single array of strings for each container that has a
 452 mark. The order of that array is undefined. If more than one container has the
 453 same mark, it will be represented multiple times in the reply (the array
 454 contents are not unique).
 455
 456 If no window has a mark the response will be the empty array [].
 457
 458 === BAR_CONFIG reply
 459
 460 This can be used by third-party workspace bars (especially i3bar, but others
 461 are free to implement compatible alternatives) to get the +bar+ block
 462 configuration from i3.
 463
 464 Depending on the input, the reply is either:
 465
 466 empty input::
 467         An array of configured bar IDs
 468 Bar ID::
 469         A JSON map containing the configuration for the specified bar.
 470
 471 Each bar configuration has the following properties:
 472
 473 id (string)::
 474         The ID for this bar. Included in case you request multiple
 475         configurations and want to differentiate the different replies.
 476 mode (string)::
 477         Either +dock+ (the bar sets the dock window type) or +hide+ (the bar
 478         does not show unless a specific key is pressed).
 479 position (string)::
 480         Either +bottom+ or +top+ at the moment.
 481 status_command (string)::
 482         Command which will be run to generate a statusline. Each line on stdout
 483         of this command will be displayed in the bar. At the moment, no
 484         formatting is supported.
 485 font (string)::
 486         The font to use for text on the bar.
 487 workspace_buttons (boolean)::
 488         Display workspace buttons or not? Defaults to true.
 489 verbose (boolean)::
 490         Should the bar enable verbose output for debugging? Defaults to false.
 491 colors (map)::
 492         Contains key/value pairs of colors. Each value is a color code in hex,
 493         formatted #rrggbb (like in HTML).
 494
 495 The following colors can be configured at the moment:
 496
 497 background::
 498         Background color of the bar.
 499 statusline::
 500         Text color to be used for the statusline.
 501 focused_workspace_text/focused_workspace_bg::
 502         Text color/background color for a workspace button when the workspace
 503         has focus.
 504 active_workspace_text/active_workspace_bg::
 505         Text color/background color for a workspace button when the workspace
 506         is active (visible) on some output, but the focus is on another one.
 507         You can only tell this apart from the focused workspace when you are
 508         using multiple monitors.
 509 inactive_workspace_text/inactive_workspace_bg::
 510         Text color/background color for a workspace button when the workspace
 511         does not have focus and is not active (visible) on any output. This
 512         will be the case for most workspaces.
 513 urgent_workspace_text/urgent_workspace_bar::
 514         Text color/background color for workspaces which contain at least one
 515         window with the urgency hint set.
 516
 517
 518 *Example of configured bars:*
 519 --------------
 520 ["bar-bxuqzf"]
 521 --------------
 522
 523 *Example of bar configuration:*
 524 --------------
 525 {
 526  "id": "bar-bxuqzf",
 527  "mode": "dock",
 528  "position": "bottom",
 529  "status_command": "i3status",
 530  "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
 531  "workspace_buttons": true,
 532  "verbose": false,
 533  "colors": {
 534    "background": "#c0c0c0",
 535    "statusline": "#00ff00",
 536    "focused_workspace_text": "#ffffff",
 537    "focused_workspace_bg": "#000000"
 538  }
 539 }
 540 --------------
 541
 542 === VERSION reply
 543
 544 The reply consists of a single JSON dictionary with the following keys:
 545
 546 major (integer)::
 547         The major version of i3, such as +4+.
 548 minor (integer)::
 549         The minor version of i3, such as +2+. Changes in the IPC interface (new
 550         features) will only occur with new minor (or major) releases. However,
 551         bugfixes might be introduced in patch releases, too.
 552 patch (integer)::
 553         The patch version of i3, such as +1+ (when the complete version is
 554         +4.2.1+). For versions such as +4.2+, patch will be set to +0+.
 555 human_readable (string)::
 556         A human-readable version of i3 containing the precise git version,
 557         build date and branch name. When you need to display the i3 version to
 558         your users, use the human-readable version whenever possible (since
 559         this is what +i3 --version+ displays, too).
 560
 561 *Example:*
 562 -------------------
 563 {
 564    "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
 565    "minor" : 2,
 566    "patch" : 0,
 567    "major" : 4
 568 }
 569 -------------------
 570
 571 == Events
 572
 573 [[events]]
 574
 575 To get informed when certain things happen in i3, clients can subscribe to
 576 events. Events consist of a name (like "workspace") and an event reply type
 577 (like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format
 578 as replies to specific commands. However, the highest bit of the message type
 579 is set to 1 to indicate that this is an event reply instead of a normal reply.
 580
 581 Caveat: As soon as you subscribe to an event, it is not guaranteed any longer
 582 that the requests to i3 are processed in order. This means, the following
 583 situation can happen: You send a GET_WORKSPACES request but you receive a
 584 "workspace" event before receiving the reply to GET_WORKSPACES. If your
 585 program does not want to cope which such kinds of race conditions (an
 586 event based library may not have a problem here), I suggest you create a
 587 separate connection to receive events.
 588
 589 === Subscribing to events
 590
 591 By sending a message of type SUBSCRIBE with a JSON-encoded array as payload
 592 you can register to an event.
 593
 594 *Example:*
 595 ---------------------------------
 596 type: SUBSCRIBE
 597 payload: [ "workspace", "focus" ]
 598 ---------------------------------
 599
 600
 601 === Available events
 602
 603 The numbers in parenthesis is the event type (keep in mind that you need to
 604 strip the highest bit first).
 605
 606 workspace (0)::
 607         Sent when the user switches to a different workspace, when a new
 608         workspace is initialized or when a workspace is removed (because the
 609         last client vanished).
 610 output (1)::
 611         Sent when RandR issues a change notification (of either screens,
 612         outputs, CRTCs or output properties).
 613 mode (2)::
 614         Sent whenever i3 changes its binding mode.
 615
 616 *Example:*
 617 --------------------------------------------------------------------
 618 # the appropriate 4 bytes read from the socket are stored in $input
 619
 620 # unpack a 32-bit unsigned integer
 621 my $message_type = unpack("L", $input);
 622
 623 # check if the highest bit is 1
 624 my $is_event = (($message_type >> 31) == 1);
 625
 626 # use the other bits
 627 my $event_type = ($message_type & 0x7F);
 628
 629 if ($is_event) {
 630   say "Received event of type $event_type";
 631 }
 632 --------------------------------------------------------------------
 633
 634 === workspace event
 635
 636 This event consists of a single serialized map containing a property
 637 +change (string)+ which indicates the type of the change ("focus", "init",
 638 "empty", "urgent").
 639
 640 *Example:*
 641 ---------------------
 642 { "change": "focus" }
 643 ---------------------
 644
 645 === output event
 646
 647 This event consists of a single serialized map containing a property
 648 +change (string)+ which indicates the type of the change (currently only
 649 "unspecified").
 650
 651 *Example:*
 652 ---------------------------
 653 { "change": "unspecified" }
 654 ---------------------------
 655
 656 === mode event
 657
 658 This event consists of a single serialized map containing a property
 659 +change (string)+ which holds the name of current mode in use. The name
 660 is the same as specified in config when creating a mode. The default
 661 mode is simply named default.
 662
 663 *Example:*
 664 ---------------------------
 665 { "change": "default" }
 666 ---------------------------
 667
 668 == See also
 669
 670 For some languages, libraries are available (so you don’t have to implement
 671 all this on your own). This list names some (if you wrote one, please let me
 672 know):
 673
 674 C::
 675         i3 includes a headerfile +i3/ipc.h+ which provides you all constants.
 676         However, there is no library yet.
 677 Ruby::
 678         http://github.com/badboy/i3-ipc
 679 Perl::
 680         https://metacpan.org/module/AnyEvent::I3
 681 Python::
 682         * https://github.com/whitelynx/i3ipc
 683         * https://github.com/ziberna/i3-py (includes higher-level features)