wezterm.procinfo.get_info_for_pid() 进程信息查询 API 详解：从 PID 到完整进程树的 Lua 实战指南

wezterm.procinfo.get_info_for_pid() 进程信息查询 API 详解从 PID 到完整进程树的 Lua 实战指南【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm本篇指南围绕 WezTerm 终端模拟器的 Lua APIwezterm.procinfo.get_info_for_pid()展开讲解如何仅凭一个进程 IDPID查询到该进程的完整信息——包括可执行文件路径、命令行参数、工作目录、进程状态以及其全部子进程构成的进程树。读者将掌握该函数的调用方式、返回对象LocalProcessInfo的每一个字段含义并通过源码理解其在 Linux、macOS、Windows 三大平台上的底层实现原理从而能在自己的 wezterm.lua 配置中灵活运用进程信息实现高级功能。函数速览wezterm.procinfo.get_info_for_pid()是 wezterm.procinfo 模块 提供的能力之一自版本20220807-113146-c2fee766起可用。它允许从 wezterm 配置的 Lua 脚本中查询本地系统上运行进程的详细信息。local info wezterm.procinfo.get_info_for_pid(pid)参数pid一个正整数即要查询的目标进程 ID。返回值一个 LocalProcessInfo 对象其中携带目标进程自身的信息并通过嵌套结构包含了它的全部子进程查询失败时返回nil例如进程已退出、权限不足或平台不支持。从 Lua 绑定源码看该函数在注册时直接透传给底层实现lua-api-crates/procinfo-funcs/src/lib.rs 中将get_info_for_pid绑定为LocalProcessInfo::with_root_pid(pid)参数类型为u32。同时该模块还暴露了三个同族函数函数返回值说明wezterm.procinfo.pid()数字返回当前进程wezterm 自身的 PID见 pid.mdwezterm.procinfo.get_info_for_pid(pid)LocalProcessInfo / nil返回指定 PID 的进程树信息wezterm.procinfo.current_working_dir_for_pid(pid)字符串 / nil返回指定 PID 的当前工作目录见 current_working_dir_for_pid.mdwezterm.procinfo.executable_path_for_pid(pid)字符串 / nil返回指定 PID 的可执行文件路径见 executable_path_for_pid.md基础用法与官方示例最典型的用法是先通过wezterm.procinfo.pid()拿到 wezterm 自身更准确地说是当前运行 Lua 脚本的进程的 PID再把它传给get_info_for_pid()做查询。官方文档给出了完整返回示例 wezterm.procinfo.get_info_for_pid(wezterm.procinfo.pid()) { argv: [ /home/wez/wez-personal/wezterm/target/debug/wezterm-gui, ], children: { 540513: { argv: [ -zsh, ], children: {}, cwd: /home/wez, executable: /usr/bin/zsh, name: zsh, pid: 540513, ppid: 540450, start_time: 232656896, status: Sleep, }, }, cwd: /home/wez/wez-personal/wezterm, executable: /home/wez/wez-personal/wezterm/target/debug/wezterm-gui, name: wezterm-gui, pid: 540450, ppid: 425276, start_time: 8671498240, status: Run, }从示例中可以清晰地读出两层结构根节点是wezterm-gui进程本身PID 540450而children中嵌套了它的一个子进程zshPID 540513。这说明返回值不是孤立的单个进程快照而是一棵以目标 PID 为根、向下递归完整的进程树。LocalProcessInfo 字段全解析返回对象的类型定义在 docs/config/lua/LocalProcessInfo.md 中有完整说明其结构体实现在 procinfo/src/lib.rs。两者结合每个字段含义如下字段类型含义与注意事项pid数字进程 IDppid数字父进程 IDname字符串进程的短名称。平台限制下可能不准确或被截断许多系统截断到 15~16 个字符且进程运行时可能被setproctitle()等机制修改建议优先使用executable或argv字段executable字符串可执行映像的完整路径某些情况下可能为空字符串argv字符串数组进程的参数数组。部分系统允许进程在运行时改写 argv 块cwd字符串进程当前工作目录无法访问时为空字符串status字符串进程状态枚举取值见下表start_time数字一个系统相关单位的时钟值用于刻画进程的相对年龄如 Linux 上为启动以来的 tick 数children表以子进程 PID 为键、值为嵌套LocalProcessInfo对象的子进程表console仅 Windows数字与进程关联的控制台句柄Windows 专有字段status字段的可取值在源码的LocalProcessStatus枚举中定义procinfo/src/lib.rs包括Idle、Run、Sleep、Stop、Zombie、Tracing、Dead、Wakekill、Waking、Parked、LockBlocked、Unknown。需要注意的是并非所有取值在所有平台都可移植——例如Wakekill、Parked等主要来源于 Linux 内核的进程状态而 Windows 实现中所有进程的状态统一置为Run见下文源码分析。源码级实现原理三大平台如何采集进程信息get_info_for_pid的核心实现在procinfocrate 中按操作系统分别实现了with_root_pid、current_working_dir与executable_path。虽然查询入口一致但三个平台的采集路径差异很大理解这些差异有助于预判跨平台行为。Linux直接解析 /proc 伪文件系统Linux 实现procinfo/src/linux.rs完全基于/proc文件系统枚举全部进程遍历/proc目录下所有纯数字命名的目录作为 PID 候选见all_pids()procinfo/src/linux.rs。读取每个进程的统计信息解析/proc/pid/stat文件提取进程名、状态码、PPID 以及自系统启动以来的启动 tick 数starttime见info_for_pid()procinfo/src/linux.rs。补充路径与参数/proc/pid/exe的符号链接解析出executable/proc/pid/cwd的符号链接解析出cwd/proc/pid/cmdline按 NUL 字节切分得到argv见parse_cmdline()procinfo/src/linux.rs。状态码映射将/proc/pid/stat中的单字母状态码映射到LocalProcessStatus例如R→Run、S→Sleep、D→Idle、Z→Zombie、T→Stop、t→Tracing、X/x→Dead等procinfo/src/linux.rs。递归建树build_proc()遍历全部进程找出所有ppid等于当前节点 PID 的子进程并用visited集合防止环procinfo/src/linux.rs。macOSproc_pidinfo 与 sysctl 组合macOS 实现procinfo/src/macos.rs走的是系统调用路线枚举进程通过proc_listallpids()一次性列出全部 PID且预留了 32 个 PID 的缓冲 padding 以应对查询期间新进程频繁产生的情况procinfo/src/macos.rs。基础信息通过proc_pidinfo(pid, PROC_PIDTBSDINFO, ...)获取 BSD 进程信息块PID、PPID、pbi_comm 进程名、启动时间、状态见 procinfo/src/macos.rs。可执行文件与参数优先通过sysctl的KERN_PROCARGS2查询拿到 argc、可执行路径与完整 argvprocinfo/src/macos.rs失败时退回proc_pidpath()获取可执行路径。该模块还附带了针对KERN_PROCARGS2缓冲区解析的单元测试如 procinfo/src/macos.rs覆盖了 exe_path 与 argv 之间补零、argv 项之间补零、缓冲区末尾补零以及畸形数据等多种边界情况。工作目录通过proc_pidinfo的PROC_PIDVNODEPATHINFO读取 vnode 路径信息得到cwdprocinfo/src/macos.rs。WindowsToolhelp32 快照 PEB 内存读取Windows 实现procinfo/src/windows.rs最为复杂枚举进程基于 Toolhelp32 API 的CreateToolhelp32SnapshotProcess32FirstW/NextW拍摄进程快照procinfo/src/windows.rs。打开目标进程OpenProcess需要PROCESS_QUERY_INFORMATION | PROCESS_VM_READ权限特别地如果查询目标是 wezterm 自身进程会直接跳过以避免死锁procinfo/src/windows.rs。可执行路径通过QueryFullProcessImageNameW获取procinfo/src/windows.rs。argv 与 cwd通过NtQueryInformationProcess拿到 PEB 指针再ReadProcessMemory读取RTL_USER_PROCESS_PARAMETERS中的命令行CommandLine与当前目录CurrentDirectory.DosPath结构最后用CommandLineToArgvW把命令行字符串拆分成 argv 数组procinfo/src/windows.rs。实现还区分了 64 位原生进程与 32 位 WOW64 进程通过ProcessWow64Information判定分别用不同宽度的结构体解析procinfo/src/windows.rs并对读取长度设置了MAX_PATH * 4的防御上限procinfo/src/windows.rs。状态由于 Windows 无法提供与 Unix 等价的进程状态枚举所有进程的status一律置为Runprocinfo/src/windows.rs。此外procinfo/src/lib.rs 表明在非 macOS / Linux / Windows 的平台上with_root_pid、current_working_dir、executable_path均直接返回None——即这些函数仅在三大主流桌面平台上有实际实现。实战在配置中查询与展示进程信息结合 wezterm.procinfo.pid() 的幂等查询wezterm.procinfo.pid()返回当前进程的 PID。在配置加载阶段此时运行 Lua 的是 wezterm-gui 进程把它作为get_info_for_pid的入参就能拿到以 wezterm-gui 为根的完整进程树——上面的官方示例正是这么做的。与 pane:get_foreground_process_info() 的关系在 passing-data.md 中wezterm.procinfo.get_info_for_pid()被归类为本地进程状态Local Process State类函数与pane:get_foreground_process_info()并列。两者的区别在于入口不同后者从某个 Pane 对象出发返回该 pane 中前台进程的进程树而前者接受任意 PID不依赖 pane 上下文。捕获 nil 返回由于目标进程可能在任何时刻退出或查询权限不足函数可能返回nil。任何访问其字段的代码都应先判空local info wezterm.procinfo.get_info_for_pid(some_pid) if info then -- 此时可安全访问 info.executable、info.cwd、info.children 等字段 return info.cwd else return unknown end遍历进程树children是递归嵌套结构可按需深度遍历例如收集整棵进程树的可执行文件名源码中的flatten_to_exe_names即提供了类似思路见 procinfo/src/lib.rslocal function walk(info, depth) if not info then return end local indent string.rep( , depth) wezterm.log_info(indent .. info.pid .. .. (info.executable or )) for _, child in pairs(info.children or {}) do walk(child, depth 1) end end local me wezterm.procinfo.get_info_for_pid(wezterm.procinfo.pid()) walk(me, 0)使用边界与注意事项结合官方文档与源码使用该 API 时有以下几点需要特别留意仅限本地进程该函数直接读取操作系统进程表因此只能查询运行在 wezterm 所在机器上的本地进程。当通过 SSH 连接远程主机或使用 multiplexer 连接时无法用它窥探远程进程——这正是 passing-data.md 转而推荐 User Vars、OSC 7 等机制的原因。可能返回 nil进程已退出、权限不足、平台不支持非 Linux/macOS/Windows等场景下都会得到nil。name 字段可信度有限文档明确提示它可能不准确、被截断应优先使用executable或argv。Windows 上的特殊性passing-data.md提到这些本地进程函数在 Windows 上确定正确的前台进程时可能表现不佳且 Windows 实现的status恒为Runargv/cwd依赖对目标进程 PEB 的内存读取进程是 32 位还是 64 位会影响解析路径。性能开销以 Linux 实现为例每次调用都会枚举/proc下全部进程并逐一读取多个文件以递归构建子树。若在update-status等高频回调中频繁调用可能带来可感知的开销建议缓存结果或降低调用频率。相关链接wezterm.procinfo 模块总览wezterm.procinfo.pid()wezterm.procinfo.current_working_dir_for_pid()wezterm.procinfo.executable_path_for_pid()LocalProcessInfo 类型文档pane:get_foreground_process_info()从 pane 向 Lua 传递数据的最佳实践底层实现procinfo/src/lib.rs、procinfo/src/linux.rs、procinfo/src/macos.rs、procinfo/src/windows.rsLua 绑定注册lua-api-crates/procinfo-funcs/src/lib.rs【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考