2026/9/7 9:06:55
FEATURED · 精选文章 
OBS Studio libobs config_t 配置系统带默认值机制的 INI 文件 API 全解【免费下载链接】obs-studioOBS Studio - Free and open source software for live streaming and screen recording项目地址: https://gitcode.com/GitHub_Trending/ob/obs-studio本文基于 libobs 官方 API 参考文档 Config Files 文档 及其底层实现 libobs/util/config-file.h、libobs/util/config-file.c 编写。libobs 的配置系统是一套「带默认值机制的简易 INI 实现」OBS Studio 主界面所有窗口尺寸、编码参数、OAuth 凭据等持久化数据都通过它落盘。读完本文你将完整掌握config_t的全套 C API创建、打开、读写、默认值、原子保存理解其数据结构与转义规则并能像 OBS 前端那样编写健壮的配置读写代码。1. API 概览一份带默认值的 INI官方文档对这套 API 的定位非常明确The configuration file functions are a simple implementation of the INI file format, with the addition of default values.使用方式从 C 头文件引入即可#include util/config-file.h核心类型为config_t对应 C 实现中的struct config_data。文档将全部 API 分为四组Config File Functionsconfig_create/config_open/config_open_string/config_save/config_save_safe/config_close以及分区查询config_num_sections/config_get_sectionSet/Get Functionsconfig_set_*与config_get_*五种类型string / int / uint / bool / double以及config_remove_valueDefault Value Functionsconfig_open_defaults、config_set_default_*、config_get_default_*状态查询config_has_user_value/config_has_default_value。头文件 config-file.h 中有一段被文档省略但极为重要的注释值得所有调用者注意/* * Generic ini-style config file functions * * NOTE: It is highly recommended to use the default value functions (bottom of * the file) before reading any variables from config files. */即在读取任何配置项之前先批量注册默认值。OBS 前端正是遵循这一约定见第 6 节的实际案例。状态码与打开模式在 config-file.h 中定义常量值含义CONFIG_SUCCESS0操作成功CONFIG_FILENOTFOUND-1文件不存在CONFIG_ERROR-2一般性错误enum config_open_type { CONFIG_OPEN_EXISTING, /* 文件不存在则失败 */ CONFIG_OPEN_ALWAYS, /* 文件不存在则创建 */ };2. 底层数据结构三层哈希模型从源码结构看config-file.c一个config_t内部由两级 uthash 哈希表和一把递归互斥锁构成struct config_item { /* 一个键值对 */ char *name; char *value; UT_hash_handle hh; }; struct config_section { /* 一个 [Section]内含 item 哈希表 */ char *name; struct config_item *items; UT_hash_handle hh; }; struct config_data { /* 即 config_t */ char *file; /* 关联的文件路径可为 NULL字符串打开 */ struct config_section *sections; /* 用户值来自配置文件 */ struct config_section *defaults; /* 默认值程序内注册 */ pthread_mutex_t mutex; /* 递归锁保证线程安全 */ };两个要点用户值与默认值物理隔离sections存从文件读入或config_set_*写入的值defaults只存默认值。config_get_*的查找顺序是「先sectionsmiss 后再查defaults」这正是文档中「If the value is not set, it will use the default value」的实现基础config-file.citem config_find_item(config-sections, section, name); if (!item) item config_find_item(config-defaults, section, name); if (item) value item-value;所有公开接口都会先持有递归互斥锁如 config-file.c 的pthread_mutex_lock(config-mutex)因此多线程场景下对同一config_t的读写是安全的。3. Config File Functions创建、打开与保存3.1 config_createconfig_t *config_create(const char *file);创建一个新的配置对象并关联到指定文件路径。参数file为新配置文件路径返回新建的配置对象失败返回NULL。从实现看config-file.c它实际执行了「以wb模式打开并立即关闭文件」的动作——也就是清空/截断该文件然后分配config_data并初始化递归锁。因此这个函数语义上是「新建一个空配置文件」不要用它打开已有配置否则旧内容会被抹掉。3.2 config_openint config_open(config_t **config, const char *file, enum config_open_type open_type);打开配置文件参数与返回值如文档所述参数说明config出参成功时接收新配置对象指针file配置文件路径open_typeCONFIG_OPEN_EXISTING文件不存在则失败CONFIG_OPEN_ALWAYS不存在则创建返回CONFIG_SUCCESS/CONFIG_FILENOTFOUND/CONFIG_ERROR三者之一。实现细节config-file.cconfig_parse_file以rb打开文件仅当CONFIG_OPEN_ALWAYS且文件不存在时才改用w创建。一个容易踩坑的边界是空文件视为成功os_fread_utf8读到空数据时直接返回CONFIG_SUCCESS而CONFIG_OPEN_EXISTING下文件不存在则返回CONFIG_FILENOTFOUND并将*config置回NULL。3.3 config_open_stringint config_open_string(config_t **config, const char *str);从字符串而非文件打开配置数据。对应实现中config-file NULLconfig-file.c由此带来一个直接推论通过字符串打开的配置对象调用config_save会失败——config_save内部对config-file为空直接返回CONFIG_ERRORconfig-file.c。3.4 解析器能识别什么INI 解析由parse_config_data/config_parse_section完成config-file.c可总结为形如[Section]的行开启一个分区分区外出现的非分区行整行跳过分区内以#开头的行视为注释直到行尾键值行格式为namevalue取值部分取到行尾值支持反斜杠转义\\→ 反斜杠、\n→ 换行、\r→ 回车unescapeconfig-file.c。一个合法的配置文件示例# comment line, ignored by the parser [Video] BaseCX1920 FPS60 RendererOpenGL [Audio] SampleRate48000 PathC:\path\with\backslash # 反斜杠写入文件时应转义为 \\4. Set/Get Functions五种类型的读写语义4.1 写接口五个写接口签名config-file.hvoid config_set_string(config_t *config, const char *section, const char *name, const char *value); void config_set_int (config_t *config, const char *section, const char *name, int64_t value); void config_set_uint (config_t *config, const char *section, const char *name, uint64_t value); void config_set_bool (config_t *config, const char *section, const char *name, bool value); void config_set_double(config_t *config, const char *section, const char *name, double value);参数含义一致config配置对象、section所属分区、name键名、value值。它们没有错误返回行为语义如下value在内存中永远以字符串形态存放config_item.value即char*整型/浮点只是序列化格式差异int/uint按十进制打印bool序列化为字面量true/falsedouble经平台os_dtostr格式化config-file.c目标分区不存在时自动创建键已存在则原地替换旧值config_set_itemconfig-file.cconfig_set_string允许传入NULL会被规范化为空字符串。4.2 读接口与默认回退const char *config_get_string(config_t *config, const char *section, const char *name); int64_t config_get_int (config_t *config, const char *section, const char *name); uint64_t config_get_uint (config_t *config, const char *section, const char *name); bool config_get_bool (config_t *config, const char *section, const char *name); double config_get_double(config_t *config, const char *section, const char *name);文档给出的回退规则为值未设置时使用默认值无默认值时 string 返回NULLint/uint 返回0bool 返回falsedouble 返回0.0。源码层面还有几个文档未展开、但对调用者有用的解析细节十六进制支持str_to_int64/str_to_uint64识别0x前缀并按 16 进制解析否则按 10 进制config-file.c。也就是说配置文件里写Value0x10config_get_int会返回 16bool 的宽松判定config_get_bool对true大小写不敏感或非零数字都返回trueconfig-file.cbool config_get_bool(config_t *config, const char *section, const char *name) { const char *value config_get_string(config, section, name); if (value) return astrcmpi(value, true) 0 || !!str_to_uint64(value); return false; }所有 get 接口在加锁状态下先查用户值、再查默认值因此返回值指向的字符串生命周期由config_t持有在config_close之前有效调用者不能free它。4.3 分区枚举与删除size_t config_num_sections(config_t *config); const char *config_get_section(config_t *config, size_t idx); bool config_remove_value(config_t *config, const char *section, const char *name);config_num_sections直接返回sections哈希表条目数config_get_section按迭代顺序uthash 的插入序取第idx个分区名越界返回NULLconfig-file.c。注意迭代顺序并非字典序依赖「第 N 个分区是某某」的逻辑并不可靠更稳妥的写法是枚举后按名字匹配config_remove_value只从用户值表sections中删除该键不影响默认值——这正是文档强调的「Does not remove the default value if any」删除后再读该键会落回默认值。返回值为是否真正删除成功。5. Default Value Functions默认值机制5.1 注册默认值int config_open_defaults(config_t *config, const char *file); void config_set_default_string(config_t *config, const char *section, const char *name, const char *value); void config_set_default_int (config_t *config, const char *section, const char *name, int64_t value); void config_set_default_uint (config_t *config, const char *section, const char *name, uint64_t value); void config_set_default_bool (config_t *config, const char *section, const char *name, bool value); void config_set_default_double(config_t *config, const char *section, const char *name, double value);config_set_default_*用于程序内逐个注册默认值文档与头文件注释都建议优先此方式config_open_defaults则把另一个 INI 文件的整体内容作为默认值表载入config_parse_file(config-defaults, file, false)config-file.c。头文件注释config-file.h特别澄清了语义边界These donotactually set any values, they only set what values will be returned for config_get_* if the specified variable does not exist.默认值「不真正设置任何值」只是决定键缺失时config_get_*返回什么。一个反直觉的实现细节藏在config_set_item_defaultconfig-file.cstatic void config_set_item_default(config_t *config, const char *section, const char *name, char *value) { config_set_item(config, config-defaults, section, name, value); if (!config_has_user_value(config, section, name)) config_set_item(config, config-sections, section, name, bstrdup(value)); }若该键尚无用户值默认值会同时被复制一份进用户值表。实际效果是默认值随后一次config_save会被持久化进配置文件让新用户的配置文件自动带上完整默认项后续升级默认值变更时也能与用户显式设置的值区分开来。5.2 读取默认值与存在性查询const char *config_get_default_string (config_t *config, const char *section, const char *name); int64_t config_get_default_int (config_t *config, const char *section, const char *name); uint64_t config_get_default_uint (config_t *config, const char *section, const char *name); bool config_get_default_bool (config_t *config, const char *section, const char *name); double config_get_default_double (config_t *config, const char *section, const char *name);这组接口绕开用户值、直接读默认值表无默认值时分别返回NULL/0/0/false/0.0config-file.c。头文件注释评价它们「Probably almost never really needed」主要用于调试或导出「出厂值」。bool config_has_user_value (config_t *config, const char *section, const char *name); bool config_has_default_value(config_t *config, const char *section, const char *name);两者分别判断键是否已存在于用户值表、默认值表config-file.c。典型用法是「用户是否显式改过该项」若config_has_user_value为false说明当前读到的值来自默认UI 上可以据此显示「恢复默认」入口。6. 原子保存config_save 与 config_save_safe6.1 config_saveint config_save(config_t *config);把配置数据写回关联文件文档原话Saves configuration data to a file (if associated with a file)。返回CONFIG_SUCCESS/CONFIG_FILENOTFOUND/CONFIG_ERROR。写盘流程config-file.c值得细看在锁内把所有分区序列化为字符串每个分区输出[Section]头随后逐行keyvalue分区之间以空行分隔写盘前做转义且顺序有讲究——先\→\\再\r→\r字面量最后\n→\n字面量避免二次转义dstr_copy(tmp, item-value ? item-value : ); dstr_replace(tmp, \\, \\\\); dstr_replace(tmp, \r, \\r); dstr_replace(tmp, \n, \\n);这与第 3.4 节解析端的unescape严格互逆 3. 在 Windows 平台先写入 UTF-8 BOM\xEF\xBB\xBF再以wb一次性写出全部内容。两个限制要牢记未关联文件的对象config_open_string创建保存必败默认值不会被写盘——序列化只遍历config-sections。6.2 config_save_safeint config_save_safe(config_t *config, const char *temp_ext, const char *backup_ext);文档描述Saves configuration data and minimizes overwrite corruption risk.参数temp_ext为临时文件扩展名backup_ext为旧文件备份扩展名传NULL表示不保留备份。实现是标准的「临时文件 原子替换」策略config-file.c校验temp_ext非空否则直接返回CONFIG_ERROR并打日志临时把config-file指向原路径 . temp_ext自动补点号调config_save写出临时文件若指定了backup_ext把目标路径备份为原路径 . backup_ext调用平台层os_safe_replace(file, temp, backup)完成重命名最后恢复config-file。os_safe_replace的 POSIX 实现只有两步先rename(target, backup)再rename(from, target)platform-nix.c。由于rename在同一文件系统内是原子操作即使进程在两步之间崩溃最坏情况也只是留下「临时文件已写、正式文件尚未就位」的状态原配置文件本身不会被截断成半个文件——这就是「minimizes overwrite corruption risk」的实质。6.3 OBS 前端的真实用法OBS Studio 全部配置落盘点几乎统一走SaveSafe(tmp)例如退出、切换 Profile、保存设置时config_save_safe(App()-GetUserConfig(), tmp, nullptr); // frontend/widgets/OBSBasic.cpp config_save_safe(main-Config(), tmp, nullptr); // frontend/settings/OBSBasicSettings.cpp仓库中所有调用点都传tmp且不带备份可搜索config_save_safe(找到 20 余处。而 plugins/win-capture/load-graphics-offsets.c 则展示了另一种组合——先用config_open(config, ver_file, CONFIG_OPEN_ALWAYS)打开「不存在则创建」的版本号文件写入后再config_save_safe(config, tmp, NULL)。C 侧还有一层薄封装ConfigFilelibobs/util/util.hpp把上述 C API 映射为OpenString/Open/Save/SaveSafe/Close并提供operator config_t *()以便直接以裸指针传给 C 接口。7. 完整实战示例一套典型的配置读写流程综合以上全部接口下面是一个贴近 OBS 用法的完整示例可直接复制到独立工程编译链接 libobs 的 util 即可#include stdio.h #include util/config-file.h int main(void) { config_t *config NULL; /* 1. 打开不存在则创建 */ if (config_open(config, settings.ini, CONFIG_OPEN_ALWAYS) ! CONFIG_SUCCESS) return 1; /* 2. 先注册默认值头文件强烈建议读之前先设默认 */ config_set_default_string(config, General, NickName, Anonymous); config_set_default_int(config, Video, FPS, 60); config_set_default_uint(config, Video, BaseCX, 1920); config_set_default_bool(config, General, ConfirmOnExit, true); config_set_default_double(config, BasicWindow, SnapDistance, 10.0); /* 3. 读未设置时自动回退默认值 */ printf(nick%s fps%lld rate%llu exit%d snap%g\n, config_get_string(config, General, NickName), (long long)config_get_int(config, Video, FPS), (unsigned long long)config_get_uint(config, Video, BaseCX), config_get_bool(config, General, ConfirmOnExit), config_get_double(config, BasicWindow, SnapDistance)); /* 4. 用户是否显式改过 FPS */ if (config_has_user_value(config, Video, FPS)) printf(FPS was explicitly set by user\n); /* 5. 写整型、十六进制读回演示、删除演示 */ config_set_int(config, Video, FPS, 120); config_set_string(config, General, Path, C:\\new\\path); config_remove_value(config, General, NickName); /* 删用户值默认值仍在 */ /* 6. 原子保存写 settings.ini.tmp 再 rename 覆盖 */ if (config_save_safe(config, tmp, bak) ! CONFIG_SUCCESS) return 1; /* 7. 分区枚举 释放 */ for (size_t i 0; i config_num_sections(config); i) printf(section[%zu] %s\n, i, config_get_section(config, i)); config_close(config); return 0; }执行后settings.ini中会看到含转义后的反斜杠与 Windows BOM[General] PathC:\new\path ConfirmOnExittrue [Video] FPS120 [BasicWindow] SnapDistance108. 生命周期与错误处理小结步骤函数失败行为 / 注意点新建空文件config_create会截断已有文件文件不可创建时返回NULL打开文件config_open失败时*config被置NULL空文件视为成功打开字符串config_open_stringfile为NULL不可config_save载入默认表config_open_defaults文件不存在返回CONFIG_FILENOTFOUND保存config_save/config_save_safe前者直接覆盖写后者临时文件 原子 renametemp_ext必填、backup_ext可NULL释放config_close释放两个哈希表全部条目、锁与路径字符串调用后对象不可再使用需要特别强调的三条工程约束默认值必须「一次注册、处处生效」头文件注释要求每个已知键只调用一次config_set_default_*且在任何读取之前完成返回值所有权config_get_string系列返回的指针归config_t所有config_close之后立即失效保存只写用户值想保证磁盘文件完整可回读应像config_set_item_default那样依赖「默认值在无用户值时会落入用户表」这一机制或显式config_set_*一次。从源码结构看这套 API 体量很小但闭环完整uthash 提供 O(1) 的分区/键查找递归互斥锁覆盖全部读写路径转义与原子替换保证了含反斜杠、换行的值和断电/崩溃场景下配置文件的一致性。OBS Studio 从主程序设置user.ini、basic.ini到 OAuth 令牌frontend/oauth/Auth.cpp、回放缓冲参数frontend/widgets/OBSBasic_ReplayBuffer.cpp都构建在这一层之上——理解本文覆盖的每个函数语义就等于掌握了 OBS 配置系统的全部地基。【免费下载链接】obs-studioOBS Studio - Free and open source software for live streaming and screen recording项目地址: https://gitcode.com/GitHub_Trending/ob/obs-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OBS Studio libobs config_t 配置系统：带默认值机制的 INI 文件 API 全解
OBS Studio libobs config_t 配置系统带默认值机制的 INI 文件 API 全解【免费下载链接】obs-studioOBS Studio - Free and open source software for live streaming and screen recording项目地址: https://gitcode.com/GitHub_Trending/ob/obs-studio本文基于 libobs 官方 API 参考文档 Config Files 文档 及其底层实现 libobs/util/config-file.h、libobs/util/config-file.c 编写。libobs 的配置系统是一套「带默认值机制的简易 INI 实现」OBS Studio 主界面所有窗口尺寸、编码参数、OAuth 凭据等持久化数据都通过它落盘。读完本文你将完整掌握config_t的全套 C API创建、打开、读写、默认值、原子保存理解其数据结构与转义规则并能像 OBS 前端那样编写健壮的配置读写代码。1. API 概览一份带默认值的 INI官方文档对这套 API 的定位非常明确The configuration file functions are a simple implementation of the INI file format, with the addition of default values.使用方式从 C 头文件引入即可#include util/config-file.h核心类型为config_t对应 C 实现中的struct config_data。文档将全部 API 分为四组Config File Functionsconfig_create/config_open/config_open_string/config_save/config_save_safe/config_close以及分区查询config_num_sections/config_get_sectionSet/Get Functionsconfig_set_*与config_get_*五种类型string / int / uint / bool / double以及config_remove_valueDefault Value Functionsconfig_open_defaults、config_set_default_*、config_get_default_*状态查询config_has_user_value/config_has_default_value。头文件 config-file.h 中有一段被文档省略但极为重要的注释值得所有调用者注意/* * Generic ini-style config file functions * * NOTE: It is highly recommended to use the default value functions (bottom of * the file) before reading any variables from config files. */即在读取任何配置项之前先批量注册默认值。OBS 前端正是遵循这一约定见第 6 节的实际案例。状态码与打开模式在 config-file.h 中定义常量值含义CONFIG_SUCCESS0操作成功CONFIG_FILENOTFOUND-1文件不存在CONFIG_ERROR-2一般性错误enum config_open_type { CONFIG_OPEN_EXISTING, /* 文件不存在则失败 */ CONFIG_OPEN_ALWAYS, /* 文件不存在则创建 */ };2. 底层数据结构三层哈希模型从源码结构看config-file.c一个config_t内部由两级 uthash 哈希表和一把递归互斥锁构成struct config_item { /* 一个键值对 */ char *name; char *value; UT_hash_handle hh; }; struct config_section { /* 一个 [Section]内含 item 哈希表 */ char *name; struct config_item *items; UT_hash_handle hh; }; struct config_data { /* 即 config_t */ char *file; /* 关联的文件路径可为 NULL字符串打开 */ struct config_section *sections; /* 用户值来自配置文件 */ struct config_section *defaults; /* 默认值程序内注册 */ pthread_mutex_t mutex; /* 递归锁保证线程安全 */ };两个要点用户值与默认值物理隔离sections存从文件读入或config_set_*写入的值defaults只存默认值。config_get_*的查找顺序是「先sectionsmiss 后再查defaults」这正是文档中「If the value is not set, it will use the default value」的实现基础config-file.citem config_find_item(config-sections, section, name); if (!item) item config_find_item(config-defaults, section, name); if (item) value item-value;所有公开接口都会先持有递归互斥锁如 config-file.c 的pthread_mutex_lock(config-mutex)因此多线程场景下对同一config_t的读写是安全的。3. Config File Functions创建、打开与保存3.1 config_createconfig_t *config_create(const char *file);创建一个新的配置对象并关联到指定文件路径。参数file为新配置文件路径返回新建的配置对象失败返回NULL。从实现看config-file.c它实际执行了「以wb模式打开并立即关闭文件」的动作——也就是清空/截断该文件然后分配config_data并初始化递归锁。因此这个函数语义上是「新建一个空配置文件」不要用它打开已有配置否则旧内容会被抹掉。3.2 config_openint config_open(config_t **config, const char *file, enum config_open_type open_type);打开配置文件参数与返回值如文档所述参数说明config出参成功时接收新配置对象指针file配置文件路径open_typeCONFIG_OPEN_EXISTING文件不存在则失败CONFIG_OPEN_ALWAYS不存在则创建返回CONFIG_SUCCESS/CONFIG_FILENOTFOUND/CONFIG_ERROR三者之一。实现细节config-file.cconfig_parse_file以rb打开文件仅当CONFIG_OPEN_ALWAYS且文件不存在时才改用w创建。一个容易踩坑的边界是空文件视为成功os_fread_utf8读到空数据时直接返回CONFIG_SUCCESS而CONFIG_OPEN_EXISTING下文件不存在则返回CONFIG_FILENOTFOUND并将*config置回NULL。3.3 config_open_stringint config_open_string(config_t **config, const char *str);从字符串而非文件打开配置数据。对应实现中config-file NULLconfig-file.c由此带来一个直接推论通过字符串打开的配置对象调用config_save会失败——config_save内部对config-file为空直接返回CONFIG_ERRORconfig-file.c。3.4 解析器能识别什么INI 解析由parse_config_data/config_parse_section完成config-file.c可总结为形如[Section]的行开启一个分区分区外出现的非分区行整行跳过分区内以#开头的行视为注释直到行尾键值行格式为namevalue取值部分取到行尾值支持反斜杠转义\\→ 反斜杠、\n→ 换行、\r→ 回车unescapeconfig-file.c。一个合法的配置文件示例# comment line, ignored by the parser [Video] BaseCX1920 FPS60 RendererOpenGL [Audio] SampleRate48000 PathC:\path\with\backslash # 反斜杠写入文件时应转义为 \\4. Set/Get Functions五种类型的读写语义4.1 写接口五个写接口签名config-file.hvoid config_set_string(config_t *config, const char *section, const char *name, const char *value); void config_set_int (config_t *config, const char *section, const char *name, int64_t value); void config_set_uint (config_t *config, const char *section, const char *name, uint64_t value); void config_set_bool (config_t *config, const char *section, const char *name, bool value); void config_set_double(config_t *config, const char *section, const char *name, double value);参数含义一致config配置对象、section所属分区、name键名、value值。它们没有错误返回行为语义如下value在内存中永远以字符串形态存放config_item.value即char*整型/浮点只是序列化格式差异int/uint按十进制打印bool序列化为字面量true/falsedouble经平台os_dtostr格式化config-file.c目标分区不存在时自动创建键已存在则原地替换旧值config_set_itemconfig-file.cconfig_set_string允许传入NULL会被规范化为空字符串。4.2 读接口与默认回退const char *config_get_string(config_t *config, const char *section, const char *name); int64_t config_get_int (config_t *config, const char *section, const char *name); uint64_t config_get_uint (config_t *config, const char *section, const char *name); bool config_get_bool (config_t *config, const char *section, const char *name); double config_get_double(config_t *config, const char *section, const char *name);文档给出的回退规则为值未设置时使用默认值无默认值时 string 返回NULLint/uint 返回0bool 返回falsedouble 返回0.0。源码层面还有几个文档未展开、但对调用者有用的解析细节十六进制支持str_to_int64/str_to_uint64识别0x前缀并按 16 进制解析否则按 10 进制config-file.c。也就是说配置文件里写Value0x10config_get_int会返回 16bool 的宽松判定config_get_bool对true大小写不敏感或非零数字都返回trueconfig-file.cbool config_get_bool(config_t *config, const char *section, const char *name) { const char *value config_get_string(config, section, name); if (value) return astrcmpi(value, true) 0 || !!str_to_uint64(value); return false; }所有 get 接口在加锁状态下先查用户值、再查默认值因此返回值指向的字符串生命周期由config_t持有在config_close之前有效调用者不能free它。4.3 分区枚举与删除size_t config_num_sections(config_t *config); const char *config_get_section(config_t *config, size_t idx); bool config_remove_value(config_t *config, const char *section, const char *name);config_num_sections直接返回sections哈希表条目数config_get_section按迭代顺序uthash 的插入序取第idx个分区名越界返回NULLconfig-file.c。注意迭代顺序并非字典序依赖「第 N 个分区是某某」的逻辑并不可靠更稳妥的写法是枚举后按名字匹配config_remove_value只从用户值表sections中删除该键不影响默认值——这正是文档强调的「Does not remove the default value if any」删除后再读该键会落回默认值。返回值为是否真正删除成功。5. Default Value Functions默认值机制5.1 注册默认值int config_open_defaults(config_t *config, const char *file); void config_set_default_string(config_t *config, const char *section, const char *name, const char *value); void config_set_default_int (config_t *config, const char *section, const char *name, int64_t value); void config_set_default_uint (config_t *config, const char *section, const char *name, uint64_t value); void config_set_default_bool (config_t *config, const char *section, const char *name, bool value); void config_set_default_double(config_t *config, const char *section, const char *name, double value);config_set_default_*用于程序内逐个注册默认值文档与头文件注释都建议优先此方式config_open_defaults则把另一个 INI 文件的整体内容作为默认值表载入config_parse_file(config-defaults, file, false)config-file.c。头文件注释config-file.h特别澄清了语义边界These donotactually set any values, they only set what values will be returned for config_get_* if the specified variable does not exist.默认值「不真正设置任何值」只是决定键缺失时config_get_*返回什么。一个反直觉的实现细节藏在config_set_item_defaultconfig-file.cstatic void config_set_item_default(config_t *config, const char *section, const char *name, char *value) { config_set_item(config, config-defaults, section, name, value); if (!config_has_user_value(config, section, name)) config_set_item(config, config-sections, section, name, bstrdup(value)); }若该键尚无用户值默认值会同时被复制一份进用户值表。实际效果是默认值随后一次config_save会被持久化进配置文件让新用户的配置文件自动带上完整默认项后续升级默认值变更时也能与用户显式设置的值区分开来。5.2 读取默认值与存在性查询const char *config_get_default_string (config_t *config, const char *section, const char *name); int64_t config_get_default_int (config_t *config, const char *section, const char *name); uint64_t config_get_default_uint (config_t *config, const char *section, const char *name); bool config_get_default_bool (config_t *config, const char *section, const char *name); double config_get_default_double (config_t *config, const char *section, const char *name);这组接口绕开用户值、直接读默认值表无默认值时分别返回NULL/0/0/false/0.0config-file.c。头文件注释评价它们「Probably almost never really needed」主要用于调试或导出「出厂值」。bool config_has_user_value (config_t *config, const char *section, const char *name); bool config_has_default_value(config_t *config, const char *section, const char *name);两者分别判断键是否已存在于用户值表、默认值表config-file.c。典型用法是「用户是否显式改过该项」若config_has_user_value为false说明当前读到的值来自默认UI 上可以据此显示「恢复默认」入口。6. 原子保存config_save 与 config_save_safe6.1 config_saveint config_save(config_t *config);把配置数据写回关联文件文档原话Saves configuration data to a file (if associated with a file)。返回CONFIG_SUCCESS/CONFIG_FILENOTFOUND/CONFIG_ERROR。写盘流程config-file.c值得细看在锁内把所有分区序列化为字符串每个分区输出[Section]头随后逐行keyvalue分区之间以空行分隔写盘前做转义且顺序有讲究——先\→\\再\r→\r字面量最后\n→\n字面量避免二次转义dstr_copy(tmp, item-value ? item-value : ); dstr_replace(tmp, \\, \\\\); dstr_replace(tmp, \r, \\r); dstr_replace(tmp, \n, \\n);这与第 3.4 节解析端的unescape严格互逆 3. 在 Windows 平台先写入 UTF-8 BOM\xEF\xBB\xBF再以wb一次性写出全部内容。两个限制要牢记未关联文件的对象config_open_string创建保存必败默认值不会被写盘——序列化只遍历config-sections。6.2 config_save_safeint config_save_safe(config_t *config, const char *temp_ext, const char *backup_ext);文档描述Saves configuration data and minimizes overwrite corruption risk.参数temp_ext为临时文件扩展名backup_ext为旧文件备份扩展名传NULL表示不保留备份。实现是标准的「临时文件 原子替换」策略config-file.c校验temp_ext非空否则直接返回CONFIG_ERROR并打日志临时把config-file指向原路径 . temp_ext自动补点号调config_save写出临时文件若指定了backup_ext把目标路径备份为原路径 . backup_ext调用平台层os_safe_replace(file, temp, backup)完成重命名最后恢复config-file。os_safe_replace的 POSIX 实现只有两步先rename(target, backup)再rename(from, target)platform-nix.c。由于rename在同一文件系统内是原子操作即使进程在两步之间崩溃最坏情况也只是留下「临时文件已写、正式文件尚未就位」的状态原配置文件本身不会被截断成半个文件——这就是「minimizes overwrite corruption risk」的实质。6.3 OBS 前端的真实用法OBS Studio 全部配置落盘点几乎统一走SaveSafe(tmp)例如退出、切换 Profile、保存设置时config_save_safe(App()-GetUserConfig(), tmp, nullptr); // frontend/widgets/OBSBasic.cpp config_save_safe(main-Config(), tmp, nullptr); // frontend/settings/OBSBasicSettings.cpp仓库中所有调用点都传tmp且不带备份可搜索config_save_safe(找到 20 余处。而 plugins/win-capture/load-graphics-offsets.c 则展示了另一种组合——先用config_open(config, ver_file, CONFIG_OPEN_ALWAYS)打开「不存在则创建」的版本号文件写入后再config_save_safe(config, tmp, NULL)。C 侧还有一层薄封装ConfigFilelibobs/util/util.hpp把上述 C API 映射为OpenString/Open/Save/SaveSafe/Close并提供operator config_t *()以便直接以裸指针传给 C 接口。7. 完整实战示例一套典型的配置读写流程综合以上全部接口下面是一个贴近 OBS 用法的完整示例可直接复制到独立工程编译链接 libobs 的 util 即可#include stdio.h #include util/config-file.h int main(void) { config_t *config NULL; /* 1. 打开不存在则创建 */ if (config_open(config, settings.ini, CONFIG_OPEN_ALWAYS) ! CONFIG_SUCCESS) return 1; /* 2. 先注册默认值头文件强烈建议读之前先设默认 */ config_set_default_string(config, General, NickName, Anonymous); config_set_default_int(config, Video, FPS, 60); config_set_default_uint(config, Video, BaseCX, 1920); config_set_default_bool(config, General, ConfirmOnExit, true); config_set_default_double(config, BasicWindow, SnapDistance, 10.0); /* 3. 读未设置时自动回退默认值 */ printf(nick%s fps%lld rate%llu exit%d snap%g\n, config_get_string(config, General, NickName), (long long)config_get_int(config, Video, FPS), (unsigned long long)config_get_uint(config, Video, BaseCX), config_get_bool(config, General, ConfirmOnExit), config_get_double(config, BasicWindow, SnapDistance)); /* 4. 用户是否显式改过 FPS */ if (config_has_user_value(config, Video, FPS)) printf(FPS was explicitly set by user\n); /* 5. 写整型、十六进制读回演示、删除演示 */ config_set_int(config, Video, FPS, 120); config_set_string(config, General, Path, C:\\new\\path); config_remove_value(config, General, NickName); /* 删用户值默认值仍在 */ /* 6. 原子保存写 settings.ini.tmp 再 rename 覆盖 */ if (config_save_safe(config, tmp, bak) ! CONFIG_SUCCESS) return 1; /* 7. 分区枚举 释放 */ for (size_t i 0; i config_num_sections(config); i) printf(section[%zu] %s\n, i, config_get_section(config, i)); config_close(config); return 0; }执行后settings.ini中会看到含转义后的反斜杠与 Windows BOM[General] PathC:\new\path ConfirmOnExittrue [Video] FPS120 [BasicWindow] SnapDistance108. 生命周期与错误处理小结步骤函数失败行为 / 注意点新建空文件config_create会截断已有文件文件不可创建时返回NULL打开文件config_open失败时*config被置NULL空文件视为成功打开字符串config_open_stringfile为NULL不可config_save载入默认表config_open_defaults文件不存在返回CONFIG_FILENOTFOUND保存config_save/config_save_safe前者直接覆盖写后者临时文件 原子 renametemp_ext必填、backup_ext可NULL释放config_close释放两个哈希表全部条目、锁与路径字符串调用后对象不可再使用需要特别强调的三条工程约束默认值必须「一次注册、处处生效」头文件注释要求每个已知键只调用一次config_set_default_*且在任何读取之前完成返回值所有权config_get_string系列返回的指针归config_t所有config_close之后立即失效保存只写用户值想保证磁盘文件完整可回读应像config_set_item_default那样依赖「默认值在无用户值时会落入用户表」这一机制或显式config_set_*一次。从源码结构看这套 API 体量很小但闭环完整uthash 提供 O(1) 的分区/键查找递归互斥锁覆盖全部读写路径转义与原子替换保证了含反斜杠、换行的值和断电/崩溃场景下配置文件的一致性。OBS Studio 从主程序设置user.ini、basic.ini到 OAuth 令牌frontend/oauth/Auth.cpp、回放缓冲参数frontend/widgets/OBSBasic_ReplayBuffer.cpp都构建在这一层之上——理解本文覆盖的每个函数语义就等于掌握了 OBS 配置系统的全部地基。【免费下载链接】obs-studioOBS Studio - Free and open source software for live streaming and screen recording项目地址: https://gitcode.com/GitHub_Trending/ob/obs-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
