模块契约Console

裁剪宏：XRT_FEATURE_CONSOLE直接依赖：core头文件：<xrt/console.h> 或 <xrt.h>

错误

错误域固定为 xrt.console：

错误码含义
XCONSOLE_ERROR_STREAM标准流枚举无效
XCONSOLE_ERROR_UTF8文本输出或输入的 UTF-8/Unicode scalar 无效
XCONSOLE_ERROR_WRITE标准流写入失败
XCONSOLE_ERROR_FLUSH标准流刷新失败

系统调用失败会保留原生系统错误码。调用成功不清除线程中已有的错误。

选择模块

模块选择宏只启用 Console 和不可裁剪的核心错误能力。

标准流

常量含义
XCONSOLE_STDOUT标准输出
XCONSOLE_STDERR标准错误

文本契约是 UTF-8。真实 Windows 控制台会严格验证并转换为 UTF-16； 标准流重定向到文件或管道时，XRT 原样保留 UTF-8 字节。二进制输出应使用 文件或 IO API，不属于 Console 文本接口。

Windows 以 GetStdHandle 返回的进程标准句柄为权威，因此运行期间的 SetStdHandle 会立即生效。若代码通过 _dup2 等 CRT 接口重定向标准流， 还应同步调用 SetStdHandle；只有进程标准句柄不存在时才回退到 CRT 句柄。

输入、屏幕与终端会话

基础 console 输出始终先验证完整 UTF-8（包括重定向），然后按实际 字节长度写出，内嵌 NUL 不截断；二进制内容使用 io_standard。

模块直接依赖能力
console_inputconsole、buffer、io_standard严格 Unicode 字符/行输入
console_screenconsole尺寸/颜色查询和 styled output，不带 Session/IO/thread
console_terminalconsole_screen、io_standard、buffer、thread交互模式、批量屏幕输出与事件

xconsolestream类型

标准输出流名称跨平台稳定，不直接暴露 FILE 或原生句柄。

值语义
XCONSOLE_STDOUTXCONSOLE标准输出
XCONSOLE_STDERR标准错误流
typedef enum xconsolestream { XCONSOLE_STDOUT = 1, XCONSOLE_STDERR } xconsolestream;

xconsoleerror类型

Console 错误代码在 xrt.console 域内稳定。

值语义
XCONSOLE_ERROR_STREAM失败
XCONSOLE_ERROR_UTF8失败
XCONSOLE_ERROR_WRITE写方向
XCONSOLE_ERROR_FLUSH刷新失败
XCONSOLE_ERROR_READ读取失败
XCONSOLE_ERROR_LIMIT输入超过限制
XCONSOLE_ERROR_STATE控制台状态非法
XCONSOLE_ERROR_TERMINAL终端操作失败
typedef enum xconsoleerror { XCONSOLE_ERROR_STREAM = 1, XCONSOLE_ERROR_UTF8, XCONSOLE_ERROR_WRITE, XCONSOLE_ERROR_FLUSH, XCONSOLE_ERROR_READ, XCONSOLE_ERROR_LIMIT, XCONSOLE_ERROR_STATE, XCONSOLE_ERROR_TERMINAL } xconsoleerror;
输出

xrtConsoleWrite函数

写入给定 UTF-8 视图，不追加换行。一次调用不会与另一线程的一次 Console 调用交错。

bool xrtConsoleWrite(xconsolestream Stream, xstrview Text)

参数

参数方向约束说明
Stream输入枚举值XCONSOLE_STDOUT / XCONSOLE_STDERR
Text输入借用、UTF-8要写入的文本视图
返回值
返回含义失败时状态
true已写入标准流—
false流枚举非法、UTF-8 非法或写入失败错误经 xrtGetError() 报告
错误
  • XCONSOLE_ERROR_STREAM — 流枚举无效
  • XCONSOLE_ERROR_UTF8 — 真实 Windows 控制台收到非法 UTF-8
  • XCONSOLE_ERROR_WRITE — 标准流写入失败（保留原生系统错误码）

范例已编译验证

console/variants · 基础形态 · 不加换行的裸写入

bool bOk = xrtConsoleWrite(XCONSOLE_STDOUT, XRT_STR_LITERAL("write-ok"));

xrtConsoleWriteLine函数

在同一个标准流锁内写入文本并追加一个换行符。

bool xrtConsoleWriteLine(xconsolestream Stream, xstrview Text)

参数

参数方向约束说明
Stream输入枚举值目标标准流
Text输入借用、UTF-8要写入的文本（换行由函数追加）
返回值
返回含义失败时状态
true文本与换行已在同一锁内写入—
false同 xrtConsoleWrite 的失败条件错误经 xrtGetError() 报告
错误
  • 同 xrtConsoleWrite（STREAM / UTF8 / WRITE）

范例已编译验证

console/output · 双流 · 正常日志走 stdout、诊断走 stderr

if (
	!xrtConsoleWriteLine(
		XCONSOLE_STDOUT,
		XRT_STR_LITERAL("service started")
	) ||
	!xrtConsoleWriteLine(
		XCONSOLE_STDERR,
		XRT_STR_LITERAL("example diagnostic")
	)
) {
	return 1;
刷新和终端判断

xrtConsoleFlush函数

冲刷指定标准流的缓冲。

bool xrtConsoleFlush(xconsolestream Stream)

参数

参数方向约束说明
Stream输入枚举值目标标准流
返回值
返回含义失败时状态
true缓冲已落地—
false流枚举非法或刷新失败错误经 xrtGetError() 报告
错误
  • XCONSOLE_ERROR_STREAM — 流枚举无效
  • XCONSOLE_ERROR_FLUSH — 刷新失败（保留原生系统错误码）

范例已编译验证

console/output · 收尾 · 退出前保证诊断落地

return xrtConsoleFlush(XCONSOLE_STDERR) ? 0 : 2;

xrtConsoleIsTerminal函数

判断流当前是否交互终端。返回 false 可以表示普通文件或管道，不是错误。

bool xrtConsoleIsTerminal(xconsolestream Stream)

参数

参数方向约束说明
Stream输入枚举值目标标准流
返回值
返回含义失败时状态
true流连接到交互终端—
false文件/管道重定向（正常结果）或流枚举非法重定向不设错；非法流设置错误
错误
  • XCONSOLE_ERROR_STREAM — 流枚举无效

范例已编译验证

console/variants · 终端判断 · 重定向下返回 0 是正常结果

printf("is-terminal=%d\n",
	xrtConsoleIsTerminal(XCONSOLE_STDOUT) ? 1 : 0);
输入、屏幕与终端会话

xrtConsoleReadChar函数

int xrtConsoleReadChar(uint32* Codepoint)：1 为 Unicode scalar，0 为 正常 EOF，-1 为错误；Codepoint 非空。Windows 原生输入严格组合 UTF-16 代理对，重定向和 POSIX 输入严格验证 UTF-8。无效输入是 XERR_IO， 不预读下一字符。调用期间独占标准输入，活动 raw Reader/Session 造成 XERR_STATE；错误时已经消费的输入不回滚。

XRT_API int xrtConsoleReadChar(uint32* pCodepoint)

xrtConsoleReadLine函数

xbuffer* xrtConsoleReadLine(size_t MaxBytes)：去掉 LF/CRLF，裸 CR 仍是内容，UTF-8 实际字节上限不计终止符。EOF 前没有字符返回正常 NULL，空行返回独立空 Buffer；失败 NULL 并设错，调用者 Destroy 返回值。NUL 原样保留；零上限允许空行，不允许非空内容。

XRT_API xbuffer* xrtConsoleReadLine(size_t iMaxBytes)
补充参考 · 契约见公共头注释

xrtConsoleSessionOpen函数

契约注释见公共头文件。

XRT_API xconsolesession* xrtConsoleSessionOpen(uint32 Flags)

xrtConsoleSessionClose函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionClose(xconsolesession* pSession)

xrtConsoleSessionDestroy函数

契约注释见公共头文件。

XRT_API void xrtConsoleSessionDestroy(xconsolesession* pSession)

xrtConsoleSessionClosed函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionClosed(const xconsolesession* pSession)

xrtConsoleSessionPasteSupported函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionPasteSupported(const xconsolesession* pSession)

xrtConsoleSessionWrite函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionWrite(xconsolesession* pSession, xstrview Text)

xrtConsoleSessionFlush函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionFlush(xconsolesession* pSession)

xrtConsoleSessionMove函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionMove(xconsolesession* pSession, uint32 X, uint32 Y)

xrtConsoleSessionClear函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionClear(xconsolesession* pSession, int Mode)

xrtConsoleSessionCursor函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionCursor(xconsolesession* pSession, bool Visible)

xrtConsoleSessionStyle函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSessionStyle(xconsolesession* pSession, int32 Foreground, int32 Background, uint32 Attributes)

xrtConsoleSessionRead函数

契约注释见公共头文件。

XRT_API xconsoleevent* xrtConsoleSessionRead(xconsolesession* pSession, int TimeoutMs)

xrtConsoleEventDestroy函数

契约注释见公共头文件。

XRT_API void xrtConsoleEventDestroy(xconsoleevent* pEvent)

xrtConsoleSize函数

契约注释见公共头文件。

XRT_API bool xrtConsoleSize(xconsolestream Stream, uint32* pColumns, uint32* pRows)

xrtConsoleColorMode函数

契约注释见公共头文件。

XRT_API int xrtConsoleColorMode(xconsolestream Stream)

xrtConsoleWriteStyled函数

契约注释见公共头文件。

XRT_API bool xrtConsoleWriteStyled(xconsolestream Stream, xstrview Text, int32 Foreground, int32 Background, uint32 Attributes)

常量索引常量

以下常量在本页所属头文件中定义，语义见公共头注释。

常量说明
XCONSOLE_ERROR_FLUSH见头文件注释
XCONSOLE_ERROR_LIMIT见头文件注释
XCONSOLE_ERROR_READ见头文件注释
XCONSOLE_ERROR_STATE见头文件注释
XCONSOLE_ERROR_STREAM见头文件注释
XCONSOLE_ERROR_TERMINAL见头文件注释
XCONSOLE_ERROR_UTF8见头文件注释
XCONSOLE_ERROR_WRITE见头文件注释
XCONSOLE_EVENT_CLOSED见头文件注释
XCONSOLE_EVENT_KEY见头文件注释
XCONSOLE_EVENT_MOUSE见头文件注释
XCONSOLE_EVENT_PASTE见头文件注释
XCONSOLE_EVENT_RESIZE见头文件注释
XCONSOLE_EVENT_TEXT见头文件注释
XCONSOLE_KEY_BACKSPACE见头文件注释
XCONSOLE_KEY_DELETE见头文件注释
XCONSOLE_KEY_DOWN见头文件注释
XCONSOLE_KEY_END见头文件注释
XCONSOLE_KEY_ENTER见头文件注释
XCONSOLE_KEY_ESCAPE见头文件注释
XCONSOLE_KEY_F1见头文件注释
XCONSOLE_KEY_HOME见头文件注释
XCONSOLE_KEY_INSERT见头文件注释
XCONSOLE_KEY_LEFT见头文件注释
XCONSOLE_KEY_PAGE_DOWN见头文件注释
XCONSOLE_KEY_PAGE_UP见头文件注释
XCONSOLE_KEY_RIGHT见头文件注释
XCONSOLE_KEY_TAB见头文件注释
XCONSOLE_KEY_UP见头文件注释
XCONSOLE_STDERR见头文件注释
XCONSOLE_STDOUT见头文件注释