C语言函数库手册PDF：man/groff导出与索引实践

简介C语言函数库手册以PDF形式整理面向正在学习或使用C语言做软件开发的学生、初学者与需随时查阅的工程师用于解决函数名、参数及返回值记忆模糊、标准库分类不清晰的问题。全包仅1个PDF文件约51KB体积轻便可离线存入手机或电脑随时检索。内容按头文件分类组织ctype.h部分逐条列出isalpha、isalnum、isdigit、isspace、tolower、toupper等字符分类与转换函数标明判断范围与返回值含义math.h及stdlib.h部分覆盖abs、fabs、exp、log、pow、sqrt、sin、cos、tan、atan2等数学运算以及atof、atoi、itoa、ecvt等数值与字符串转换函数并附ceil、floor、rand、srand等常用工具说明便于对照速查。已有115人学习下载适合课程作业、笔试复习与日常编码时作案头参考。1. 一份能被检索的 C 语言函数库手册 PDF 该解决什么接手一段十年前留下的 C 代码耗时间的往往不是业务逻辑而是确认strncpy在源串长度等于 n 时到底补不补\0、fread读到一半返回什么、snprintf的返回值能不能直接当写入长度用。手边只有零散网页时查一次要翻三层搜索结果把 C 语言函数库手册整理成本地 PDF按函数名建好书签查参数这个动作就退化成一次 CtrlF。它要装的不是语法讲解而是 man 页的 RETURN VALUE、头文件里的原型和一段能跑起来的边界测试。刚入门的人照着命令链能搭出一份自用版本写过几年 C 的人更该关心的是索引怎么维护、不同平台的条目差异记在哪。2. 用 man 与 groff 把 C 语言函数库手册导出成 PDF2.1 手册的源头man 第 3 节、头文件原型与 info 文档的分工Linux 上 C 库函数的行为描述基本都在 man 的第 3 节系统调用在第 2 节同名条目混在一起查最容易被带偏。man printf命中的可能是 shell 命令那一页而真正想看的库函数在第 3 节所以查的时候把节号写全是个习惯问题。头文件/usr/include/string.h只给函数原型和restrict之类的限定不给行为描述真正有信息量的是RETURN VALUE、NOTES、BUGS这三段。man -w strcpy # 打印手册页的真实路径返回空说明该条目不存在 man 3 printf | head -n 20 # 只看库函数 printf而不是同名的 shell 命令 man -k copy string # 按描述里的关键字反查函数名等价于 apropos man -s 3 -k memcpy # 把反查范围限定在第 3 节内man -w是最该先跑的一条它不渲染内容只告诉你有或者没有。返回空的时候不要硬凑例如strcpy_s这类并非所有实现都提供的函数、以及大量以宏形式存在的条目assert、errno本来就没有独立手册页得靠头文件或平台文档补。在一台机器上生成手册之前先把本机缺哪些条目列出来比生成完一千页再发现空洞要省事。节号内容与函数库手册的关系2系统调用read、write、fstat在这里不在第 3 节3库函数strcpy、snprintf、fopen的主战场7概览与约定字符集、格式化输出约定等背景5文件格式/etc/下的配置文件一般不收进手册2.2 从 man 到 PDFgroff 管线和几个必调参数生成 PDF 有两条路一条是让 man 自己调 PDF 后端一条是直接把 man 的源文件喂给 groff。前者省事后者可控尤其是要统一纸张尺寸和行宽的时候。groff 不认识.gz后缀所以走源文件这条路要先用zcat解压这个细节卡过不少人报错信息通常只是「无法打开文件」。# 路线一man 自带 PDF 后端man-db 与 groff 齐备时可用 man -Tpdf strcpy strcpy.pdf # 路线二直接走 groff 管线输出参数可控 zcat /usr/share/man/man3/strcpy.3.gz \ | groff -man -Tpdf -rLL170n -rLT240n strcpy.pdf # 老环境只有 PostScript 输出时的退路 man -t strcpy | ps2pdf - strcpy.pdf参数逐个说-man指定按 man 宏包解析漏掉它整页排版会散-Tpdf是输出设备换成-Tps得到 PostScript-rLL170n设行宽单位n表示当前字号下的字符宽度A4 横向排版时常用-rLT240n设页长调小了会自动分页但不会切断代码示例。三条命令的输出质量差别不大真正的差别在批量场景路线一每调一次进程都要重新加载字体上万页时会明显变慢。代码后面这段是排错用的生成的 PDF 出现乱码先确认字体是否包含对应字符集再检查groff版本是否带 PDF 驱动出现整页空白但文件大小不为零多半是 man 页里的宏没被识别回到-man这一项检查。2.3 批量导出与合并用函数清单驱动脚本单个函数导出没有难度麻烦的是几百个函数一起导。思路很朴素把函数名写进一个清单文件一行一个脚本读一行导一页最后合并。清单本身可以从项目源码里抓也可以照着常用函数手写一份收录范围建议聚焦在字符串、内存、文件、格式化这四类上。#!/usr/bin/env bash set -euo pipefail # 任一命令失败即退出避免生成半截文件 outmanpdf mkdir -p $out while read -r fn; do [[ -z $fn || $fn \#* ]] continue # 跳过空行与注释行 if ! man -w $fn /dev/null 21; then printf miss\t%s\n $fn $out/missing.log continue # 没有手册页就记账不生成空 PDF fi man -Tpdf $fn $out/$fn.pdf 2/dev/null \ || man -t $fn | ps2pdf - $out/$fn.pdf # 后端不可用时自动降级 done funcs.txt LC_ALLC ls $out/*.pdf | sort | xargs pdfunite /dev/stdin c-manual.pdf脚本里几个点值得留意。read -r保留反斜杠函数名里一般不会出现但注释里可能有加上不亏。man -w做预检避免生成一堆零字节的 PDF 混进合并列表。missing.log是这份手册真正有价值的部分它标出了本机文档没覆盖的函数通常是无扩展的标准函数、厂商私有函数或者干脆是别的库里的东西。合并那行前面加LC_ALLC是防止不同 locale 下 glob 展开顺序不一致导致目录页码每一次生成都对不上。pdfunite来自 poppler 工具集机器上没有的话换成pdftk的cat子命令或者mutool merge顺序参数都是按命令行给的顺序拼接。3. 字符串与内存函数手册条目里的参数边界怎么落到代码3.1 把手册的形参列表翻译成一张边界表手写代码出 bug很多不是不会用而是把几个长得像的函数当成同一个。strncpy常年被当成安全的 strcpy用但它和snprintf在截断时的行为完全不同一个不保证补终止符一个保证。把手册里的原型、返回值语义和常见误用并列成表比一页页翻 PDF 快得多。函数关键形参截断时是否补\0返回值含义典型误用strcpychar *dst, const char *src不适用dst目标缓冲区容量未校验strncpy增加size_t n否src 长于 n 时无终止符dst当成安全版本直接替换strcpysnprintf增加size_t n是n 0 时想要写入的长度可能大于 n忽略返回值以为写入被截断memcpyvoid *dst, const void *src, size_t n不适用dst源目标内存重叠memmove同上不适用dst无重叠需求时白担一次拷贝开销这张表里最容易踩的还是snprintf的返回值它返回的是如果缓冲区足够大本应写入的长度不是实际写入的字节数。手册的 RETURN VALUE 段写得很清楚但只在被截断时才体现出来平时返回值和实际长度相等容易形成错误直觉。3.2 用 ASan 跑一遍截断与零填充的复现代码把手册里的结论写成断言是验证自己理解是否正确的最短路径。下面这段代码把strncpy不补零、snprintf返回值超额两件事固化成可执行的检查配合 AddressSanitizer 一起跑越界访问会立刻暴露。/* boundary_check.c — 验证手册中 strncpy 与 snprintf 的边界描述 */ #include assert.h #include stdio.h #include string.h int main(void) { char a[8]; memset(a, X, sizeof a); /* 先填哨兵值便于观察哪些字节被改写 */ strncpy(a, 0123456789, 4); /* 源串长度远大于 n */ assert(a[3] 3); assert(a[4] X); /* 第 5 字节未被清零说明没有补终止符 */ char b[8]; int need snprintf(b, sizeof b, %s, 0123456789); assert(need 10); /* 返回值是“想要写的长度”不是实际写入长度 */ assert(b[7] \0); /* n 0 时保证终止 */ assert(strlen(b) 7); return 0; }编译与运行gcc -Wall -Wextra -O1 -g -fsanitizeaddress,undefined \ boundary_check.c -o boundary_check ./boundary_check echo OK-Wall -Wextra打开常见告警-O1在保留可读栈帧的同时做基本优化-g让报错带行号。-fsanitizeaddress,undefined是两件事ASan 抓缓冲区越界、释放后使用、内存泄漏UBSan 抓有符号溢出、空指针解引用这类未定义行为。断言失败时的输出只有行号回头翻本机手册页的 NOTES 段会发现断言写的就是原文结论。这一套跑通之后strcpy用法这类问题基本不用再去社区问答里搜了自己机器上的手册页加上这段代码就是最权威的答案来源。3.3 用函数指针表把手册条目变成可查询对象C 语言函数指针在这里有个很实用的用法把签名相同的同族函数放进一张表名字、实现、备注三列编译期就绑定好。这样写速查工具、写回归测试、写性能对比都只需要维护一张表不会出现文档改了代码没改的情况。选签名一致的一组函数很关键签名不一致硬塞进同一个函数指针类型会产生不兼容指针告警那种告警不该被忽略。/* cmp_table.c — 用函数指针表统一描述比较类函数便于批量测试 */ #include stdio.h #include string.h #include strings.h /* strcasecmp 的原型在这里POSIX 扩展 */ typedef int (*cmp_fn)(const char *, const char *); /* 统一签名 */ struct entry { const char *name; cmp_fn fn; const char *note; }; int main(void) { static const struct entry tab[] { {strcmp, strcmp, 按 unsigned char 逐字节比较}, {strcoll, strcoll, 结果受 LC_COLLATE 影响}, {strcasecmp, strcasecmp, 忽略大小写POSIX 扩展}, }; const char *l apple, *r Apple; for (size_t i 0; i sizeof tab / sizeof tab[0]; i) printf(%-11s - %d %s\n, tab[i].name, tab[i].fn(l, r), tab[i].note); return 0; }cmp_fn把三个函数的签名统一成int (*)(const char *, const char *)strcmp与strcoll完全匹配strcasecmp需要额外包含strings.h漏了会退化成隐式声明。表里加note字段等于把手册页里一句话的差别是否受 locale 影响、是否忽略大小写搬到了代码里测试输出一眼能看出不同。扩展这张表的做法也很直接凡是签名相同的函数都能挂进来比如把strlen这类换成size_t (*)(const char *)再建一张表。指针函数和函数指针这两个说法经常被混着用落到代码上就是返回指针的函数和指向函数的指针的区别这张表用的是后者。4. 文件读写函数fopen、fread、fwrite 的手册条目怎么用4.1 fopen 模式字符串逐个对照文件读写出问题一半以上栽在模式串上。w和a的区别看起来简单但a的读写位置语义、w的隐式截断都是只有翻手册才能确认的细节。下面这张表把第 3 节fopen页里的模式说明整理成可以直接对照的形式。模式串打开后的能力文件不存在时初始写位置备注r只读失败errno为ENOENT—最常用失败必须判空w只写创建文件开头已有内容立即截断为 0a追加创建文件末尾每次写都落在末尾r读写失败文件开头不截断可覆盖已有内容w读写创建文件开头同样先截断a读写创建文件末尾读位置可移动写仍追加b无额外语义类 Unix——在部分平台上区分文本与二进制x独占创建C11 起——与w组合成wx已存在则失败wx这一条值得单独记它把先判断文件是否存在再创建这个必然有竞态的写法变成了一个原子操作适合写锁文件、写输出结果的场景。b在类 Unix 平台上不产生任何效果但写跨平台代码时统一加上没有坏处省得换个平台再回来改。判断fopen失败不能只看返回指针errno才是拿到具体原因的地方用perror或strerror(errno)输出比打印一句打开失败有用得多。4.2 fread 与 fwrite 的返回值语义以及必须写的短读循环fread返回的是完整读到的项数当size参数为 1 时等于字节数这一点让很多人误以为它总是读满。管道、终端、网络文件系统上的文件都可能短读返回正值但小于请求量是合法行为返回 0 才需要区分是到了文件尾还是出了错判断依据是feof和ferror。写方向的fwrite同样可能只写一部分只是磁盘文件上很少见一旦遇到就丢数据。/* copy_file.c — 带完整错误检查的文件复制 */ #include errno.h #include stdio.h #include string.h int copy_file(const char *src, const char *dst) { FILE *in fopen(src, rb); if (!in) { perror(fopen src); return -1; } FILE *out fopen(dst, wb); if (!out) { perror(fopen dst); fclose(in); return -1; } unsigned char buf[64 * 1024]; size_t n; while ((n fread(buf, 1, sizeof buf, in)) 0) { size_t off 0; while (off n) { /* fwrite 也可能短写循环写满 */ size_t w fwrite(buf off, 1, n - off, out); if (w 0) { perror(fwrite); goto fail; } off w; } } if (ferror(in)) { perror(fread); goto fail; } /* 返回 0 时靠 ferror 区分 */ if (fclose(out) ! 0) { perror(fclose out); out NULL; fclose(in); return -1; } fclose(in); return 0; fail: fclose(out); fclose(in); return -1; }编译时建议开上大文件支持gcc -Wall -Wextra -O2 -D_FILE_OFFSET_BITS64 copy_file.c -o copy_file缓冲区取 64 KB 是个经验值太小系统调用次数多太大对页缓存不友好实际瓶颈一般在存储而不是这行代码。fclose的返回值必须检查因为缓冲区的数据是在关文件时才真正刷盘的写满磁盘的错误会延迟到这里才报出来不检查就等于静默丢数据。goto fail这个写法在这里是可读性最好的收尾方式比把fclose复制三遍更容易改对。4.3 fseek 与 ftell 求文件长度的坑想拿文件长度最直觉的写法是fseek(fp, 0, SEEK_END)再ftell这在 32 位平台上遇到超过 2 GB 的文件会直接溢出因为ftell返回long。手册里ftell页的 ERRORS 段会提到EOVERFLOW但只有真的处理过大文件的人才会去翻这一段。/* file_size.c — 两种取长度的方式注意 off_t 与复位 */ #define _FILE_OFFSET_BITS 64 #include stdio.h #include sys/stat.h long long size_by_stat(FILE *fp) { struct stat st; if (fstat(fileno(fp), st) ! 0) return -1; if (!S_ISREG(st.st_mode)) return -1; /* 管道、设备节点的 st_size 无意义 */ return (long long)st.st_size; } long long size_by_seek(FILE *fp) { if (fseeko(fp, 0, SEEK_END) ! 0) return -1; off_t end ftello(fp); rewind(fp); /* 必须复位否则后续读位置错乱 */ return (long long)end; }fseeko/ftello用off_t而不是long配合_FILE_OFFSET_BITS64在大文件上才是对的。rewind那一步经常被忘掉表现是后续读取立刻返回 0看起来像文件是空的实际是读写位置还在末尾。fstat走的是 inode速度快但对管道返回的st_size通常是 0所以要先S_ISREG判一下类型。两种方式各有适用面已经打开了文件用fstat(fileno(fp))只想知道大小就用stat按路径查。5. 给这份 C 语言函数库手册 PDF 加一层可执行索引手册生成出来只是开始真正省时间的是索引。手工翻目录决定哪几页该建书签效率很低直接用项目源码的调用频次来排序更靠谱。# 统计源码里的函数调用频次作为书签候选的排序依据 rg -o --no-filename --type c \b[a-z_][a-z0-9_]*\s*\( src/ \ | tr -d ( | sort | uniq -c | sort -rn | head -n 40 hot_funcs.txt # 生成“函数名 - 调用次数 - PDF 页码”的索引骨架页码手工补 while read -r cnt fn; do printf %-22s %6s p.\n $fn $cnt done hot_funcs.txt index.tsvrg -o只输出匹配到的片段而不是整行--type c限定文件类型省得把构建产物里的调用也算进去tr -d (去掉左括号和空格uniq -c计数后按频次倒排。前 40 个基本就覆盖了一个项目八成以上的调用。有了这张表PDF 书签只给高频函数建低频函数留给 CtrlF。函数名出现次数手册节建书签的理由memcpy高3参数顺序写反是最常见的手滑snprintf高3返回值语义需要反复确认malloc/free高3内存管理配对的检查点fopen中3模式串与errno对照strcpy中3只该出现在已确认容量的位置索引表里留一列写命中后要看的段落名比如snprintf对应RETURN VALUE、fopen对应ERRORS翻到那一页不用重新找位置。改代码前先用rg定位调用点再对着索引表里那一页书签确认语义比凭记忆写参数省事得多。本文还有配套的精品资源点击获取