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

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