模块契约环境变量

错误代码

xenverror 属于 xrt.environment 域：

  • XENV_ERROR_NAME：名称为空、包含 = 或不是合法 UTF-8。
  • XENV_ERROR_VALUE：值不是合法 UTF-8，或系统返回了无法转换的值。
  • XENV_ERROR_SYSTEM：操作系统环境 API 失败；xrtErrorSystemCode 保留原生错误码。

内存不足继续使用统一的 XERR_MEMORY。全部错误都进入当前 XRT 错误执行上下文，因此上层宿主可以映射，C 调用方也可通过 xrtGetError 检查。

并发与外部修改

环境是进程级共享状态。XRT 自身的 POSIX 读取、设置和删除入口使用同一把内部短锁，读取返回独立副本，不会借用 getenv 的易失指针。直接调用 C 运行库或第三方库修改环境时，调用方仍应与这些外部操作自行同步。

示例

完整示例见 examples/system/environment/main.c 与 examples/environment/variants/main.c。

xenverror类型

环境变量错误代码在 xrt.environment 域内稳定。

值语义
XENV_ERROR_NAME名称
XENV_ERROR_VALUE值非法
XENV_ERROR_SYSTEM系统调用失败
typedef enum xenverror { XENV_ERROR_NAME = 1, XENV_ERROR_VALUE, XENV_ERROR_SYSTEM } xenverror;

xrtEnvLookup函数

无歧义基础入口：查询过程成功返回 true，变量是否存在由输出指针区分。

bool xrtEnvLookup(cstr sName, str* psValue)

参数

参数方向约束说明
sName输入非空、不含 =、严格 UTF-8变量名
psValue输出非空进入时先置 NULL；存在时为 xrtFree 释放的副本
返回值
返回含义失败时状态
true查询成功；*psValue 非空 = 值副本，NULL = 变量不存在—
false名称非法、系统失败或 OOM*psValue 保持 NULL；错误经 xrtGetError() 报告
错误
  • XENV_ERROR_NAME — 名称非法
  • XENV_ERROR_VALUE — 系统值无法转换为 UTF-8
  • XENV_ERROR_SYSTEM — 环境 API 失败
  • XERR_MEMORY — 副本分配失败

范例已编译验证

environment/variants · 缺失语义 · 不存在是成功状态（输出为空）

/* 不存在的变量：成功返回 + 空输出。 */
if ( xrtEnvLookup("XRT_DEFINITELY_MISSING", &sValue) ) {
	printf("missing=ok\n");
}
xrtFree(sValue);

xrtEnvGet函数

常见路径的一行便捷入口；需要区分缺失和失败的代码应使用 xrtEnvLookup。

str xrtEnvGet(cstr sName)

参数

参数方向约束说明
sName输入非空、不含 =、严格 UTF-8变量名
返回值
返回含义失败时状态
非空拥有式 UTF-8 副本（空变量值返回独立空串）—
NULL变量不存在或查询失败失败时错误经 xrtGetError() 报告
错误
  • 同 xrtEnvLookup（NAME / VALUE / SYSTEM / XERR_MEMORY）

范例已编译验证

system/environment · 拥有式读取 · 副本不受后续环境修改影响

sValue = xrtEnvGet("XRT_ENVIRONMENT_EXAMPLE");
if ( sValue == NULL ) {
	return 2;
}
printf("value=%s\n", sValue);

xrtEnvSet函数

设置或覆盖进程级变量。

bool xrtEnvSet(cstr sName, cstr sValue)

参数

参数方向约束说明
sName输入非空、不含 =、严格 UTF-8变量名
sValue输入非空、严格 UTF-8；允许空串新值
返回值
返回含义失败时状态
true已设置（子进程会继承）—
false名称/值非法、系统失败或 OOM环境不变；错误经 xrtGetError() 报告
错误
  • XENV_ERROR_NAME / XENV_ERROR_VALUE — 名称或值非法
  • XENV_ERROR_SYSTEM — 设置 API 失败（Windows 用宽字符 API，不经 ANSI 代码页）
  • XERR_MEMORY

范例已编译验证

system/environment · 全流程 · 真实进程环境生效

if ( !xrtEnvSet("XRT_ENVIRONMENT_EXAMPLE", "hello") ) {
	return 1;
}

xrtEnvRemove函数

幂等删除变量；变量原本不存在仍返回 true。

bool xrtEnvRemove(cstr sName)

参数

参数方向约束说明
sName输入非空、不含 =、严格 UTF-8变量名
返回值
返回含义失败时状态
true已删除或本就不存在（幂等）—
false名称非法或系统失败错误经 xrtGetError() 报告
错误
  • XENV_ERROR_NAME — 名称非法
  • XENV_ERROR_SYSTEM — 删除 API 失败

范例已编译验证

system/environment · 收尾 · 范例不留下全局副作用

return xrtEnvRemove("XRT_ENVIRONMENT_EXAMPLE") ? 0 : 3;

常量索引常量

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

常量说明
XENV_ERROR_NAME见头文件注释
XENV_ERROR_SYSTEM见头文件注释
XENV_ERROR_VALUE见头文件注释