tldr 中的 uname26 别名页:解读 `setarch uname26` 命令别名与 tldr 别名文档机制
tldr 中的 uname26 别名页:解读 setarch uname26 命令别名与 tldr 别名文档机制
导读
uname26 是 Linux 下 setarch 的一个命令别名,用于在运行程序时向系统报告伪造的架构/内核版本信息。在 tldr 项目(协作式命令行速查手册仓库)中,它被单独记录为一个"别名页"(alias page),指向原命令 setarch 的完整文档。本篇以 tldr 仓库中的 阿拉伯语 uname26 别名页 为骨架,展开讲解该别名页的内容结构、setarch uname26 的实际用法,以及 tldr 项目如何通过统一的别名页模板与配套脚本,对这类"命令别名"进行跨语言归档和维护。读完本文,你将掌握 uname26/setarch 的使用场景,也能理解 tldr 别名页的规范格式与自动化生成流程。
一、别名页是什么:三行文档的完整语义
tldr 仓库中的每个 .md 文件对应一条命令的速查页。绝大多数页面都包含命令简介、多个带占位符的示例和 tldr 命令,而别名页(alias page)是一种特殊的极简页面:它不重复记录命令用法,而是明确声明"本命令是某个原命令的别名",并引导用户去查看原命令的文档。
以英文版 pages/linux/uname26.md 为例:
# uname26
> This command is an alias of `setarch uname26`.
- View documentation for the original command:
`tldr setarch`
阿拉伯语版 pages.ar/linux/uname26.md 与此逐行对应:
# uname26
> هذا الأمر هو اسم مستعار لـ `setarch uname26`.
- إعرض التوثيقات للأمر الأصلي:
`tldr setarch`
页面共四个要素:
- 标题行(
# uname26):命令名,作为客户端检索页面的键; - 描述行(
>开头):用一句话说明它是别名,并给出原命令全名setarch uname26; - 操作说明行(
-开头):提示用户查看原命令文档; - 示例代码行(反引号包裹):给出真正可执行的
tldr setarch命令。
也就是说,这 3 行内容浓缩了"怎么查"的全部信息——用户无需记住 setarch 的复杂参数,只需执行 tldr setarch 即可跳转到完整用法页。
二、原命令 setarch uname26 到底是什么
别名页把焦点引向了 pages/linux/setarch.md,这才是 uname26 背后真正的技术实体。tldr 对 setarch 的定义是:更改程序执行时所报告的系统架构,主要用于兼容性测试或运行遗留应用。这在"运行一个命令但让它以为机器是另一种架构/内核版本"的场景中非常关键。
uname26 作为 setarch 的一个 personality 参数,核心作用是让目标程序看到一份伪造的 uname 系统信息(例如旧内核版本、32 位架构),从而绕过某些老软件对运行环境的硬编码检查。tldr 的 setarch 页给出了完整实操示例:
# 让命令以为机器架构是 i686(在 64 位内核上运行 32 位应用很实用)
setarch i686 {{command}}
# 以 x86_64 架构运行一个 shell
setarch x86_64 {{bash}}
# 禁用虚拟地址空间随机化(ASLR)
setarch {{linux32}} {{[-R|--addr-no-randomize]}} {{command}}
# 列出支持的架构
setarch --list
# 显示帮助
setarch {{[-h|--help]}}
对照这套示例可以发现,setarch uname26 的语义是:调用 setarch,并传入 uname26 作为要模拟的 personality,使程序读取到的内核版本/架构信息被改写为 uname26 风格(即向系统报告一个与当前实际内核不同的版本号)。这与页内 setarch i686、setarch x86_64 属于同一类用法——区别只在于模拟的目标不同。setarch --list 可查看当前内核支持的全部 personality 值,uname26 正是其中之一。
三、在 tldr 中如何查看 uname26 的文档
别名页提供的唯一示例就是跳转命令,执行方式遵循 tldr 客户端规范(详见仓库根目录的 CLIENT-SPECIFICATION.md):
tldr setarch
这里的解析流程涉及两层规则:
- 平台解析:
uname26与setarch都是 Linux 命令,页面存放于linux平台目录。客户端默认先查当前运行平台,查不到再回退到common平台;由于这些页面只存在于pages/linux/,在非 Linux 系统上执行tldr uname26时,符合规范的客户端也会按windows → common → osx → linux的顺序继续搜索并给出提示(见 CLIENT-SPECIFICATION 的 "Page resolution" 一节)。 - 语言解析:如果设置了
LANG=ar或通过-L ar显式指定语言,客户端会优先查找pages.ar/linux/uname26.md,找不到再回退到英文版pages/linux/uname26.md。因此阿拉伯语用户执行tldr uname26或tldr setarch时,会直接看到上面那版阿语别名页内容。
四、setarch 家族:一组同构的别名页
uname26 并非孤例。在 pages/linux/ 目录下,所有 setarch 的常用 personality 别名都采用完全相同的别名页结构:
| 命令 | 页面路径 | 指向的原命令 |
|---|---|---|
uname26 |
pages/linux/uname26.md | setarch uname26 |
linux32 |
pages/linux/linux32.md | setarch linux32 |
linux64 |
pages/linux/linux64.md | setarch linux64 |
i386 |
pages/linux/i386.md | setarch i386 |
x86_64 |
pages/linux/x86_64.md | setarch x86_64 |
这组页面共同体现了 tldr 的一个设计原则:对命令的"语法别名",不重复造文档,只做一次性跳转,把维护成本降到最低。用户在终端里敲 uname26、linux32 还是 i386,得到的文档指引最终都收敛到 tldr setarch 这一页。
五、别名页的规范模板与跨语言一致性
别名页之所以能做到"一行原命令描述 + 一条跳转命令",是因为 tldr 仓库为所有语言规定了统一的模板,存放在 contributing-guides/translation-templates/alias-pages.md。该文件按语言(en、ar、zh、zh_TW、fr 等 40+ 种)各给出一个 markdown 模板,例如:
# example
> This command is an alias of `example`.
- View documentation for the original command:
`tldr example`
阿语模板为:
# example
> هذا الأمر هو اسم مستعار لـ `example`.
- إعرض التوثيقات للأمر الأصلي:
`tldr example`
对比可见,pages.ar/linux/uname26.md 正是把模板中的 example 占位符替换为标题 uname26、原命令 setarch uname26、跳转命令 setarch 后的产物。这种"模板驱动"的方式保证了任何语言的别名页在结构上完全一致,客户端只需按固定格式解析即可。
CONTRIBUTING.md 第 214 行也明确指引:别名页的翻译模板清单见 contributing-guides/translation-templates/alias-pages.md,翻译类页面应当以英文页为基准。
六、自动化维护:set-alias-page.py 脚本
为了让别名页的创建与多语言同步可重复执行,仓库提供了专门的维护脚本 scripts/set-alias-page.py。它直接从上面提到的模板文件读取各语言模板(读取逻辑封装在 scripts/_common.py 的 get_templates 函数中),通过字符串替换生成页面内容。
脚本支持的主要参数:
| 参数 | 含义 |
|---|---|
-p, --page PAGE |
指定要创建的别名页(格式 platform/alias_command.md),进入交互式向导 |
-S, --sync |
读取英文别名页,同步到所有已存在的翻译目录 |
-l, --language ll[_CC] |
限定只同步某个语言(如 -l ar) |
-s, --stage |
同步后自动 git add 暂存变更 |
-n, --dry-run |
只预览将产生的改动,不写入文件 |
-i, --inexact |
忽略严格模板匹配,识别非标准别名页 |
典型用法:
# 交互式创建/更新 linux/uname26 的别名页
python3 scripts/set-alias-page.py -p linux/uname26
# 将英文别名页同步到全部翻译(包括 pages.ar)
python3 scripts/set-alias-page.py -S
# 仅同步阿拉伯语翻译并暂存
python3 scripts/set-alias-page.py -S -l ar -s
值得注意的两个实现细节:
- 占位符替换:
generate_alias_page_content会依次把模板中的三处example替换为"页面标题""原命令""跳转命令"(见set-alias-page.py的generate_alias_page_content函数),对应别名页的三要素。 - 模板一致性校验:
get_alias_command_in_page会把现有页面内容做正则归一化后与模板比对,判断页面是否严格符合规范;sync模式下英文页是数据源,各语言页按需生成。这也解释了为什么仓库中 39 个uname26.md(英 + 38 种翻译)内容逐字对应。
七、小结与延伸阅读
回到最初的三行阿语别名页:它虽短,却完整承载了"uname26 是什么(setarch uname26 的别名)、去哪查(tldr setarch)、怎么查(跨平台/跨语言的页面解析)"三层信息,并受仓库模板与脚本的约束保持跨语言一致。
想进一步深入,可继续查看以下仓库文件:
- pages/linux/setarch.md:
uname26背后的原命令完整文档; - pages/linux/linux32.md 与 pages/linux/i386.md:同族别名页示例;
- contributing-guides/translation-templates/alias-pages.md:全部语言的别名页模板;
- scripts/set-alias-page.py:别名页的生成与同步脚本;
- CLIENT-SPECIFICATION.md:客户端如何做平台与语言解析。