printf 函数使用规范

[ English | 简体中文 ]

一、概述

printf 函数主要用于开发和调试阶段，在需要与用户直接交互的命令行工具中向标准输出（stdout）打印格式化信息。

核心原则：严禁在内核模块和后台服务中使用 printf。在此类场景下，应使用 syslog 作为标准日志记录方案。错误地使用 printf 会引发多核系统中的严重问题，例如服务阻塞、资源耗尽和日志混乱，对系统稳定性和实时性构成威胁。

二、适用场景：命令行交互

printf 的唯一推荐使用场景是开发需要直接与用户交互的命令行（CLI）应用程序。

功能：向控制台（终端）实时输出程序状态、用户提示或调试信息。
示例：一个需要用户输入参数并立即显示结果的工具。

三、禁用场景与核心风险分析

在以下场景中，必须禁止使用 printf：

内核模块（Kernel Modules）
后台服务与守护进程（Background Services & Daemons）

主要风险分析如下：

1、多核阻塞与 IPC 资源耗尽

在多核系统中，printf 的实现依赖于跨核的处理器间通信（IPC）。

工作机制：当非主核调用 printf 时，系统会通过 uart_rpmsg IPC 机制将打印内容发送到主核，由主核上的 cu 等终端工具负责显示。
风险：如果主核上的终端工具没有监听对应的非主核设备（例如，未执行 cu -l /dev/ttyRBT），IPC 消息会积压在缓冲区中，导致以下严重后果：
- IPC 缓冲区耗尽：由于消息无法被消费，IPC 缓冲区将迅速耗尽，导致新的 IPC 请求失败。
- 系统服务阻塞：依赖 IPC 的其他关键系统服务（如心跳、数据同步）将因无法获取缓冲区而阻塞，最终可能导致系统挂起或崩溃。
- 日志混乱与截断：与 syslog 混合使用时，printf 的同步阻塞特性会干扰 syslog 的异步日志流，导致日志条目被截断、内容交叉或完全丢失，使其不可读。

2、线程阻塞

printf 的底层实现涉及文件 I/O 操作，这是一个阻塞式调用。调用 printf 的线程将被挂起，直到数据完全写入输出缓冲区。对于有实时性要求的任务，这种不确定的阻塞时间是不可接受的。

3、中断上下文（ISR）中禁用

printf 不是可重入函数且可能引起阻塞，在中断服务程序（ISR）中调用会破坏系统实时性，甚至导致系统崩溃。

4、数据易失性

printf 的输出直接流向标准输出设备（如串口终端），并不会被持久化存储为日志文件。系统重启或会话关闭后，所有打印信息都会丢失。

四、最佳实践与替代方案

1、使用 `syslog` 进行日志记录

对于内核和服务，必须使用 syslog API 进行日志记录。syslog 具备以下优势：

异步非阻塞：调用 syslog 不会阻塞当前线程。
统一管理：支持日志等级（如 DEBUG, INFO, ERROR），易于过滤和管理。
持久化：可配置将日志保存到文件或发送到远程服务器。

注意：在 Linux 内核环境中，printk 函数的功能和定位类似于 syslog，用于向内核环形缓冲区输出日志，而非直接对应用户态的 printf。

2、确保跨平台兼容性

当您在适用场景（CLI 工具）中使用 printf 时，为确保代码在不同架构（如 32位/64位）平台间的可移植性，推荐使用 <inttypes.h> 头文件中定义的宏来格式化整型。

示例：

#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
int main() {
    uint64_t my_large_number = 12345678901234567890ULL;

    // 使用 PRIu64 宏确保正确打印 uint64_t 类型
    printf("My large number is: %" PRIu64 "\n", my_large_number);
    return 0;
}

五、函数原型

#include <stdio.h>

int printf(const char *format, ...);