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

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