XCB监听X11窗口事件：从掩码订阅到事件循环的全指南-平芜编程栈

直接说结论：在 Linux 桌面上想盯住某个外部程序的窗口什么时候出现、什么时候消失、标题什么时候变了，第一反应常常是轮询——每 100ms 扫一遍窗口列表。我也这么干过，代码倒是简单，但是延迟、漏事件、CPU 占用高，尤其窗口一闪而过的时候，根本来不及记录。后来我把整套逻辑切到 XCB 上，才发现窗口事件的监听在 X11 协议层本来就是设计好的功能，只是很少有人把这块梳理清楚。这篇文章就围绕 xcb 监听窗口这件事，把事件掩码、订阅关系、事件循环和实际调试中踩过的坑完整过一遍，适合想写窗口管理辅助工具、自动化脚本或者桌面小部件的人参考。

1. 先回答一个关键问题：为什么是 XCB 而不是 Xlib

老一批 Linux 下的 X11 客户端程序，基本都是用 Xlib 写的。Xlib 历史悠久，资料多，网上随便一搜就是几十年前的代码片段。但如果你真的拿它来监听窗口事件，用不了多久就会难受起来。Xlib 的模型是同步阻塞式的，调用 XNextEvent 的时候，整个线程会卡在那个调用上，直到有事件到达。这在老式单线程程序里问题不大，可一旦你需要在同一个线程里同时处理窗口事件、网络消息、UI 刷新，就会被迫开线程、加锁，最后陷入各种诡异的数据竞争里。之前我就在一个工具里试过用 Xlib 监听窗口创建，结果程序动不动就卡死在事件等待上，注释里翻来覆去全是"不知道哪里卡了"的痕迹。

XCB 的价值在于它从一开始就是异步明文协议风格的。它不像 Xlib 那样把很多细节埋进封装层，而是尽量和 X11 协议一一对应。它把请求和回复拆成 cookie，发出请求之后不阻塞，回复到了你再取。事件读取也分阻塞和非阻塞两种方式，可以配合 select/poll 统一管理文件描述符。对我来说最直观的体验是：用 XCB 写的监听程序，事件循环与业务逻辑就可以干净地拆开，不会因为一个阻塞调用把整条链路拖死。

下面这个对比表可以帮你快速判断自己的项目该用哪条路：

对比维度	Xlib	XCB
API 模型	同步阻塞，调用结果立等返回	异步非阻塞，请求与回复分离
线程友好度	并发访问需要显式加锁	天然适合单线程事件循环 + 工作线程
协议贴合度	封装层较厚，细节被隐藏	与 X11 协议字段几乎一一对应
错误处理	全局错误钩子，定位困难	请求关联错误，可按上下文处理
事件读取	XNextEvent 逐个阻塞读取	wait/poll 两种模式，灵活控制

另外还有一点很实在：Xlib 本身就基于 XCB 实现。也就是说，底层协议沟通并没有本质区别，区别主要在 API 的取舍和事件处理的灵活性上。你如果只是想画个窗口显示点内容，Xlib 也能用；但如果核心需求就是监听窗口事件、解析窗口状态、做自动化联动，选 XCB 会省掉很多堵塞和锁带来的麻烦。

2. 窗口事件的分发规则：掩码、类型与订阅关系

在动手写代码之前，一定要先搞清楚一件事：X11 里的窗口事件不是广播式的。你在一个进程里监听窗口，不代表所有窗口的变化都会通知给你。X server 负责维护窗口树和输入状态，客户端必须先在某个窗口上"订阅"对应类型的事件，之后这个窗口（或其子窗口）发生相关变化时，X server 才会把事件投递到你的连接上。

这个订阅动作就是 xcb_select_input。它做的事情非常直白：给某个窗口设置一组事件掩码。掩码决定了你要不要关心这扇窗口上的某类事件。比如窗口被映射到屏幕上、被销毁、大小变了、属性变了，这些都是不同的事件类型，对应不同的掩码位。你订阅了什么，才会收到什么；没订阅的，哪怕发生一百遍，你也一无所知。

2.1 事件不是广播，更像是"门牌订阅"

我经常用一个类比来解释这个机制：X server 是大楼物业，每个窗口是一间房，你是住在物业办公室里的观察员。物业不可能把大楼里每一扇门开关、每一个灯泡亮灭都实时汇报给你，那样消息量太大。你只能在感兴趣的房门口挂一块牌子，写上"这间房的门开关通知我"或者"这间房换灯泡了通知我"。牌子上的内容，就是事件掩码。你没有挂牌的房子，发生任何事都和你无关。

所以监听窗口的第一步永远不是写循环，而是想清楚你要监听哪个窗口、要监听哪一类变化。这两个问题没想清楚，后面代码写得再漂亮也是白搭。

2.2 掩码就是你的订阅单

实际开发中常用的事件掩码就三组，但它们的含义经常被搞混：

XCB_EVENT_MASK_STRUCTURE_NOTIFY：订阅窗口自身的结构变化，包括被映射、被取消映射、被销毁、被移动或调整大小、被重新设置父窗口。注意，这个掩码只对你指定的窗口本身生效。
XCB_EVENT_MASK_SUBSTRUCTURE_NOTIFY：订阅指定窗口的子窗口的结构变化。也就是说，父窗口上挂了这块牌子，它的直接子窗口发生映射、销毁、移动时，你也能收到事件。这是我们监听"所有新窗口出现"的核心掩码。
XCB_EVENT_MASK_PROPERTY_CHANGE：订阅窗口属性的变化，比如标题变化、窗口类型变化、PID 属性被设置等。监听标题变化和窗口状态变化时全靠它。

再对照一下常见的窗口事件类型，方便后面看日志时一眼认出是在处理什么：

事件类型	数值	掩码依赖	触发时机
CreateNotify	16	SubstructureNotify	窗口创建完成
DestroyNotify	17	StructureNotify / SubstructureNotify	窗口被销毁前
MapNotify	19	StructureNotify / SubstructureNotify	窗口映射到屏幕
UnmapNotify	18	StructureNotify / SubstructureNotify	窗口取消映射
ConfigureNotify	22	StructureNotify / SubstructureNotify	窗口移动、调整大小
PropertyNotify	28	PropertyChange	窗口属性发生变化

这里面最值得记住的是 CreateNotify 依赖 SubstructureNotify 掩码。也就是说，如果你想监听的是"所有新窗口创建"这个全局事件，那就要在 root 窗口（即屏幕的根窗口）上设置 SubstructureNotify 掩码，而不是 StructureNotify。很多人第一次写监听程序发现什么都收不到，八成就是在这里栽了跟头。

2.3 事件结构体里的字段怎么读

事件的通用结构是 xcb_generic_event_t，字段里有 response_type，但实际使用时要处理一下。X11 规定 response_type 的高位（0x80 位）表示这个事件是否由 SendEvent 合成，所以真正的事件类型应该用ev->response_type & 0x7f来取。这一点不处理干净，你会看到一些"不应该出现"的事件类型，或者在对不上号的 switch 分支里浪费很多时间。

取出类型之后，根据类型把通用事件指针强转为对应的具体事件结构体。比如 CreateNotify 事件是 xcb_create_notify_event_t，里面有 window 和 parent 两个字段，分别表示新窗口和它的父窗口；DestroyNotify 事件是 xcb_destroy_notify_event_t，同样有 window 和 parent；PropertyNotify 事件是 xcb_property_notify_event_t，里面有 window、atom、state。有了这些字段，你才谈得上去判断"是哪个窗口动了、动了什么"。

3. 第一个可运行版本：监听全局窗口的创建与销毁

理解了掩码规则之后，写一个最基础的全局监听程序其实就是三步：连接 X server、在 root 窗口上设置 SubstructureNotify 掩码、进入事件循环。这套代码可以作为模板反复使用，后面所有高级监听都是在它的基础上加判断条件的。

3.1 代码骨架：从连接到事件循环

下面是一段完整可编译的最小监听程序。它不做任何业务处理，只是把窗口创建、销毁、映射三种事件打出来。

#include <stdio.h> #include <stdlib.h> #include <xcb/xcb.h> int main(void) { int screen_num = 0; xcb_connection_t *conn = xcb_connect(NULL, &screen_num); if (xcb_connection_has_error(conn)) { fprintf(stderr, "无法连接 X server\n"); return 1; } const xcb_setup_t *setup = xcb_get_setup(conn); xcb_screen_iterator_t iter = xcb_setup_roots_iterator(setup); xcb_screen_t *screen = iter.data; uint32_t mask = XCB_EVENT_MASK_SUBSTRUCTURE_NOTIFY; xcb_select_input(conn, screen->root, mask); xcb_flush(conn); printf("监听中，root 窗口 0x%08x\n", screen->root); xcb_generic_event_t *ev; while ((ev = xcb_wait_for_event(conn)) != NULL) { int type = ev->response_type & 0x7f; switch (type) { case XCB_CREATE_NOTIFY: { xcb_create_notify_event_t *e = (xcb_create_notify_event_t *)ev; printf("CreateNotify: 新窗口 0x%08x, 父窗口 0x%08x\n", e->window, e->parent); break; } case XCB_DESTROY_NOTIFY: { xcb_destroy_notify_event_t *e = (xcb_destroy_notify_event_t *)ev; printf("DestroyNotify: 窗口 0x%08x 被销毁\n", e->window); break; } case XCB_MAP_NOTIFY: { xcb_map_notify_event_t *e = (xcb_map_notify_event_t *)ev; printf("MapNotify: 窗口 0x%08x 已映射到屏幕\n", e->window); break; } default: break; } free(ev); } xcb_disconnect(conn); return 0; }

代码里有两个细节值得多说一句。一是 xcb_connect 的第二个参数传入 screen_num，是为了同时拿到默认屏幕的编号，方便后续从 setup 里获取 root 窗口。二是循环里拿到的事件指针用完之后一定要 free。xcb_wait_for_event 返回的指针指向的是动态分配的缓冲区，不释放的话，一个监听程序跑几个小时，内存占用会一路涨上去。这个坑后面还会再提到。

3.2 编译与验证

编译命令很简单，用 pkg-config 拿编译参数就行：

gcc watch.c -o watch $(pkg-config --cflags --libs xcb)

运行之后另开一个终端，随便启动一个图形程序，比如系统自带的文本编辑器。正常情况下你会立刻在终端里看到 CreateNotify 输出，关闭程序时看到 DestroyNotify。这里要注意一个现象：你看到的 CreateNotify 对应的"新窗口"不一定是程序的主窗口，还可能是各种辅助窗口、提示窗、输入法候选窗。因为 root 窗口下的所有直接子窗口创建都会触发事件，而这些子窗口可能只是装饰性的 frame 窗口。

如果运行之后什么都看不到，先检查三件事：是否在 root 窗口上设置的是 SubstructureNotify；事件类型是否取了& 0x7f；程序是否因为 X server 权限问题压根没连上。绝大多数情况下，前两个问题就能命中九成的原因。

4. 精确到某个窗口：属性变化、子窗口和标题监测

全局监听能帮你掌握窗口的"生老病死"，但很多实际需求是更精确的：盯住某个特定程序的主窗口，获取它的标题变化，或者监听它的所有子窗口。举个例子，我做一个窗口状态监视工具时，需要持续跟踪某个应用的主窗口是否最小化、标题是否变化。这个需求就不能只靠 root 监听，还要拿到目标窗口的 ID，然后在目标窗口上单独设置掩码。

4.1 先搞清楚目标窗口的 ID 从哪来

获取窗口 ID 的方式有好几种，最常用的是从 root 窗口的属性 _NET_CLIENT_LIST 里读取。这个是 Extended Window Manager Hints（EWMH）规范里约定的属性，桌面环境和窗口管理器都会维护它，里面存的是当前所有顶层窗口的 XID 列表。你也可以用 xwininfo 这类命令行工具去点选窗口，或者通过 xcb_query_tree 从 root 递归遍历整棵窗口树，找到名字匹配的窗口。

我在实际项目中用的是后一种方式：先用 xcb_query_tree 获取 root 的直接子窗口列表，逐个读取窗口名称（_NET_WM_NAME 或 WM_NAME），匹配到目标进程的窗口标题之后，记下它的 XID。这个过程表面上是在"搜索"，本质上是主动遍历 + 属性查询，和各就各位的订阅没有冲突。

4.2 在目标窗口上挂掩码并处理 PropertyNotify

拿到 XID 之后，监听就变成了这样：

uint32_t mask = XCB_EVENT_MASK_STRUCTURE_NOTIFY | XCB_EVENT_MASK_PROPERTY_CHANGE; xcb_select_input(conn, target_window, mask); xcb_flush(conn);

这里用 StructureNotify 是为了感知目标窗口自身的映射、销毁、移动和缩放。用 PropertyChange 是为了感知它的属性变化。属性变化事件里最常用的是标题变化，也就是 _NET_WM_NAME 发生变化。处理 PropertyNotify 时，事件结构体里的 atom 字段会告诉你哪个属性变了。判断具体是不是目标属性，不是直接用字符串比较，而是提前把字符串变成 Atom 再比较。因为 X server 内部用整数 ID 表示属性名，频繁做字符串比较既慢又容易出错。

预取 Atom 的代码片段：

static xcb_atom_t get_atom(xcb_connection_t *conn, const char *name) { xcb_intern_atom_cookie_t cookie = xcb_intern_atom(conn, 0, strlen(name), name); xcb_intern_atom_reply_t *reply = xcb_intern_atom_reply(conn, cookie, NULL); xcb_atom_t atom = reply ? reply->atom : XCB_ATOM_NONE; free(reply); return atom; }

事件循环里处理属性变化：

case XCB_PROPERTY_NOTIFY: { xcb_property_notify_event_t *e = (xcb_property_notify_event_t *)ev; if (e->atom == net_wm_name_atom) { printf("窗口 0x%08x 标题发生变化\n", e->window); } break; }

需要读取新标题时，再走一次 xcb_get_property，请求 _NET_WM_NAME 的值，解析返回字节流就是字符串。实测下来，这套逻辑非常稳定，标题每次变化都能精确捕获，而且因为只订阅了需要的属性，丢事件概率很小。

4.3 递归订阅子窗口的两个注意点

如果你需要监听某个应用的所有子窗口（比如像文档编辑器里的浮动工具窗），XCB 的 SubstructNotify 只能覆盖直接子窗口，孙子级窗口需要递归遍历窗口树之后逐个设置掩码。这个"逐层订阅"的规则非常关键，写递归的时候要小心，别陷入死循环或者重复订阅。

我做遍历时用的是 xcb_query_tree，拿到窗口的所有子窗口 XID，对每个子窗口再递归查询。每到一个窗口都用 xcb_select_input 设置掩码，并且把 XID 记录到一个数组里，避免同一个窗口被订阅两次。这个方案在窗口数量较少的应用上效果很好，但在窗口大量频繁创建的场景下，要注意每个 select_input 都是一次往返请求，太频繁会拖慢整个监听程序甚至影响目标应用。

对于大多数场景，我更推荐"按需订阅"：先只监听目标主窗口，到它的某个事件触发了，比如 ConfigureNotify 说它的子窗口数量变了，再重新遍历一次窗口树补充订阅。这个策略可以在事件实时性和网络开销之间拿到一个比较好的平衡点。

5. 踩坑记录：事件不触发、属性风暴与 reparent 问题

任何协议层面的开发，光看文档是不够的，真机调试才会暴露那些文档不会写的问题。下面这几个坑是我在实际监听项目里踩过并解决的，每一项背后都有一段从"现象异常"到"逐步排查"的完整过程。把这些记录整理出来，希望你能少走几趟弯路。

5.1 事件总是收不到，root 掩码设错了对象

最开始踩的坑就是掩码对象搞混。我在 root 窗口上设置了 XCB_EVENT_MASK_STRUCTURE_NOTIFY，期待着能捕获到新窗口的创建。结果运行半天，什么都等不到。原因在上面已经说过：StructureNotify 只会告诉你"root 窗口自己"的结构变化，你不能指望它报告子窗口的消息。root 窗口本身基本不会移动、不会销毁，所以在它身上挂 StructureNotify 等于什么都没订阅。

排查链路值得复述一遍：先确认窗口树里程序主窗口的父子关系，用xwininfo -root -tree能看到当前所有窗口的父子结构；然后在 root 上分别测试 StructureNotify 和 SubstructureNotify；最后把一个普通顶层窗口挂上 SubstructureNotify，看能不能收到它子窗口的事件。这么一轮下来，掩码和监听对象的关系就彻底摸清了。这件事之后，我在代码注释里明确写了一句：监听全局窗口，用 SubstructureNotify + root。

5.2 PropertyNotify 刷屏，必须过滤 Atom

第二个隐蔽问题出现在属性监听阶段。给目标窗口挂上 PropertyChange 掩码之后，终端像疯了一样刷事件。原因很简单：窗口属性远不止标题一个，光标形状变化、焦点状态变化、提示信息切换，全都会触发 PropertyNotify。如果你不检查 event 里的 atom 是不是你关心的那个，就会收到大量噪音事件。

我的解决办法是在事件分发的最前面加一层过滤。维护一个需要关心的 atom 数组，事件进来先比对，不是关心的直接跳过。这样即使在窗口频繁切换状态的场景下，最终进入业务处理逻辑的事件数量也少得可怜。顺便说一句，过滤 atom 比对的是整数，不是字符串，开销极小，千万别把字符串比较混进去。

5.3 窗口 ID 不等于进程 ID，别搞混

X11 里的窗口 XID 是 X server 分配的资源编号，和进程 PID 没有半毛钱关系。我在解析 CreateNotify 事件时，一度想当然地以为拿到窗口 ID 就能一并发启动它的进程。结果自然是查无此进程。排查过程中才意识到，进程关联需要从窗口属性 _NET_WM_PID 里读取。

如果应用没有设置这个属性，就只能靠窗口标题、窗口类型或者 WM_CLASS 来做模糊匹配。这里有个现实的坑：某些应用会把多个进程共用一个窗口，或者子进程窗口继承父进程环境，导致 _NET_WM_PID 指向的进程并不符合直觉。所以根据 PID 反查进程只是"尽力而为"，不能作为唯一判据。我在项目里把 PID 当作辅助信息，主要匹配逻辑还是用 WM_CLASS 和窗口标题。

5.4 reparent 让 CreateNotify 的 window 不是你要的主窗口

现代桌面环境下，窗口管理器通常会把程序的顶层窗口"包装"进一个 frame 窗口。这个 frame 窗口才是 root 的子窗口，而程序真正的窗口变成了 frame 的子窗口。于是 CreateNotify 事件里你看到的 window 可能是窗口管理器生成的装饰框，而不是目标程序的主窗口。如果直接拿这个 XID 去请求属性，可能得到的是一堆无效信息。

排查这个问题的过程挺有意思：我打印出 CreateNotify 的 window 后，用 xcb_query_tree 查看它的子窗口，才发现真正的应用窗口在它的下一层。解决方案分两种：一是收到事件后，对 window 做一次属性尝试（比如读 WM_CLASS），如果读不到，就往下遍历一层再尝试；二是不依赖某个特定窗口 ID，而是监控整个 frame 窗口的子树变化。做窗口自动化时，第二种方式更稳，因为窗口管理器会在什么时候重新包装窗口并不完全可控，我们要适应它，而不是跟它对抗。

5.5 在混合显示环境下的兜底策略

这个坑更像是一种"环境假设偏差"。我把监听程序放在一个常见的 Wayland 合成器环境下做验证时，发现某些 X11 窗口的最小化、恢复状态变化表现得并不规律，甚至会出现事件缺失，比如最小化按钮点了，UnmapNotify 却没来。后来才意识到，程序运行在 XWayland 兼容层里，窗口状态的部分变化被合成器接管了，传统的 X11 结构事件并不能完整覆盖所有状态切换。

面对这种情况，我的处理手段很直接：主逻辑仍然走 XCB 事件驱动，但额外引入一个低频轮询作为兜底，每 1 到 2 秒检查一次窗口的 _NET_WM_STATE 属性。事件流正常时，轮询几乎不会触发额外逻辑；事件缺失时，轮询能保证状态不会长时间停留在错误认知里。这个"事件驱动为主、低频轮询兜底"的组合，在混合显示环境里实测下来非常稳，也不会有性能问题。

6. 从监听到联动：几个可直接落地的扩展思路

基础监听能跑通之后，整个程序的想象空间就打开了。同样一套事件循环，我可以根据实际需求自由扩展业务逻辑。这里整理几个我实际做过的扩展方向，每一个都有明确的落地价值。

6.1 事件驱动替代轮询，让 CPU 占用率几乎归零

监听窗口创建这种场景，最常见的传统写法是每 100ms 查询一次窗口列表再 diff。但窗口事件驱动的方式是：窗口创建那一瞬间，事件就到了，根本不需要周期性唤醒。我把一个窗口监视工具的轮询逻辑全部换成 XCB 事件驱动之后，程序空闲时 CPU 占用从 3%~5% 降到了接近 0%。这在低配置机器上是有实际意义的，尤其要长期驻留后台的工具，这种差别非常明显。

实现上也简单，事件循环本身不需要定时器，只需要在收到事件后做处理。如果业务逻辑里确实需要定期做别的事情，可以用第 3 章提到的 select/poll 方式给事件循环加超时，把定时任务和事件监听融合在一个循环里。

int fd = xcb_get_file_descriptor(conn); struct timeval timeout = {1, 0}; // 1 秒超时 fd_set fds; while (1) { FD_ZERO(&fds); FD_SET(fd, &fds); if (select(fd + 1, &fds, NULL, NULL, &timeout) > 0) { xcb_generic_event_t *ev; while ((ev = xcb_poll_for_event(conn)) != NULL) { handle_event(conn, ev); free(ev); } } // 到这里可以执行一次周期性的检查任务 }

6.2 结合 EWMH 属性实现全局状态感知

全局监听与窗口属性读取是互补的两个手段。监听能告诉你"什么时候变了"，属性读取能告诉你"现在是什么状态"。比如我在做某跨平台自动化工具时，需要一个"当前激活窗口"的实时查询能力。这个能力不依赖监听，直接读 root 窗口的 _NET_ACTIVE_WINDOW 属性就能拿到激活窗口的 XID；但要感知"激活窗口切换了"这个动作，就需要在 root 窗口上订阅 PropertyNotify，并且关注 _NET_ACTIVE_WINDOW 这个 atom。两种手段一结合，既能主动查询又能被动感知，工具的整体响应速度会提升一个档次。

用同样的组合，还可以做很多场景化联动：某个程序窗口打开就自动弹出通知；某个窗口标题变化就自动同步到远端状态栏；某个窗口被销毁就自动清理关联资源。这些逻辑本质上都是同一个事件循环里加上若干条件分支。