开源 C 语言库之错误码管理

本文将介绍一种可以拥有更多含义的 int 型错误码。

错误码演进

首先，我们先来说一说错误码的演进，顺便看一看本文中要讲述的错误码演进到了何种程度。

阶段 1. 区分一个函数的执行是成功还是失败。

在这一阶段，人们使用 0 和非 0 值来表示函数的执行是成功或者失败。

但这时我们也会直观的想到，是否能在失败时给出失败原因。因此就衍生出了下一个阶段。

阶段 2. 获知一个函数的执行是成功还是失败，失败的话，要给出失败原因。

这一阶段，人们一般的做法是，函数返回 0 表示成功，失败则返回一个负数，而不同负数的绝对值用于指代错误类型。例如，-1 表示内存不足，-2 表示参数错误，-3 表示无权限等等。

但这一阶段的问题也很明显，就是：同一个错误码可能会在同一个函数中出现多次，我们如何得知当前的返回值是哪一个错误点抛出的？

阶段 3. 获知一个函数的执行是成功还是失败，失败的话，要给出失败原因和报错点位置。

在这一阶段，常规的处理方式基本上都是在出错点打印一段 log 信息，并返回一个负值给调用方。

然而这样做的弊端就是，返回值本身的定位能力并为加强，而是依赖于 log 组件来提供了位置信息，这样的方式增加了返回值与 log 的耦合度。

阶段 4. 获知一个函数的执行是成功还是失败，失败的话，在不依赖 log 的情况下，要给出失败原因和报错点位置。

这一阶段就是我们这篇文章主要介绍的内容了，请往下看。

先看一段示例代码

#include "mln_error.h"

#define OK    0 //0 是个特殊值，表示一切正常，由 0 生成的返回值就是 0 ，不会增加额外信息
#define NMEM  1 //由使用者自行定义，但顺序必须与 errs 数组给出的错误信息顺序一致

int main(void)
{
    char msg[1024];
    mln_string_t files[] = {
        mln_string("a.c"),
    };
    mln_string_t errs[] = {
        mln_string("Success"),
        mln_string("No memory"),
    };
    mln_error_init(files, errs, sizeof(files)/sizeof(mln_string_t), sizeof(errs)/sizeof(mln_string_t));
    printf("%x %d [%s]\n", RET(OK), CODE(RET(OK)), mln_error_string(RET(OK), msg, sizeof(msg)));
    printf("%x %d [%s]\n", RET(NMEM), CODE(RET(NMEM)), mln_error_string(RET(NMEM), msg, sizeof(msg)));
    printf("%x %d [%s]\n", RET(2), CODE(RET(2)), mln_error_string(RET(2), msg, sizeof(msg)));
    printf("%x %d [%s]\n", RET(0xff), CODE(RET(0xff)), mln_error_string(RET(0xff), msg, sizeof(msg)));
    return 0;
}

在这段代码中，笔者使用了Melon 库的错误码组件。我们先给出结论和效果，那就是利用 Melon 的错误码组件，我们可以在一个出错点处获取到一个整型数值。通过这个数值，我们可以知道如下信息：

是否出错
错误类型
出错文件
出错行号

这段代码的输出如下：

0 0 [Success]
ffffedff 1 [a.c:18:No memory]
ffffec01 255 [a.c:19:Unknown Code]
ffffeb01 255 [a.c:20:Unknown Code]

原理分析

原理其实很简单。首先在 Melon 中，通过调用 mln_error_init 函数来初始化工程全局的错误码管理变量。伴随着该函数调用的还有两个数组：

本工程包含的（或者说开发者关心的）源代码文件名。本例中是：files
错误码对应的错误信息字符串数组。本例中是：errs

而错误号则是错误信息字符串数组的下标，且第一个元素（下标为 0 ）的错误信息含义应为成功或无异常。

然后，在错误点处，将错误码传递给 RET 宏来生成返回值。如果错误码大于 0 ，则会生成一个负数。这个负数的各部分含义如下（从左到右，比特位从高到低）：

[1-bit 符号位｜ 9-bit 文件名下标｜ 14-bit 当前行号｜ 8-bit 错误码]

如此拼凑出整个 32-bit 的 int 型数值。

此外，对于未曾在初始化时给出的源文件路径和错误码，皆可生成错误码，只是因为不存在映射关系，因此在函数 mln_error_string 调用时返回的详细错误字符串内容中，对应的部分仅给出 Unkown xxx 的字样。

使用限制

因为使用了位域，因此每一个定位条件都有数量限制：

支持 255 个错误码（ 0xff 为表留值）
支持每个文件 16383 行（ 0x3ffff 为保留值）
支持 511 个文件（ 0x1ff 为保留值）
仅针对文件名，而非文件路径名，因此应尽量避免不同目录下出现同名代码文件

感谢阅读，对文中 Melon 库感兴趣的读者可以访问 Github repo。Melon 库中提供了多种多样和奇奇怪怪的组件，有些组件常用，但也包含了一些额外扩展功能。