C / C++ / 系统课时
读懂手册与系统接口文档
读懂手册与系统接口文档
面对陌生 Linux 接口时,最可靠的做法不是凭记忆猜参数,而是从 man 分册找到正确条目,再核对头文件、函数原型、返回值和 errno 约定,把“能调用”变成“按契约调用”。
学习目标
- 能根据
man分册区分命令、系统调用和 C 库函数的同名条目。 - 能从手册的 SYNOPSIS、RETURN VALUE 与 ERRORS 确认接口契约。
- 能在函数失败后正确读取并保存
errno,避免把旧错误码当成当前结果。
先用分册锁定正确条目
Linux 手册最常用的分册中,1 表示用户命令,2 表示系统调用,3 表示 C 库函数。比如 printf 既可能指命令,也可能指 C 库函数;查程序接口时应明确写成 man 3 printf,查 open 系统调用则使用 man 2 open。
先确认本机手册条目实际安装在哪里:
man -w 2 open
man -w 3 printf
man -w 3 errno预期输出
<PATH>/man2/open.2.gz
<PATH>/man3/printf.3.gz
<PATH>/man3/errno.3.gz<PATH>、压缩格式和本地化目录可能因发行版而不同;关键是三条命令都能定位到对应分册。如果提示没有手册条目,需要先安装发行版提供的 Linux man-pages 与 C 库开发文档包。
从原型读出调用前提
打开 man 2 open 后,优先看 SYNOPSIS。它会告诉你应包含 <fcntl.h>,以及 open 的函数原型;这一步能避免“函数能猜出来,但头文件、参数类型或可变参数条件写错”的问题。
接着按固定顺序阅读接口契约:
- 在 SYNOPSIS 确认头文件和函数原型。
- 在 DESCRIPTION 确认每个参数、标志位以及前置条件。
- 在 RETURN VALUE 确认成功值和失败哨兵值。
- 在 ERRORS 查看失败后可能出现的错误码,再决定程序如何恢复或退出。
对 open 而言,成功时返回新的文件描述符,失败时返回 -1 并设置 errno。因此程序必须先检查返回值,不能只看 errno 是否非零。
用 errno 验证失败契约
下面的完整程序故意打开一个不存在的路径。失败后立即把 errno 保存到局部变量,再进行格式化输出;这样即使后续库函数改变 errno,也不会丢失原始错误原因。
cat > errno_demo.c <<'EOF'
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
int main(void) {
int fd = open("/definitely-not-existing/anystack-demo", O_RDONLY);
if (fd == -1) {
// 先保存 errno,避免后续库调用覆盖本次失败原因。
int err = errno;
printf("open failed: errno=%d\n", err);
printf("reason=%s\n", strerror(err));
return 0;
}
close(fd);
return 0;
}
EOF
gcc -Wall -Wextra -O2 errno_demo.c -o errno_demo
LC_ALL=C ./errno_demo预期输出
open failed: errno=2
reason=No such file or directory这里设置 LC_ALL=C 是为了让错误文本稳定为英文;在其他语言环境中,strerror 的文字可能不同,但 ENOENT 在 Linux 上仍对应错误码 2。
避免误读 errno
errno 只有在接口文档明确说明“调用失败并设置 errno”,且你已经通过返回值确认失败时才有意义。成功调用之后,即使 errno 仍保留旧值,也不能据此判断本次操作失败。
还要注意,有些接口的合法成功返回值可能与常见“失败值”重叠,必须严格按该函数的 RETURN VALUE 说明判断。遇到陌生接口时,把“分册、头文件、原型、成功返回、失败返回、ERRORS”这六项查全,基本就能建立一份可靠的调用契约。