# netutil

**Repository Path**: pangxiongfei/netutil

## Basic Information

- **Project Name**: netutil
- **Description**: 网络小工具（支持udp和tcp）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# netutil 通用 Linux 网络库

## 一、项目简介
纯通用 Linux C99 网络静态库，无业务依赖。
支持 **TCP / UDP / Unix 域套接字**，提供上下文管理、事件驱动、统一接口。

### 主要能力
- IPv4 TCP 服务端 / 客户端
- IPv4 UDP 服务端 / 客户端
- Unix 域套接字 服务端 / 客户端
- Socket 通用操作：创建、绑定、非阻塞、超时配置
- TCP Keepalive 原生心跳保活
- SO_REUSEADDR 端口复用
- UDP SO_RCVBUF 接收缓冲（防丢包）
- TCP / Unix 发送循环重传
- 基于 poll 的事件驱动引擎
- pollfd 动态数组 calloc + realloc 2x 扩容
- 连接内嵌事件循环，尾插法管理
- 按连接类型分派回调
- 统一错误码体系

### 运行平台
- 仅支持：Linux
- 编译标准：C99
- 依赖：系统原生 socket / netinet / poll 头文件，无第三方库

## 二、目录结构
```
netutil/
├── CMakeLists.txt
├── README.md
├── include/
│   └── netutil/
│       ├── common.h            # 通用类型、NetAddr、EventMask、RetCode 错误码
│       ├── socket.h            # Socket 基础操作、超时、保活、接收缓冲
│       ├── tcp.h               # TCP 上下文与接口
│       ├── udp.h               # UDP 上下文与接口
│       ├── unix_socket.h       # Unix 域套接字上下文与接口
│       ├── connection.h        # 通用连接节点（链表，含回调指针）
│       └── event_handler.h     # poll 事件循环引擎（内嵌连接链表）
├── src/
│   ├── common.c
│   ├── socket.c
│   ├── tcp.c
│   ├── udp.c
│   ├── unix_socket.c
│   ├── connection.c
│   └── event_handler.c
├── test/
│   └── test_net.c              # TCP/UDP/Unix/事件循环/对话测试

```

## 三、编译说明
### 1. 本地独立编译
```bash
# 创建编译目录
mkdir build && cd build

# 生成构建文件
cmake ..

# 编译
make -j$(nproc)
```
编译产物：
- 静态库：`libnetutil.a`
- 测试程序：`test_net`

### 2. 测试运行

**TCP 通信（读写超时 + TCP 原生心跳）**
```bash
# 终端 1（服务端）
./test_net tcp_server
# 终端 2（客户端）
./test_net tcp_client
```
- 默认端口：9999，读写超时：5000ms
- TCP 心跳：空闲 10s 探测，间隔 3s，连续 3 次失败断开
- 端口复用已启用（SO_REUSEADDR）

**UDP 通信**
```bash
# 终端 1（服务端）
./test_net udp_server
# 终端 2（客户端）
./test_net udp_client
```
- 默认端口：8888，无连接概念
- 接收缓冲区：256KB（SO_RCVBUF），防止丢包

**Unix 域套接字（本地进程通信）**
```bash
# 终端 1（服务端）
./test_net unix_server
# 终端 2（客户端）
./test_net unix_client
```
- 套接字路径：/tmp/netutil.sock，权限掩码已自动放开（umask）
- 适用于本机多进程通信，不占用网络端口
- 异常处理：`rm -f /tmp/netutil.sock` 可清理残留文件

**事件循环 + 连接管理**
事件驱动模型示例：
- 事件循环内嵌连接链表（`ev->connections`）
- pollfd 动态扩容（`calloc` 初始 16 → `realloc` 2x 扩容）
- 按连接类型分派回调（服务端监听 / 客户端收发分别绑定不同回调）
- 连接断开自动回收资源
- Ctrl + C 优雅退出
```bash
# 启动事件循环服务端
./test_net event_loop
# 多客户端测试
./test_net tcp_client
```

**TCP 多轮对话测试（演示持续会话能力）**
```bash
# 终端 1（对话服务端）
./test_net tcp_dialog_server
# 终端 2（对话客户端）
./test_net tcp_dialog_client
```
对话流程：
1. 客户端发送 `Hello!` → 服务端回复 `Hi, nice to meet you!`
2. 客户端发送 `What's your name?` → 服务端回复 `I'm netutil server.`
3. 客户端发送 `How are you?` → 服务端回复 `I'm fine, thanks!`
4. 客户端发送 `Good to know!` → 服务端回复 `I got your message.`
5. 客户端发送 `quit` → 服务端回复 `Bye!` 并断开连接

## 四、核心设计说明

本库从成熟的网络守护进程模块剥离封装，逐文件逐函数核对，关键行为可靠对齐：

| 模块 | netutil | 能力说明 | 状态 |
|------|---------|---------|------|
| 套接字创建 | `socket_create_tcp/udp` 内嵌 SO_REUSEADDR | 端口复用 | ✅ |
| TCP 发送 | `tcp_send` while 循环分包重传 | 可靠发送 | ✅ |
| UDP 接收缓冲 | `socket_set_recvbuf(256KB)` | 防丢包 | ✅ |
| 事件引擎 | `poll()` 驱动 `event_loop_run` | 高效事件驱动 | ✅ |
| pfd 动态扩容 | `calloc(16) → event_enable_fd 内 realloc 2x` | 按需扩容 | ✅ |
| 事件注册 | `event_enable_fd` fd 追加 + 容量检测 | 动态注册 | ✅ |
| 事件删除 | `event_disable_fd` i/j 双游标压缩式删除 | O(n) 删除 | ✅ |
| 连接内嵌 | `EventLoop.connections` 内嵌链表 | 连接管理 | ✅ |
| 回调分派 | `conn->callback(loop, conn, mask)` 按连接分派 | 灵活回调 | ✅ |
| 连接注册 | `event_register_connection` 尾插+激活 | 连接注册 | ✅ |
| 连接注销 | `event_unregister_connection` 去激活+移除+销毁 | 资源回收 | ✅ |
| 连接节点 | `connection_create/destroy` + 尾插链表 | 节点管理 | ✅ |
| Unix 域权限 | `umask(0)` 临时放开 → 绑定 → 恢复 | 权限控制 | ✅ |
| Unix 发送 | `unix_send` while 循环可靠发送 | 可靠发送 | ✅ |
| Unix 接收 | 处理 EAGAIN → RET_TIMEOUT | 非阻塞语义 | ✅ |
| 错误码体系 | `RET_OK/ERROR/TIMEOUT/...` | 统一错误码 | ✅ |
| 错误事件处理 | `EVENT_MASK_REJECTED` 识别并回收连接 | 异常处理 | ✅ |
| init_poll_fd | 静态函数 `fd=-1; events=0; revents=0` | pollfd 初始化 | ✅ |

> **注：** 设计上通过 `Connection` 结构体存储回调指针实现分派，比硬编码 switch 更通用灵活，分派逻辑等价。

## 五、项目集成方式
将整个 netutil 目录放入主工程，修改主工程 CMakeLists.txt：

**添加子目录**
```cmake
add_subdirectory(netutil)
```

**链接静态库**
```cmake
target_link_libraries(your_target netutil)
```

**引用头文件**
```c
#include "netutil/tcp.h"
#include "netutil/udp.h"
#include "netutil/unix_socket.h"
#include "netutil/event_handler.h"
```