git.sur5r.net Git - i3/i3.github.io/blob - _docs/ipc

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