C语言16进制整数转字符串：snprintf、定宽查表与缓冲区避坑

调试一个通信协议的时候，日志里蹦出一串0x1A2B3C，你想把它原样打出来对照手册，结果 printf 一写，前面一坨 f 冒出来。C语言 16进制整数转字符串这件事，看着是最基础不过的功课，可我在带人看代码的时候，十个人里有六七个在这上面栽过跟头——要么缓冲区少算了一个字节，要么负数打成八位 f，要么大小写和补零对不上。这篇就把这件事从头拆一遍：四种常见写法各自的开销和适用面、缓冲长度到底按什么公式算、从单个整数扩展到一整块内存怎么做、以及字符串再转回整数时那些不对等的细节。刚上手 C 的能照着抄一份能进项目的实现，写过几年的人大概也能在负数处理和定宽这两处捡到点东西。

1. 需求先摆清楚：这活到底在转什么

1.1 四个必须在动手前定下来的问题

很多人一上来就写循环，写完发现调用方要的是大写、要八位补零、要带0x前缀，然后回头改，改完又发现负数打印出十六个 f。这活儿的麻烦不在于转换本身，而在于需求没定死。我一般会先问四个问题：

• 定宽还是变长：0x1A2B3C这种变长输出看起来清爽，但在日志对齐、协议字段比对、十六进制编辑器里就没法定长比较。寄存器、CRC、哈希这类东西几乎一律要求定宽。
• 大小写：十六进制里 a-f 和 A-F 都合法，但同一个项目里必须统一，否则 grep 都搜不全。
• 前缀：要不要0x。这个前缀会占两个字符，缓冲区算错往往就错在这儿。
• 有符号输入的语义：一个int值-1，你要输出-1、输出ffffffff、还是输出FFFFFFFFFFFFFFFF？三个答案对应三套代码，选错了就是线上对账对不上的那种 bug。

把这四个问题答完，代码其实已经写出来一半了。剩下的只是性能和多字节场景。

1.2 这些调用场景决定了你该用哪套写法

同一个功能在不同位置的写法完全不一样。我把它归成三类：

第一类是调试和日志。这类调用频率低、可读性优先，snprintf就是最合适的选择，别为了省那点时间把代码写得难读。

第二类是协议帧和寄存器值的展示。特点是频率高、格式固定、要求定宽补零。比如某模拟项目里解析一个二进制配置块，每个字段都要转成定宽大写十六进制打到日志里做 diff，这种地方手写查表实现比sprintf稳得多，也不会有重复格式串解析的开销。

第三类是整块内存的 dump。抓到一个 256 字节的包体，要一次性转成十六进制字符串保存下来，这时候单个整数的转换函数就不够用了，需要面向unsigned char数组的版本，还得考虑要不要插分隔符、每行多少字节。

分清这三类之后，你就不会拿一个函数去套所有场景了。

1.3 一个容易被忽略的前置判断

写转换之前先确认一件事：你到底要转的是"数值"还是"内存里的字节"。这两件事的输出结果在小端机器上完全不同。uint32_t x = 0x11223344;直接按数值转，得到11223344；但如果把&x当字节数组 dump，小端机器上得到的是44332211。我在排查一个固件升级包的时候就被这个坑过一次——校验工具按字节序算，日志按数值打，两边对不上，折腾了小半天才反应过来是两个语义。后面第 4 节会把这块单独讲。

2. 底层逻辑：右移四位，掩码取低四位

2.1 十进制打印背后的"取余倒排"

printf("%d", n)在库函数里干的事，说白了就三步：反复对 10 取余拿到最低位，把余数映射成字符，最后把字符顺序倒过来。比如 255：255 % 10 = 5，25 % 10 = 5，2 % 10 = 2，倒排得"255"。这个"取余 + 倒排"是所有进制转换的母版。

十六进制的代码之所以看起来比十进制短，是因为它有个天然优势：进制 16 是 2 的幂。n % 16等价于n & 0x0F，n / 16等价于n >> 4。编译器对十进制那次除法也会优化成乘法加移位（这就是所谓的魔数乘法），但那是编译器替你兜的，遇到变量进制就兜不住了。十六进制直接用手写的位运算，没有除法指令、没有魔数表，编译器看到多少就是多少。

2.2 定宽输出的写法为什么更简单

一旦确定输出宽度是 8 位，整个逻辑就反过来了：不再"从低位取到高位再倒排"，而是从最高位开始，一位一位往后填。循环变量从 7 递减到 0，每轮取v & 0xF写进out[i]，然后v >>= 4。

这么写的好处很实在：不需要临时数组做倒排，不需要判断前导零，不需要算长度，也不会有分支预测失败。它的代价是必须知道宽度。宽度是 32 位的就固定 8 个字符，是 64 位就固定 16 个。对绝大多数工程场景来说，这个约束根本不是问题——寄存器和字段本来就是定宽的。

2.3 缓冲区长度：那个加一的终止符

长度公式我习惯这么写：

#include <limits.h> /* 容纳一个 unsigned int 的十六进制串所需的最小缓冲区（含终止符） */ #define UINT_HEX_BUF (sizeof(unsigned int) * (CHAR_BIT / 4) + 1) /* 64 位整数的 */ #define ULL_HEX_BUF (sizeof(unsigned long long) * (CHAR_BIT / 4) + 1)

CHAR_BIT / 4表示"一个字节能装多少个十六进制位"，标准要求CHAR_BIT >= 8，绝大多数环境是 8，算出来是 2。乘以sizeof就得到位数，再+1给终止符留位置。用sizeof(unsigned int)而不是写死的 32，可移植性好一点，虽然现实中int几乎不会不是 32 位。

如果要带0x前缀，那还得再+2。我见过太多char buf[8]存 8 位定宽十六进制然后buf[8] = '\0'的代码，栈上越界一个字节，平时不炸，换个编译器加个栈保护就崩了。

注意：char buf[8]写snprintf(buf, 8, "%08x", v)的时候，最后一位会被截掉，你拿到的是 7 个字符加终止符，看着像是对的，其实少了一位。

2.4 有符号数：负数为什么变成一串 f

这是新手最常问的一个问题。int v = -1; printf("%08x", v);输出ffffffff，为什么？

因为-1的补码表示就是全 1，而%x把对应参数当成无符号类型来解释。严格说，%x期望的是unsigned int类型的参数，你传一个int进去，格式串和实参类型不匹配，标准里这属于未定义行为。只不过在所有主流的实现上，int和unsigned int走的是同一套传参规则，位模式照搬，所以你能看到ffffffff。

稳妥的写法是显式转换：

int v = -1; printf("%08x\n", (unsigned)v); /* 明确定义：模 2^N 转换 */ printf("%08llx\n", (unsigned long long)v); /* 会先经过符号扩展再转换 */

注意第二行的结果依赖int和long long的宽度：-1先转成long long是符号扩展，得到-1LL，再转成无符号就是0xFFFFFFFFFFFFFFFF。如果你想要的是"把一个 32 位值按 32 位打出来"，那就得先(unsigned)v再往上转，否则位数会变。这个细节在协议解析里出错，往往表现为"前端收到 16 个 f 的 CRC 字段"。

3. 四套落地方案，从能跑起来到跑得快

3.1 方案一：sprintf / snprintf，先让它跑起来

大多数人的第一版都是这个：

char buf[16]; sprintf(buf, "%x", 0x1A2B3Cu); /* "1a2b3c" */ sprintf(buf, "%X", 0x1A2B3Cu); /* "1A2B3C" */ sprintf(buf, "%08x", 0x1A2B3Cu); /* "001a2b3c" */ sprintf(buf, "0x%08X", 0x1A2B3Cu); /* "0x001A2B3C" */

格式串里几个修饰符的作用要记清：%x小写、%X大写、0表示用零填充、8是最小宽度（不是截断宽度，值超出时会打更多位）、#会加0x或0X前缀。

sprintf的问题是不带长度保护，缓冲区小了就直接溢出。工程代码里应该一律用snprintf：

char buf[16]; int n = snprintf(buf, sizeof buf, "%08X", 0x1A2B3Cu);

代价也有，而且不小。snprintf每次调用都要解析格式串、处理可变参数列表、走一遍 locale 相关的判断，这些开销跟你实际要干的"移位填字符"完全不成比例。在每秒几十万条的日志热路径上，这一块能占到相当可观的比例。我做过一个粗糙的对比，同样转 1000 万次 32 位值，定宽的%08x和手写查表的差距是数量级的，不是百分之几十，是十倍往上。所以规则很简单：调试和低频日志随便用，热路径和嵌入式环境别用。

3.2 方案二：取余循环，理解原理用

自己实现一遍变长版本，是搞清楚进制转换最快的方式：

#include <stddef.h> /* 变长、小写、不带前缀；调用方保证 out 至少能放 sizeof(v)*2+1 字节 */ void u32_to_hex_loop(unsigned int v, char *out) { static const char digits[] = "0123456789abcdef"; char tmp[sizeof(unsigned int) * 2]; size_t i = 0, j = 0; if (v == 0) { out[0] = '0'; out[1] = '\0'; return; } while (v != 0) { tmp[i++] = digits[v & 0x0Fu]; v >>= 4; } while (i > 0) { out[j++] = tmp[--i]; } out[j] = '\0'; }

几个点值得注意。tmp的大小按sizeof(unsigned int) * 2算，是最大可能位数，不多不少。v == 0必须单独处理，否则循环一次都不进，输出空串——这是这类实现最经典的漏判。字符映射用查表而不是if (d < 10) ...的三目运算，因为三目在某些编译器上可能生成分支，查表就是一次内存读，顺便也方便切换大小写。

这个版本适合放在工具库里当"通用变长转换"用，逻辑清楚、容易 review。但它有个隐患：tmp是栈上的局部数组，如果未来有人把宽度改成运行期变量，这块就得改成变长数组或者动态分配，那就麻烦了。所以我更倾向于把它当成教学版本，生产环境用下一套。

3.3 方案三：查表加位移，定宽场景的生产写法

定宽版本没有倒排、没有临时数组，代码短得几乎不像在干正事：

static const char HEX_LOWER[] = "0123456789abcdef"; static const char HEX_UPPER[] = "0123456789ABCDEF"; /* 无符号 32 位 -> 8 字符小写十六进制，带终止符；out 至少 9 字节 */ void u32_to_hex8(unsigned int v, char *out) { for (int i = 7; i >= 0; --i) { out[i] = HEX_LOWER[v & 0x0Fu]; v >>= 4; } out[8] = '\0'; } /* 无符号 64 位 -> 16 字符大写十六进制；out 至少 17 字节 */ void u64_to_hex16(unsigned long long v, char *out) { for (int i = 15; i >= 0; --i) { out[i] = HEX_UPPER[v & 0x0Fu]; v >>= 4; } out[16] = '\0'; }

这段代码的性质很好：循环次数编译期就知道（定宽），每次迭代的工作量固定，没有数据依赖的分支，写进去的下标单调递减，缓存友好。我通常会把i的类型写成int而不是size_t，因为倒序循环用无符号类型很容易写出for (size_t i = 15; i >= 0; --i)这种死循环——i永远不会小于 0，减到SIZE_MAX就飞了。这是 C 语言里的经典陷阱，编译器现在一般会给警告，但别指望它。

需要0x前缀的时候，把out往后挪两格、填上'0'和'x'，再调这个函数就行，或者写个包装函数。我偏好包装：

/* out 至少 11 字节 */ void u32_to_hex8_prefixed(unsigned int v, char *out) { out[0] = '0'; out[1] = 'x'; u32_to_hex8(v, out + 2); }

这种"基础函数只管数字、包装函数管装饰"的分层，在需要多种前缀/格式组合的时候特别省事，不会出现%#08x那种前缀占位把零填充搞乱的情况（#加0填充时，0x会排在补零前面还是后面，很容易搞混，实测下来还不如自己拼）。

3.4 方案四：非标准扩展函数，用之前先看清楚环境

很多人从旧代码里学到的是这类函数：

char buf[16]; itoa(0x1A2B, buf, 16); /* 不是标准库函数 */

问题是itoa从来就不在 C 标准里，它是某些实现附带的便利函数，换一个编译器可能就找不到符号。带下划线的_itoa、_itoa_s、_ui64toa这一族更是特定实现私有的接口，参数顺序、返回行为、是否带安全检查各不一样，跨平台项目里能不用就不用。

如果确实想用"转成任意进制"的通用函数，标准库里有strtol/strtoul的反向版本可以自己包一层，或者干脆用前面那套定宽实现。我在移植一段老代码时遇到过itoa找不到声明、编译器按隐式声明推断返回int、结果被当成指针用的荒唐情况——那个 bug 找了整整一个下午。结论：能用标准库就用标准库，不能用就自己写，别碰非标准扩展。

3.5 四套方案横向对比

这张表里我最想强调的不是速度，而是可移植性那一列。前面三种都是标准 C，随便哪个编译器都能编；第四种出了名的不靠谱，而它的速度优势在定宽查表面前根本不存在。

4. 从单个数到一整块内存

4.1 字节数组转十六进制串的通用写法

抓到一包数据要打日志，需要的是面向unsigned char数组的版本。核心思路和前面一样，只是每个字节拆成高低两个半字节：

#include <stddef.h> /* 返回写入的字符数（不含终止符），空间不足返回 -1 */ int bytes_to_hex(const unsigned char *buf, size_t len, char *out, size_t outsz, int upper) { static const char L[] = "0123456789abcdef"; static const char U[] = "0123456789ABCDEF"; const char *set = upper ? U : L; if (len > (SIZE_MAX - 1) / 2) return -1; /* 防溢出 */ if (outsz < len * 2 + 1) return -1; for (size_t i = 0; i < len; ++i) { out[i * 2] = set[(buf[i] >> 4) & 0x0F]; out[i * 2 + 1] = set[buf[i] & 0x0F]; } out[len * 2] = '\0'; return (int)(len * 2); }

len > (SIZE_MAX - 1) / 2这一行看着多余，实际上是防len * 2 + 1在size_t上回绕的。理论上只有长度为天文数字的缓冲区才会触发，但这种"先检查再相乘"的写法是肌肉记忆，写习惯了不会出错。返回值设计成"写入字符数"而不是"成功/失败"，调用方拼日志的时候可以直接把它接在后面累加。

4.2 字节序：转的是数值还是内存布局

这一节值得单独拎出来。前面提过，uint32_t x = 0x11223344;有两种完全不同的打印方式，结果不一样：

#include <stdio.h> #include <stdint.h> uint32_t x = 0x11223344u; /* 方式一：按数值打，与机器字节序无关 */ printf("%08x\n", x); /* 固定输出 11223344 */ /* 方式二：按内存字节顺序打，结果依赖机器 */ unsigned char *p = (unsigned char *)&x; for (size_t i = 0; i < sizeof x; ++i) printf("%02x", p[i]); /* 小端机器输出 44332211，大端输出 11223344 */

问题出在"你要给谁看"。给协议对端看，协议规定的是网络字节序（大端），那就要在网络字节序上做转换；给自己排查内存布局看，就该按实际字节顺序打。两种需求混在一起的代码最难维护。我习惯在函数名上做区分：u32_to_hex表示按数值，bytes_to_hex表示按内存。看名字就知道在干什么，比在注释里写一行"注意这里是字节序"可靠得多。

要用到网络字节序时，标准头文件里的htons/htonl那一族函数负责主机序和大端之间的转换。这里我只说一个原则：转换函数只做转换，字节序调整在调用前做完。把两件事缝在一个函数里，以后想按数值打的时候就没法复用了。

4.3 反向解析：字符串转回字节数组

有转过去的就得有转回来的，做日志回放或者配置文件解析时都要用。难点和正向不一样：正向只要输出，反向要处理非法字符、奇数长度、空白分隔符这三类输入。

static int hex_val(char c) { if (c >= '0' && c <= '9') return c - '0'; if (c >= 'a' && c <= 'f') return c - 'a' + 10; if (c >= 'A' && c <= 'F') return c - 'A' + 10; return -1; } /* 解析形如 "1a 2b 3c" 或 "1A2B3C" 的串；返回字节数，出错返回 -1 */ int hex_to_bytes(const char *s, unsigned char *out, size_t outsz) { size_t n = 0; while (*s) { while (*s == ' ' || *s == '\t' || *s == '\n' || *s == '\r') ++s; if (!*s) break; int hi = hex_val(s[0]); int lo = s[1] ? hex_val(s[1]) : -1; if (hi < 0 || lo < 0) return -1; /* 非法字符或奇数长度 */ if (n >= outsz) return -1; out[n++] = (unsigned char)((hi << 4) | lo); s += 2; } return (int)n; }

这里s[1] ? ... : -1那行是在处理奇数长度：比如输入"1a2"，走到最后只剩一个字符，s[1]是终止符，直接判错。这个判断不做的话，hex_val('\0')返回 -1，其实也会被后面拦住，但显式写出来意图更清楚。

还有一点：这段代码不跳过0x前缀。很多人从日志里复制出来的串是带0x的，直接喂进去会解析失败。要不要支持前缀取决于你的输入来源，我一般会在上面再加一层：如果开头两个字符是0x或0X就跳过去。但要小心，"0x"本身不是有效数据，跳完之后如果空了也得判错。

4.4 定宽零填充、插入分隔符与大小写切换

实际项目里还有两个常见需求：每几个字节插一个分隔符（比如 MAC 地址格式AA:BB:CC:DD:EE:FF），以及大小写可在运行期切换。这两个都是装饰性的东西，别塞进核心转换函数。

分隔符我一般这么处理：先算总长度len * 3 - 1（每字节两位加一个分隔符，最后一个不要），检查缓冲区，然后循环里每写完两个字符就补一个分隔符。核心的"半字节转字符"还是复用bytes_to_hex里那段查表逻辑，写成一个小函数或者static内联，比复制粘贴强。

大小写切换用一个查表指针就够了，不用写两套代码：

static inline void byte_to_hex(unsigned char b, char *out, const char *set) { out[0] = set[(b >> 4) & 0x0F]; out[1] = set[b & 0x0F]; }

set传"0123456789abcdef"还是"0123456789ABCDEF"由调用方决定。这个模式我用了很多年，比我见过的所有if (upper)分支写法都干净。

5. 踩坑实录与问题速查

5.1 缓冲区那一个字节，永远是最高频的错

我统计过自己经手的这类问题，十次里有六次是缓冲区差一个字节。典型写法：

char buf[8]; snprintf(buf, sizeof buf, "%08x", v); /* 只剩 7 个字节装 8 个字符 */

snprintf会把buf填满 7 个字符加终止符，最后一位十六进制被吃掉。因为日志输出看起来还是"一串十六进制"，很难第一眼发现少了一位，等到协议字段比对时才暴露。

注意：缓冲区大小的计算式统一用sizeof(unsigned int) * 2 + 1，别写数字。带0x前缀再+2。写完用sizeof buf传给snprintf，不要传一个手写的数字。

另一个变体是定宽查表函数里out[8] = '\0'越界，因为调用方只分配了 8 字节。解决办法是把长度约束写进函数名（u32_to_hex8明确是 8 字符），并在注释里写清"out至少 9 字节"。命名比注释管用。

5.2 snprintf 的返回值不是"实际写入长度"

这个点在写拼接逻辑的时候特别容易翻车。snprintf返回的是"假如缓冲区足够大，本应写入的字符数"，不含终止符；只有当返回值小于传入的缓冲区大小，才表示完整写入；返回负数才表示编码错误。

char buf[8]; int n = snprintf(buf, sizeof buf, "%08x", 0x12345678u); /* n == 8，但 sizeof buf 也是 8，说明有截断 */ if (n < 0 || (size_t)n >= sizeof buf) { /* 处理截断 */ }

正确判断条件是(size_t)n >= bufsz，不是n > bufsz。这个差一个等号的错误，我见过不止一次，而且它只在"刚好写满"的时候出事，测试覆盖不到就上线了。

5.3 类型不匹配和可变参数的静默失败

printf家族不做类型检查，%x配long long、%llx配int都会静默跑出奇怪结果。典型的：

unsigned long long v = 0x1122334455667788ULL; printf("%x\n", v); /* 大概率只打出低 32 位 */ printf("%llx\n", v); /* 正确 */

在 32 位 ABI 上，%llx对应的参数走的是对齐后的寄存器对或者栈上的两个槽，格式串写错会导致后续所有参数整体错位，输出会乱得毫无规律。现代编译器一般会给-Wformat警告，把警告全打开、并且当成错误处理，能拦掉绝大多数这类问题。

5.4 问题速查表

6. 选型习惯和几条实打实的经验

6.1 我的默认选择

如果不是特别说明，我在项目里默认这么放：

• 工具库：提供bytes_to_hex和hex_to_bytes一对，覆盖字节数组双向转换，定宽数值转换基于它包一层。
• 日志宏：封装一个LOG_HEX(buf, len)，内部用变长的bytes_to_hex，输出小写、无前缀、无分隔符。日志里统一格式，比每次手写格式串靠谱得多。
• 协议相关代码：一律用u32_to_hex8/u64_to_hex16这类定宽函数，大写、无前缀，因为协议手册里写的就是大写。
• 调试临时打印：snprintf随便用，反正不进主干。

这个分工定下来之后，团队里就不会出现同一种数据在不同模块打印出不同格式的情况。格式不统一带来的排查成本，比性能优化省下来的那点时间高得多。

6.2 性能这块的实际感受

定宽查表比snprintf快一个数量级以上，这一点在几百条每秒的场景下完全感知不到，但在百万级每秒的日志链路上，差距就变成了可测量的 CPU 占用。我的经验是：不要为了性能提前优化，但也不要把它写成本来就慢的样子。定宽查表版本只有五六行，比写格式串还短，没有理由不用。

反过来，变长版本需要倒排和临时数组，代码长、分支多，如果调用频率高，我会倾向于先确定宽度再转，实在确定不了就用"先算最大值再补零"的两步走。性能这块还有一个隐形收益：定宽版本没有栈上的临时数组，对栈空间紧张的嵌入式环境很友好，这在资源受限的项目里有时比速度更关键。

6.3 可移植性上多留一步

写这类基础函数，我一般会注意三件事：不依赖CHAR_BIT == 8（虽然现实如此，但用CHAR_BIT / 4算长度几乎零成本）、不依赖字节序、不用非标准扩展。另外把static const char常量放在.rodata段，比每次在栈上构造字符表省事，也比宏更安全。

最后分享一个小习惯：这类转换函数我写完之后，一定会用0、1、0xF、0x10、最大值、以及带符号的-1这几个边界值各跑一遍，把输出打印出来肉眼对照。看起来土，但v == 0漏判、负号扩展、终止符位置这三类问题，全靠这几个用例挡住。工具函数出错的影响面太大，多花五分钟验证，值。