107 lines
2.8 KiB
Markdown
107 lines
2.8 KiB
Markdown
# liblog — 异步日志系统 API 参考
|
||
|
||
## 模块概述
|
||
|
||
liblog 是嵌入式装置专用的异步日志系统。支持 INFO/ERROR 两级日志，非阻塞写入。
|
||
首次调用自动初始化（pthread_once 懒启动）。控制台支持 ANSI 彩色输出，
|
||
文件支持按大小自动轮转。
|
||
|
||
**核心特性**:
|
||
- **消息池预分配**：10000 条消息槽位，运行时零 malloc
|
||
- **批量消费**：工作线程每次最多取 100 条，批量 I/O 减少系统调用
|
||
- **生产者-消费者模型**：`log_prt()` 入队（生产者）→ 工作线程出队写入（消费者）
|
||
- **文件轮转**：单文件超过 10MB 自动重命名为 `.1 → .2 → ... → .5`
|
||
|
||
## 常量与宏
|
||
|
||
| 宏 | 值 | 说明 |
|
||
|----|-----|------|
|
||
| `LOG_INFO` | 0 | INFO 级别（白色） |
|
||
| `LOG_ERROR` | 1 | ERROR 级别（红色） |
|
||
| `LOG_I(fmt, ...)` | — | INFO 便捷宏（自动填充文件名/函数名/行号） |
|
||
| `LOG_E(fmt, ...)` | — | ERROR 便捷宏 |
|
||
|
||
## 接口函数
|
||
|
||
### log_init(dir)
|
||
```c
|
||
int log_init(const char *dir);
|
||
```
|
||
手动初始化日志系统（可选）。首次调用 `log_prt()` 时会自动触发。
|
||
- `dir`: 日志目录路径，`NULL` 则默认 `/tmp/logs`
|
||
- 返回: 0 成功
|
||
|
||
### log_prt(level, file, func, line, fmt, ...)
|
||
```c
|
||
void log_prt(uint32_t level, const char *file, const char *func,
|
||
uint32_t line, const char *fmt, ...);
|
||
```
|
||
核心日志函数（非阻塞）。从消息池取空闲块 → 填充时间/来源 → 入队 → 立即返回。
|
||
|
||
**参数**:
|
||
- `level`: `LOG_INFO` 或 `LOG_ERROR`
|
||
- `file`: `__FILE__`（源文件名）
|
||
- `func`: `__FUNCTION__`（函数名）
|
||
- `line`: `__LINE__`（行号）
|
||
- `fmt, ...`: printf 格式化
|
||
|
||
### log_file_on / log_file_off
|
||
```c
|
||
void log_file_on(void);
|
||
void log_file_off(void);
|
||
```
|
||
开启/关闭文件写入。默认关闭，通过 `log_init()` 开启。
|
||
|
||
### log_console_on / log_console_off
|
||
```c
|
||
void log_console_on(void);
|
||
void log_console_off(void);
|
||
```
|
||
开启/关闭控制台输出。默认开启。
|
||
|
||
### log_flush(void)
|
||
```c
|
||
void log_flush(void);
|
||
```
|
||
阻塞等待消息队列清空（所有日志写入完成）。
|
||
|
||
### log_cleanup(void)
|
||
```c
|
||
void log_cleanup(void);
|
||
```
|
||
停止工作线程、关闭文件句柄、释放消息池。
|
||
|
||
## 使用示例
|
||
|
||
```c
|
||
#include "myLog.h"
|
||
|
||
int main(void)
|
||
{
|
||
// 手动初始化（可选），指定日志目录
|
||
log_init("/var/log/myapp");
|
||
|
||
// INFO 日志
|
||
LOG_I("系统启动完成, CPU=%.1f%%, MEM=%uMB", 45.2, 128);
|
||
|
||
// ERROR 日志（红色输出）
|
||
LOG_E("通讯超时: channel=%d, addr=%u", 3, 0x01);
|
||
|
||
// 开关控制
|
||
log_console_off(); // 关闭控制台（仅写文件）
|
||
LOG_I("仅文件输出");
|
||
log_console_on();
|
||
|
||
// 清理
|
||
log_flush();
|
||
log_cleanup();
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
## 依赖关系
|
||
|
||
- **依赖**: liblist (消息队列链表), libfunc (进程路径获取)
|
||
- **被依赖**: 所有需要日志的模块
|