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