kala13x/libxutils

 [](https://github.com/kala13x/libxutils/blob/main/LICENSE) [](https://github.com/kala13x/libxutils/actions/workflows/linux.yml) [](https://github.com/kala13x/libxutils/actions/workflows/macos.yml) [](https://github.com/kala13x/libxutils/actions/workflows/windows.yml) [](https://github.com/kala13x/libxutils/actions/workflows/codeql.yml) ## libxutils - 跨平台 C 语言库 2.x 版本 `libxutils` 是一个底层跨平台 `C` 语言库，旨在消除拼接数十个互不相关库的需求。 它提供统一的、事件驱动的运行时，具有一致的 API，用于网络、数据结构、加密和系统工具，专为性能关键型原生应用而优化。 该库面向 `Linux`、`Unix` 和 `Windows`，采用 `MIT` 许可证发布。 ## 核心优势 - 一个一致的底层栈，替代多个库 - 明确的内存和所有权模型 - 事件驱动架构 - 最小依赖，可选 `OpenSSL` - 专为需要控制性和可预测性的高性能原生软件设计 ## 核心优势：网络 `libxutils` 最强大的方面是网络。 无需为套接字、事件循环、HTTP、WebSocket、SSL 和协议粘合组合单独的库，`libxutils` 将它们整合在一个库中，共享缓冲区、回调、所有权和运行时流的约定。 内置的网络组件包括： - 原始套接字、Unix 套接字、`TCP` 和 `UDP` - `SSL`（可选） - `HTTP` - `WebSocket` - `MDTP` - 跨平台事件循环集成 HTTP、WebSocket 和原始 TCP 共享相同的回调模型、端点设置和事件循环。只需更改一个枚举即可切换协议——其余代码保持不变。更重要的是，它们可以共存：一个实例可以在一个端口上提供 HTTP API，在另一个端口上提供 WebSocket 提要，在第三个端口上提供原始 TCP 控制通道，所有这些都通过一个服务循环进行多路复用，无需线程。 ## 典型用例 - 高性能网络服务，如 `HTTP` 和 `WebSocket` 服务器、网关和代理 - 需要在单个二进制文件中集成网络、JSON、加密和文件系统支持的 CLI 工具 - 具有最小依赖要求的嵌入式或系统级软件 - 自定义运行时和协议实现 - 通过 `FFI` 暴露给高级语言的原生后端 ## 为什么选择 libxutils？ libxutils 始于 2015 年的个人工具库，经过多年实际使用，已演变为一个专注的、经过生产验证的技术栈。 该库围绕可预测的性能和明确的资源控制设计。没有隐藏的分配，没有隐式线程，也没有垃圾回收层——内存所有权在调用点始终可见。 每个提交都会在 CI 管道中通过 Valgrind 进行测试，以在发布前捕获泄漏、无效读取和释放后使用错误。结合在每次推送时运行的 CodeQL 静态分析，代码库持续接受内存安全和整体质量检查。 其结果是一个保持小巧、构建快速且在长期运行的服务器或短期运行的 CLI 工具中表现一致的库。 ## 与其他技术栈的比较 | 特性 | libxutils | libuv | boost::asio | curl + 临时技术栈 | |---|---|---|---|---| | 集成完整技术栈 | ✔️ | ❌ | ❌ | ❌ | | 事件循环 | ✔️ | ✔️ | ✔️ | ❌ | | 内置 HTTP/WebSocket | ✔️ | ❌ | ❌ | ❌ | | 内置加密辅助工具 | ✔️ | ❌ | ❌ | ❌ | | 最小外部依赖 | ✔️ | ✔️ | ❌ | ❌ | | 生态系统成熟度 | 中等 | 高 | 高 | 高 | | 社区/采用率 | 增长中 | 非常高 | 非常高 | 非常高 | | 高级抽象 | 选择性 | 有限 | 中等 | 不等 | | 学习曲线 | 中等 | 中等 | 较高 | 不等 | 此比较反映了每个库开箱即提供的功能，无需额外的库或集成。 ## 文档 完整文档可在 [docs](docs/README.md) 目录中获取。 - 从 [docs/README.md](docs/README.md) 开始获取完整索引 - 分类索引可在 [networking](docs/net/README.md)、[data](docs/data/README.md)、[crypto](docs/crypt/README.md) 和 [system](docs/sys/README.md) 中获取 - `docs/` 树记录了 `src/` 中的实际行为，包括参数、返回值、回调约定和已知特性 ## 库模块 以下每个模块都链接到带有 API 约定和行为的文档。 ### 网络 - [HTTP、WebSocket、MDTP 和原始套接字的高级事件驱动 API](docs/net/api.md) - [跨平台套接字层](docs/net/sock.md) - [跨平台事件循环](docs/net/event.md) - [HTTP 解析器/客户端辅助工具](docs/net/http.md) - [WebSocket 帧处理](docs/net/ws.md) - [MDTP 数据包协议](docs/net/mdtp.md) - [RTP 数据包辅助工具](docs/net/rtp.md) - [地址/接口辅助工具](docs/net/addr.md) ### 数据和容器 - [动态数组](docs/data/array.md) - [字节/数据缓冲区](docs/data/buf.md) - [键/值映射](docs/data/map.md) - [哈希映射](docs/data/hash.md) - [链表](docs/data/list.md) - [C 字符串工具和动态字符串](docs/data/str.md) - [JSON 解析器/写入器/格式化工具](docs/data/json.md) - [JWT 解析器/写入器/验证器](docs/data/jwt.md) ### 加密和编码 - [加密调度辅助工具](docs/crypt/crypt.md) - [AES 加密和解密](docs/crypt/aes.md) - [Base64 和 Base64Url](docs/crypt/base64.md) - [RSA 辅助工具](docs/crypt/rsa.md) - [SHA-256](docs/crypt/sha256.md) - [SHA-1](docs/crypt/sha1.md) - [CRC32](docs/crypt/crc32.md) - [HMAC](docs/crypt/hmac.md) - [MD5](docs/crypt/md5.md) ### 系统和运行时 - [文件和目录操作](docs/sys/xfs.md) - [CPU 亲和性辅助工具](docs/sys/cpu.md) - [递归文件/内容搜索](docs/sys/srch.md) - [时间和日期辅助工具](docs/sys/xtime.md) - [资源监控](docs/sys/mon.md) - [内存池](docs/sys/pool.md) - [文件和屏幕日志记录](docs/sys/log.md) - [同步原语](docs/sys/sync.md) - [线程和重复任务](docs/sys/thread.md) ### 其他 - [CLI 辅助工具和进度条](docs/sys/cli.md) - [信号和守护进程辅助工具](docs/sys/sig.md) - [小型类型/格式辅助工具](docs/sys/type.md) - [NTP 客户端辅助工具](docs/net/ntp.md) - [版本辅助工具](docs/xver.md) ## 快速示例 最小化的事件驱动 HTTP 服务器示例。如需查看包含日志、超时、SSL 和完整连接生命周期处理的更完整实现，请参阅 [`examples/http-server.c`](examples/http-server.c)。 此示例展示核心事件驱动流程： - 接受连接 - 读取 HTTP 请求 - 组装响应 - 发送回去 - 关闭会话 ``` #include static int on_request(xapi_session_t *s) { xhttp_t *req = (xhttp_t*)s->pPacket; (void)req; // handle request here xhttp_t res; XHTTP_InitResponse(&res, 200, NULL); XHTTP_AddHeader(&res, "Content-Type", "text/plain"); const char *body = "Hello from libxutils\n"; XHTTP_Assemble(&res, (const uint8_t*)body, strlen(body)); XAPI_PutTxBuff(s, &res.rawData); XHTTP_Clear(&res); return XAPI_EnableEvent(s, XPOLLOUT); } static int callback(xapi_ctx_t *ctx, xapi_session_t *s) { switch (ctx->eCbType) { case XAPI_CB_ACCEPTED: return XAPI_SetEvents(s, XPOLLIN); case XAPI_CB_READ: return on_request(s); case XAPI_CB_COMPLETE: return XAPI_DISCONNECT; default: return XAPI_CONTINUE; } } int main(void) { xapi_t api; XAPI_Init(&api, callback, NULL); xapi_endpoint_t ep; XAPI_InitEndpoint(&ep); ep.pAddr = "0.0.0.0"; ep.nPort = 8080; ep.eType = XAPI_HTTP; ep.eRole = XAPI_SERVER; XAPI_AddEndpoint(&api, &ep); while (XAPI_Service(&api, 100) == XEVENTS_SUCCESS); XAPI_Destroy(&api); return 0; } ``` 单一抽象层涵盖 HTTP、WebSocket 和原始 TCP。相同的 `XAPI_Init` → `XAPI_AddEndpoint` → `XAPI_Service` 流程、相同的回调签名和相同的返回代码适用于任何协议。为一种传输编写的代码只需少量更改即可移植到另一种传输，从而消除了为每个协议组合单独库的集成成本。不同协议的多个端点也可以在同一事件循环中并行运行，使得从单个进程公开 HTTP API、WebSocket 流和原始 TCP 通道变得简单，无需线程或外部粘合代码。 ## 安装 有多种方式可以构建和安装该库。 ### 使用附带的脚本 这是在 Linux 和 macOS 上最简单的路径： ``` git clone https://github.com/kala13x/libxutils ./libxutils/build.sh --install ``` 支持的构建脚本选项- `--tool=` 选择 `cmake`、`smake` 或附带的 `make` - `--install` 构建后安装库和工具 - `--examples` 在构建中包含示例 - `--tools` 在构建中包含工具 - `--clean` 构建/安装后移除目标文件 如果省略 `--tool`，脚本默认使用 `cmake`。 ### 使用 CMake ``` git clone https://github.com/kala13x/libxutils cd libxutils cmake . && make sudo make install ``` ### 使用 SMake [SMake](https://github.com/kala13x/smake) 是 Linux/Unix 的简单 Makefile 生成器： ``` git clone https://github.com/kala13x/libxutils cd libxutils smake && make sudo make install ``` ### 使用附带的 Makefile 该项目也可以在 Linux 上使用预生成的 `Makefile` 构建： ``` export XUTILS_USE_SSL=y # Enable SSL-related features git clone https://github.com/kala13x/libxutils cd libxutils make sudo make install ``` ## 依赖项 `OpenSSL` 是唯一的外部依赖项，仅在需要 `SSL` 和 `RSA` 功能时才需要。如果缺少开发包，仍可以在没有 SSL 支持的情况下构建该库。 ### 安装 OpenSSL 开发包 Red Hat 系列：`sudo dnf install openssl-devel` Debian 系列：`sudo apt-get install libssl-dev` Windows：`choco install openssl` macOS：`brew install openssl` ## 使用方法 在项目中包含所需的 `` 头文件，并链接 `-lxutils`。 有关确切的运行时行为，请使用 [docs/](

`XTOP` 是一种类似 `HTOP` 的性能监控器，在单个 CLI 窗口中显示 CPU、内存和网络活动，并具有强大的 REST API 客户端/服务器（守护进程）模式及更多功能。它也是展示在该库之上可以构建多少功能的良好示例，无需添加大型外部技术栈。 构建 `tools/` 中的源代码后，运行 `sudo make install` 安装： - `xcrypt` - 文件和文本加密/解密 CLI 工具 - `xpass` - 安全密码管理器 CLI 工具 - `xjson` - JSON 格式化和压缩 CLI 工具 - `xhttp` - HTTP 客户端 CLI 工具 - `xhost` - hosts 文件搜索和修改 CLI 工具 - `xtop` - 资源监控 CLI 工具 - `xsrc` - 高级文件搜索 CLI 工具 运行每个工具时使用 `-h` 查看使用方法和版本信息。

标签：Bash脚本, libxutils, OpenSSL, SSL/TLS, TCP, UDP, Unix套接字, WebSocket, 事件驱动, 低级别编程, 依赖分析, 加密, 原生应用, 回调机制, 套接字, 安全测试工具, 客户端加密, 密码学, 并发编程, 开源库, 手动系统调用, 搜索引擎爬虫, 数据结构, 漏洞扫描器, 系统工具, 缓冲区管理, 网络编程