豫言操作系统底层句柄 0.1.0

状态：草案。文言本见文言版。通用规则见[调用约定](../调用约定.汉语.md)，状态码表见[底层基础](../底层基础/规范.汉语.md)。

范围

句柄的通用操作：读、写、定位读写、寻址、同步、设长度、设非阻塞、等待、建管道，以及枚举初始授权与查询类别。文件、套接字、终端、进程的句柄都用这里的函数收发数据；打开、连接、启动它们的函数在各自的包里。本包依赖底层基础（状态码）。

句柄模型

• 句柄是非负整数，由平台发放；0、1、2 恒为标准输入、输出、错误；-1 无效；关闭后编号可能复用。
• 初始句柄表：启动时平台授予的其余句柄（预开目录等），用 取初始句柄 按序号（从 0 起）枚举，每项给出类别、句柄和名字（预开目录的名字是客体看到的路径，如 /）。这是程序获得授权的唯一来源。
• 类别（取句柄类别）：0 未知、1 普通文件、2 目录、3 终端、4 其他字符设备、5 管道、6 套接字、7 进程。
• 各函数对不适用的类别返回 28（参数无效）：例如对目录 读，对管道 寻址（返回 70，不可寻址）。

句柄（句柄。接口。豫）

| 函数 | 参数 | 作用 | | --- | --- | --- | | 取初始句柄 | 序号, 类别出, 句柄出, 名缓冲址, 名缓冲长, 名总长出 | 出类别、句柄各 4 字节；名字写入名缓冲，名字总长 4 字节；序号越界返回 44；名缓冲不足返回 61 | | 取句柄类别 | 句柄, 出 | 类别 4 字节 | | 读 | 句柄, 缓冲址, 长, 出 | 至多读「长」字节；已读数 4 字节，0 表示文件尾；非阻塞句柄无数据返回 6；终端行模式按行送达，换行符含在所读字节中，空行因此读得至少 1 字节；缓冲区短于一行时，剩余字节由后续读取接收；长为 0 时不消耗输入 | | 写 | 句柄, 址, 长, 出 | 已写数 4 字节，可短写；读端已关闭的管道返回 64 | | 定位读 | 句柄, 缓冲址, 长, 偏移低, 偏移高, 出 | 不改变当前位置；不可寻址的句柄返回 70 | | 定位写 | 句柄, 址, 长, 偏移低, 偏移高, 出 | 同上 | | 寻址 | 句柄, 偏移低, 偏移高, 起点, 出 | 起点 0 开头、1 当前、2 末尾；新位置 8 字节；不可寻址返回 70 | | 关闭 | 句柄 | 之后该编号失效 | | 同步 | 句柄, 标志 | 标志 1 表示仅同步数据；不可同步的句柄返回 28 | | 设长度 | 句柄, 低, 高 | 截断或扩展普通文件；其余类别返回 28 | | 设非阻塞 | 句柄, 开关 | 开关 1 置为非阻塞、0 恢复阻塞 | | 建管道 | 读端出, 写端出 | 两端各得一个句柄（各 4 字节）；所有写端关闭后读端读得 0 |

等待（等待。接口。豫）

| 函数 | 参数 | 作用 | | --- | --- | --- | | 等待 | 订阅址, 订阅数, 事件址, 出 | 阻塞到至少有一个事件；事件写入事件址，事件个数（4 字节）写入出址；订阅数为 0 返回 28 |

订阅（16 字节）：

| 偏移 | 宽 | 字段 | | --- | --- | --- | | 0 | 4 | 类别：1 时钟、2 可读、3 可写 | | 4 | 4 | 句柄（时钟类忽略） | | 8 | 8 | 超时纳秒（仅时钟类，相对当前时刻） |

事件（16 字节）：

| 偏移 | 宽 | 字段 | | --- | --- | --- | | 0 | 4 | 订阅序号，即该订阅在数组中的下标 | | 4 | 4 | 状态码：0，或该句柄出错的码（如 8） | | 8 | 4 | 类别，同订阅 | | 12 | 4 | 可用字节数（可读类，超过 32 位则取最大值；其余为 0） |

规则：时钟订阅到时即报告；可读订阅在句柄有数据或已到文件尾（此时可用字节数为 0）时报告；可写订阅在写入不会阻塞时报告；没有时钟订阅且没有句柄就绪则一直阻塞。没有句柄订阅、只有时钟订阅时就是睡眠。首版保证四类对象可等待：文件（恒就绪）、终端、管道、套接字与进程（进程可读即已退出）。

平台注记

• 裸机：0、1、2 是控制台；管道是执行器内的内存对象；等待时钟用内核滴答（精度 10 ms），等待邮箱与终端输入靠内核服务轮询；文件句柄由执行器内的文件系统提供（见[底层文件](../底层文件/规范.汉语.md)）。
• 桌面：句柄是对文件描述符（Linux、macOS）或 HANDLE（Windows）的一层编号；等待 落到 ppoll、kevent 或 WaitForMultipleObjects，这是各后端里最难保持一致的一处，首版只承诺上面四类对象。