通过

AddressSanitizer 运行时

AddressSanitizer 运行时库拦截常见的内存分配函数和操作，以检查内存访问。 有几个不同的运行时库可支持编译器可能生成的各种类型的可执行文件。 只要在编译时传递 /fsanitize=address 选项，编译器和链接器就会自动链接相应的运行时库。 可以在链接时使用 /NODEFAULTLIB 选项重写默认行为。 有关详细信息，请参阅 AddressSanitizer 语言、生成和调试参考中有关链接的部分。

使用 cl /fsanitize=address 进行编译时，编译器会生成指令来管理和检查影子字节。 程序使用此检测来检查堆栈、堆或全局范围内的内存访问。 编译器还会生成描述堆栈和全局变量的元数据。 此元数据使运行时能够生成精确的错误诊断：源代码中的函数名称、行和列。 将编译器检查和运行时库相结合，可以在运行时遇到多种类型的内存安全 bug 时进行准确诊断。

从 Visual Studio 17.7 预览版 3 开始，用于链接到 AddressSanitizer 运行时的运行时库列表如下所示。 有关 /MT（静态链接运行时）和 /MD（在运行时动态链接 redist）选项的详细信息，请参阅 /MD、/MT、/LD（使用运行时库）。

注意

在下表中，{arch} 是 i386 或 x86_64。 这些库使用体系结构名称的 Clang 约定。 MSVC 约定通常是 x86 和 x64 ，而不是 i386 和 x86_64，但它们引用相同的体系结构。

CRT 选项 AddressSanitizer 运行时库 (.lib) 地址运行时二进制文件 (.dll)
/MT 或 /MTd %> clang_rt.asan_dynamic-{arch}
/MD 或 /MDd %> clang_rt.asan_dynamic-{arch}

下图显示 /MT、/MTd、/MD 和 /MDd 编译器选项下如何链接语言运行时库：

不同编译器选项下链接运行时库的示意图。

下图显示了不同编译器选项下如何链接 ASan 库：

链接 ASan 运行时 dll 的示意图。

与其他 C 运行时组件不同，即使是静态链接，ASan 运行时 DLL 也必须出现在运行时中。

以前的版本

在 Visual Studio 17.7 预览版 3 之前，静态链接（/MT 或 /MTd）的版本不使用 DLL 依赖项。 与之相反，AddressSanitizer 运行时是静态链接到用户的 EXE 中的。 然后，DLL 项目将从用户的 EXE 加载导出以访问 ASan 功能。

动态链接的项目（/MD 或 /MDd）根据其配置目的为调试或发布而使用不同的库和 DLL。 有关这些更改及其动机的详细信息，请参阅 MSVC 地址擦除系统 – 一个 DLL 适用于所有运行时配置。

下表描述了 Visual Studio 17.7 预览版 3 之前 AddressSanitizer 运行时库链接的先前行为：

CRT 选项 DLL 或 EXE 调试？ ASan 库 (.lib) ASan 运行时二进制 (.dll)
/MT EXE 否 %> 无
/MT DLL 否 clang_rt.asan_dll_thunk-{arch} 无
/MD 或 否 %> clang_rt.asan_dynamic-{arch}
/MT EXE 是 %> 无
/MT DLL 是 clang_rt.asan_dbg_dll_thunk-{arch} 无
/MD 或 是 %> clang_rt.asan_dbg_dynamic-{arch}

下图显示了 Visual Studio 2022 17.7 预览版 3 之前，不同编译器选项下如何链接 ASan 库：

Visual Studio 2022 预览版 3 之前链接 ASan 运行时 dll 的示意图。

函数拦截

AddressSanitizer 通过多种热修补技术实现函数拦截。 源代码本身对这些技术进行了最好的记录。

运行时库拦截许多常见的内存管理和内存操作函数。 有关列表，请参阅 AddressSanitizer 拦截函数列表。 分配拦截器管理与每个分配调用相关的元数据和影子字节。 每次调用 CRT 函数（例如 malloc 或 delete）时，拦截器都会在 AddressSanitizer 影子内存区域中设置特定值，以指示这些堆位置当前是否可访问以及分配的边界是什么。 这些影子字节允许编译器生成对影子字节的检查，以确定负载或存储是否有效。

无法保证拦截成功。 如果函数序言太短而无法写入 jmp，则拦截可能会失败。 如果拦截失败，程序将引发 debugbreak 并停止。 如果附加一个调试器，则可以清楚了解拦截问题的原因。 如果遇到此问题，请报告 bug。

注意

用户可以选择尝试在拦截失败后继续执行，方法是将环境变量 ASAN_WIN_CONTINUE_ON_INTERCEPTION_FAILURE 设置为任意值。 在拦截失败后继续执行可能会导致丢失该函数的 bug 报告。

自定义分配器和 AddressSanitizer 运行时

AddressSanitizer 运行时为常见的分配器接口 malloc/free、new/delete、HeapAlloc/HeapFree（通过 RtlAllocateHeap/RtlFreeHeap）提供拦截器。 许多程序会出于某种原因使用自定义分配器，例如使用 dlmalloc 的任何程序或使用 std::allocator 接口和 VirtualAlloc() 的解决方案。 编译器无法自动将影子内存管理调用添加到自定义分配器。 用户有责任使用提供的手动中毒接口。 此 API 使这些分配器能够与现有的 AddressSanitizer 运行时和影子字节约定一起正常运行。

手动 AddressSanitizer 中毒接口

启蒙的接口很简单，但它对用户施加了对齐限制。 用户可以通过导入 sanitizer/asan_interface.h 来导入这些原型。 以下是接口函数原型：

void __asan_poison_memory_region(void const volatile *addr, size_t size);
void __asan_unpoison_memory_region(void const volatile *addr, size_t size);

为方便起见，AddressSanitizer 接口头文件提供了包装器宏。 这些宏检查在编译期间是否启用了 AddressSanitizer 功能。 它们允许源代码在不需要时省略中毒函数调用。 这些宏应该优先于直接调用上述函数：

#define ASAN_POISON_MEMORY_REGION(addr, size)
#define ASAN_UNPOISON_MEMORY_REGION(addr, size)

注意

如果手动有害内存，则必须在重复使用之前将其取消欺骗。 这对于堆栈地址尤其重要，例如对于在程序执行期间经常重复使用的局部变量。 如果不在删除堆栈帧之前取消威胁，则在手动中毒的堆栈地址中引入 use-after-poison 误报的风险。

AddressSanitizer 中毒的对齐要求

影子字节的任何手动中毒都必须考虑对齐要求。 如有必要，用户必须添加填充，以便影子字节在影子内存中的字节边界处结束。 AddressSanitizer 影子内存中的每个位对应用程序内存中单个字节的状态进行编码。 这种编码意味着每个分配（包括任何填充）的总大小必须与 8 字节边界对齐。 如果不满足对齐要求，可能会生成 bug 报告。 不正确的报告可能表现为缺少报告（漏报）或非错误报告（误报）。

有关对齐要求和潜在问题的说明，请参阅提供的 ASan 对齐示例。 一个是一个小程序，显示手动影子内存中毒可能会出错的情况。 第二个是使用 std::allocator 接口的手动中毒的示例实现。

运行时选项

MSVC AddressSanitizer 基于 llvm-project 存储库中的 Clang AddressSanitizer 运行时。 因此，MSVC 中也提供了大多数 clang 的 ASan 运行时选项。 此处提供了公共 Clang 运行时选项的完整列表。 以下各部分介绍了其中一些差异。 如果发现某选项无法按预期运行，请报告 bug。

配置运行时选项

ASan 运行时选项采用以下两种方式之一进行设置：

  • ASAN_OPTIONS 环境变量
  • __asan_default_options用户函数

如果环境变量和用户函数指定冲突选项，则 ASAN_OPTIONS 环境变量中的选项优先。

通过用冒号分隔多个选项来指定多个选项。:

以下示例将设置为 alloc_dealloc_mismatch 1 和 symbolize 0：

set ASAN_OPTIONS=alloc_dealloc_mismatch=1:symbolize=0

或者将以下函数添加到代码中：

extern "C" const char* __asan_default_options()
{
  return "alloc_dealloc_mismatch=1:symbolize=0";
}

不支持的 AddressSanitizer 选项

  • detect_container_overflow
  • unmap_shadow_on_exit

注意

AddressSanitizer 运行时选项 halt_on_error 无法按预期方式运行。 在 Clang 和 MSVC 运行时库中，许多错误类型被视为不可持续，包括大多数内存损坏错误。

有关详细信息，请参阅与 Clang 12.0 的差异部分。

特定于 MSVC 的 AddressSanitizer 运行时选项

  • windows_hook_legacy_allocators 布尔值，设置为 false 以禁用对 GlobalAlloc 和 LocalAlloc 分配器的拦截。

    注意

    撰写本文时，公共 llvm 项目运行时中没有 windows_hook_legacy_allocators 选项。 该选项最终可能会进入公共项目；但需要经过代码审查和社区接受。

    选项 windows_hook_rtl_allocators 以前是一个可选功能，因为 AddressSanitizer 是试验性的，但现在默认启用。 在 Visual Studio 2022 版本 17.4.6 之前的版本中，默认选项值为 false。 在 Visual Studio 2022 版本 17.4.6 及更高版本中，选项 windows_hook_rtl_allocators 默认为 true。

  • iat_overwrite 字符串，默认设置为 "error"。 其他可取的值为 "protect" 和 "ignore"。 某些模块可能会覆盖其他模块的 import address table 以自定义某些函数的实现。 例如，驱动程序通常为特定硬件提供自定义实现。 该 iat_overwrite 选项管理 AddressSanitizer 运行时对特定 memoryapi.h 函数的防覆盖保护。 运行时当前跟踪 VirtualAlloc、VirtualProtect 和 VirtualQuery 函数以进行保护。 Visual Studio 2022 版本 17.5 预览版 1 及更高版本提供该选项。 以下 iat_overwrite 值控制在覆盖受保护函数时运行时的反应方式：

    • 如果设置为 "error"（默认值），运行时将在检测到覆盖时报告错误。
    • 如果设置为 "protect"，运行时将尝试避免使用被覆盖的定义并继续操作。 实际上，该函数的原始 memoryapi 定义在运行时内部使用，以避免无限递归。 进程中的其他模块仍使用被覆盖的定义。
    • 如果设置为 "ignore"，运行时不会尝试更正任何被覆盖的函数，并继续执行。

  • windows_fast_fail_on_error 布尔值（默认情况下为 false），设置为 true，使进程在打印错误报告后以 __fastfail(71) 终止。

注意

当 abort_on_error 值设置为 true 时，在 Windows 上，程序以 exit(3) 终止。 为了不更改当前行为，我们决定改为引入这一新选项。 如果 abort_on_error 和 windows_fast_fail_on_error 均为 true，则程序将以 __fastfail 退出。

AddressSanitizer 拦截函数列表 (Windows)

AddressSanitizer 运行时热修补许多函数，以在运行时启用内存安全检查。 下面是 AddressSanitizer 运行时监视的函数的非详尽列表。

默认拦截器

可选拦截器

仅当启用了 AddressSanitizer 运行时选项时，才会安装此处列出的拦截器。 将 windows_hook_legacy_allocators 设置为 false 以禁用旧式分配器拦截。 set ASAN_OPTIONS=windows_hook_legacy_allocators=false

另请参阅

AddressSanitizer 概述
AddressSanitizer 已知问题
AddressSanitizer 生成和语言参考
AddressSanitizer 阴影字节
AddressSanitizer 云或分布式测试
AddressSanitizer 调试程序集成
AddressSanitizer 错误示例