豫言 / 豫言操作系统底层接口 @ 0.1.0
豫言操作系统底层接口（无垃圾回收）的父包：登记全部底层接口包，便于按层级发现。
总纲.汉语.md
# 豫言操作系统底层接口
状态：源级接口草案 0.1。这里是仓库根目录下的独立规范树，只含接口包、纯声明和规范文字；各平台后端与 shim 在别处。Linux x86-64、arm64 与 macOS arm64 的 45 个底层函数已有后端，裸机已有用于验证与运行客体的后端；Windows 后端仍在规划中。GC 与 WASI shim 已部分改接，跨平台全量一致性仍待验收。设计缘由与整体方案见[总体架构](../豫言操作系统/文档/豫言操作系统总体架构.汉语.md)。文言本见[文言版](总纲.文言.md)。
## 是什么
一套**不含垃圾回收**的操作系统接口：值只有 32 位整数，数据以（地址，长度）与出址传递，每个函数返回状态码。它是各平台与上层之间的“窄腰”：Windows、macOS、Linux 和裸机各实现一份后端，WASI shim 与 GC shim 架在它上面。
它**只有两个使用者**：WASI shim 与 GC shim。应用不直接调用它：非 GC 应用用 WASI，GC 应用用[豫言操作系统接口](../豫言操作系统接口/总纲.汉语.md)。
## 与 GC 接口的关系
| | GC 接口（豫言操作系统接口） | 底层接口（本树） |
| --- | --- | --- |
| 值 | 豫言值类型：字符串、列、变体、资源…… | 32 位整数 |
| 编译模式 | 高级（有垃圾回收），依赖标准库 | 底层（无垃圾回收），依赖底层库 |
| 使用者 | 应用 | WASI shim、GC shim |
| 实现 | 宿主适配包（豫言写）与宿主库 | 平台后端实现包（豫言写），每平台一份 |
| 错误 | 变体结果与共用的系统错误 | 状态码（WASI errno 的子集） |
| 授权 | 授权表、目录权、显示面等 | 启动时的初始句柄表（预开目录） |
两棵树互不依赖。底层接口里没有的东西（HTTP、JSON、日期拆分、路径规范化、当前目录）由 shim 用豫言实现，不进后端。
## 文件与身份
- 每个能力组是独立的包 `豫言操作系统底层<能力>`，放在目录 `底层<能力>/` 里：`名称。包。豫`（`「编译模式」者『底层』也。`，依赖 `底层库` 与所需的本树其他包）、若干 `模块。接口。豫`、`规范.汉语.md` 与 `规范.文言.md`。
- 目录名等于包名去掉 `豫言操作系统` 前缀：现行检查器据此定位兄弟包，本树不需要另改定位规则。
- 接口文件的写法沿用 GC 接口的[接口文件规则](../豫言操作系统接口/接口文件规则.汉语.md)，差异与本树的通用规则见[调用约定](调用约定.汉语.md)：签名里只有 `整数`（返回值可以是 `有`），类型来自 `底层库` 的 `基础`，不写函数体。
- 同一依赖闭包内编译模式必须一致（豫构检查），所以本树的包不会混进 GC 类型，也不能依赖标准库。
- 目录根的 `豫言操作系统底层接口。包。豫` 是本树的父包，说明文件就是本总纲：它用「包含包」按“首批能力组”表格的顺序登记全部底层接口包，各包用「包含在」指回本包（规则见[包系统](../应用/豫构/包系统.汉语.md)“层级包”一节）。父包与库类型子包须同编译模式，所以父包也声明底层。父包不含模块，用于按层级发现。新增能力组时，在表格与父包「包含包」的相同位置登记，并在新包写「包含在」。
## 首批能力组
| 包 | 语义范围 | 函数 | 性质 |
| --- | --- | --- | --- |
| [底层基础](底层基础/规范.汉语.md) | 状态码、时钟、随机、命令行参数与环境、退出、中断、平台探测 | 11 | 核心 |
| [底层句柄](底层句柄/规范.汉语.md) | 句柄的读写、寻址、同步、等待、管道 | 13 | 核心 |
| [底层文件](底层文件/规范.汉语.md) | 按目录句柄授权的打开、状态、目录读取与增删改名 | 9 | 核心 |
| [底层网络](底层网络/规范.汉语.md) | TCP 监听、连接、接受 | 7 | 可选 |
| [底层终端](底层终端/规范.汉语.md) | 终端模式与尺寸 | 2 | 可选 |
| [底层进程](底层进程/规范.汉语.md) | 运行程序、取退出码、终止 | 3 | 可选 |
共 45 个函数。“可选”指平台可以没有：没有时所有函数返回 58（不支持），shim 据此降级。显示与输入预留为 `豫言操作系统底层显示`，v2 再做。
依赖关系：底层基础 ← 底层句柄 ← {底层文件、底层网络、底层终端、底层进程}；所有包依赖 `底层库`。
## 检查
- 接口检查器 `yy豫言操作系统接口检查` 已改为按包索引定位包（原先只认自身、`标准库` 和以 `豫言操作系统` 开头的包，找不到 `底层库`；见[检查器说明](../豫言操作系统/应用/豫言操作系统接口检查/说明.汉语.md)），本树可以直接检查：`node 豫言操作系统/宿主/节点/宿主.cjs yy豫言操作系统接口检查.wasm 豫言操作系统底层接口/底层文件/豫言操作系统底层文件。包。豫`，`--清单` 与 `--核对清单` 同样可用。修复前后对全部 GC 接口包与适配清单做过对照，输出逐字相同。
- 状态码、标志、类别号等常量的统一机器可读定义仍待完成；现有后端和 shim 各持所需常量。
## 尚未做
- 一致性样例与测试骨架；
- Windows 后端、GC 与 WASI shim 的余下改接及全平台一致性验收；
- 显示与输入；设文件时间、建链接、分散／聚集读写、文件锁等后续候选（见方案第六节）。
总纲.文言.md
# 豫言操作系统底层接口
状：源级接口之草案〇点一。此仓库根目录下之独立规范树，唯含接口包、纯声明与规范之文；诸平台后端与垫层，皆在他处。Linux x86-64、arm64 与 macOS arm64 之后端，已备四十五底层函数；裸机亦有供验与行客体之后端，Windows 犹待为。GC 与 WASI 垫层已改接其一部，跨平台全量一致之验犹待行。设计之由与全案，见[总体架构](../豫言操作系统/文档/豫言操作系统总体架构.文言.md)。汉语本见[汉语版](总纲.汉语.md)。
## 是何物
一套**无垃圾回收**之操作系统接口：值唯三十二位整数，数据以（址，长）与出址相授，每函数返状态之码。乃诸平台与上层之间之“窄腰”：Windows、macOS、Linux 与裸机各成一后端，WASI 垫层与 GC 垫层架于其上。
其用者**唯二**：WASI 垫层与 GC 垫层。应用不径呼之：非 GC 应用用 WASI，GC 应用用[豫言操作系统接口](../豫言操作系统接口/总纲.文言.md)。
## 与 GC 接口之系
| | GC 接口（豫言操作系统接口） | 底层接口（本树） |
| --- | --- | --- |
| 值 | 豫言值类型：字符串、列、变体、资源…… | 三十二位整数 |
| 编译之模 | 高级（有垃圾回收），依标准库 | 底层（无垃圾回收），依底层库 |
| 用者 | 应用 | WASI 垫层、GC 垫层 |
| 实现 | 宿主适配包（豫言书之）与宿主库 | 平台后端实现包（豫言书之），每平台一 |
| 误 | 变体之果与共用之系统错误 | 状态之码（WASI errno 之子集） |
| 授权 | 授权表、目录权、显示面等 | 启动时之初始柄表（预开之目录） |
二树互不相倚。底层接口之所无者（HTTP、JSON、日期拆分、路径规整、当前目录），由垫层以豫言为之，不入后端。
## 文件与身份
- 每能力组各为一包 `豫言操作系统底层<能力>`，置于目录 `底层<能力>/`：`名称。包。豫`（`「编译模式」者『底层』也。`，依 `底层库` 及所需之本树他包）、若干 `模块。接口。豫`、`规范.汉语.md` 与 `规范.文言.md`。
- 目录名即包名去 `豫言操作系统` 前缀：今之检查器据此定位兄弟之包，本树不必另改定位之规。
- 接口文之书法，沿 GC 接口之[接口文件规则](../豫言操作系统接口/接口文件规则.文言.md)，其异与本树通用之规，见[调用约定](调用约定.文言.md)：签中唯有 `整数`（返值可为 `有`），类型取诸 `底层库` 之 `基础`，不书函数体。
- 同一依赖闭包之内，编译之模必同（豫构校之），故本树之包不混入 GC 之型，亦不得依标准库。
- 目根之 `豫言操作系统底层接口。包。豫` 为本树之父包，其说即此总纲：以「包含包」依首批能力组之表序登诸底层接口包，诸包以「包含在」还指之（其制见[包制](../应用/豫构/包系统.文言.md)“层级之包”之节）。父与库子其模必同，故父亦书底层。父包无模，以便循层寻包。增能力组者，表与父之「包含包」同处并登，新包书「包含在」。
## 首批能力组
| 包 | 义之所涵 | 函数 | 性 |
| --- | --- | --- | --- |
| [底层基础](底层基础/规范.文言.md) | 状态之码、时钟、随机、命令行参数与环境、退出、中断、平台之探 | 11 | 核心 |
| [底层句柄](底层句柄/规范.文言.md) | 柄之读写、寻址、同步、等待、管道 | 13 | 核心 |
| [底层文件](底层文件/规范.文言.md) | 按目录柄授权之打开、状态、目录之读与增删改名 | 9 | 核心 |
| [底层网络](底层网络/规范.文言.md) | TCP 之监听、连接、接受 | 7 | 可选 |
| [底层终端](底层终端/规范.文言.md) | 终端之模与尺寸 | 2 | 可选 |
| [底层进程](底层进程/规范.文言.md) | 运行程序、取退出码、终止 | 3 | 可选 |
凡四十五函数。“可选”者，平台可无之：无则诸函数一概返 58（不支持），垫层依此降级。显示与输入预留为 `豫言操作系统底层显示`，第二版再为。
相倚之序：底层基础 ← 底层句柄 ← {底层文件、底层网络、底层终端、底层进程}；诸包皆依 `底层库`。
## 检查
- 接口检查器 `yy豫言操作系统接口检查` 已改循包索引以定位诸包（昔唯识自身、`标准库` 与以 `豫言操作系统` 起首之包，不得 `底层库`；见[检查器说明](../豫言操作系统/应用/豫言操作系统接口检查/说明.文言.md)），本树可径检之：`node 豫言操作系统/宿主/节点/宿主.cjs yy豫言操作系统接口检查.wasm 豫言操作系统底层接口/底层文件/豫言操作系统底层文件。包。豫`，`--清单` 与 `--核对清单` 亦可用。修前修后，于全部 GC 接口包与适配之清单，皆作对照，所出逐字相同。
- 状态之码、标志、类别之号，统一而可机读之定义犹待备；现有后端与垫层各持所需之常量。
## 尚未为
- 一致之样例与测试之骨架；
- Windows 后端、GC 与 WASI 垫层余下之改接，及诸平台一致之验；
- 显示与输入；设文件时间、建链接、分散／聚集之读写、文件锁等后续之候选（见方案第六节）。