|
|
# AddressSanitizer 使用指南
|
|
|
|
|
|
## 📋 概述
|
|
|
|
|
|
AddressSanitizer (ASan) 是一个快速的内存错误检测工具，可以检测：
|
|
|
- 堆缓冲区溢出/下溢
|
|
|
- 栈缓冲区溢出/下溢
|
|
|
- 全局缓冲区溢出/下溢
|
|
|
- 释放后使用（Use-after-free）
|
|
|
- 返回后使用（Use-after-return）
|
|
|
- 重复释放（Double-free）
|
|
|
- 内存泄漏
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🚀 快速开始
|
|
|
|
|
|
### Windows (MSVC)
|
|
|
|
|
|
```powershell
|
|
|
# 启用 AddressSanitizer
|
|
|
php bin/compiler.php your-app.php --sanitize=address
|
|
|
|
|
|
# 或简写
|
|
|
php bin/compiler.php your-app.php --sanitize=addr
|
|
|
```
|
|
|
|
|
|
**要求：**
|
|
|
- Visual Studio 2019 16.9+ 或 Visual Studio 2022
|
|
|
- MSVC 编译器版本 19.29+
|
|
|
|
|
|
### Linux/macOS (GCC/Clang)
|
|
|
|
|
|
```bash
|
|
|
# 单个 sanitizer
|
|
|
php bin/compiler.php your-app.php --sanitize=address
|
|
|
|
|
|
# 多个 sanitizer（用逗号分隔）
|
|
|
php bin/compiler.php your-app.php --sanitize=address,undefined
|
|
|
|
|
|
# 可用的 sanitizer 类型：
|
|
|
# - address: 地址错误检测
|
|
|
# - undefined: 未定义行为检测
|
|
|
# - thread: 线程竞争检测
|
|
|
# - memory: 未初始化内存读取检测
|
|
|
# - leak: 内存泄漏检测
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔍 示例输出
|
|
|
|
|
|
当检测到内存错误时，AddressSanitizer 会输出详细的错误信息：
|
|
|
|
|
|
```
|
|
|
=================================================================
|
|
|
==12345==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000000010
|
|
|
READ of size 4 at 0x602000000010 thread T0
|
|
|
#0 0x7ff6abc12345 in main D:\workspace\compiler\examples\test.php:10
|
|
|
#1 0x7ff6abc67890 in __scrt_common_main_seh
|
|
|
|
|
|
0x602000000010 is located 0 bytes to the right of 16-byte region [0x602000000000,0x602000000010)
|
|
|
allocated by thread T0 here:
|
|
|
#0 0x7ff6abc98765 in operator new[]
|
|
|
#1 0x7ff6abc12340 in main D:\workspace\compiler\examples\test.php:8
|
|
|
|
|
|
SUMMARY: AddressSanitizer: heap-buffer-overflow
|
|
|
=================================================================
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 💡 使用建议
|
|
|
|
|
|
### 1. 开发阶段启用
|
|
|
|
|
|
在开发和测试阶段启用 AddressSanitizer，可以帮助您尽早发现内存错误：
|
|
|
|
|
|
```powershell
|
|
|
# 编译带 AddressSanitizer 的版本
|
|
|
php bin/compiler.php debug-test.php --sanitize=address --no-console
|
|
|
|
|
|
# 运行测试
|
|
|
.\debug-test.exe
|
|
|
```
|
|
|
|
|
|
### 2. 不要与优化同时使用
|
|
|
|
|
|
AddressSanitizer 会降低程序性能（约 2x），建议：
|
|
|
- 开发时：`-O0 --sanitize=address`
|
|
|
- 发布时：`-O2`（不使用 sanitizer）
|
|
|
|
|
|
### 3. 结合调试信息使用
|
|
|
|
|
|
```powershell
|
|
|
# 同时启用调试信息和 AddressSanitizer
|
|
|
php bin/compiler.php app.php --debug-info --sanitize=address
|
|
|
```
|
|
|
|
|
|
这样可以在错误报告中看到源代码行号。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🛠️ 常见用例
|
|
|
|
|
|
### 检测数组越界
|
|
|
|
|
|
```php
|
|
|
<?php
|
|
|
|
|
|
function test_buffer_overflow()
|
|
|
{
|
|
|
$arr = [1, 2, 3, 4, 5];
|
|
|
|
|
|
// 这会触发 AddressSanitizer 错误
|
|
|
$value = $arr[10]; // 越界访问
|
|
|
|
|
|
return $value;
|
|
|
}
|
|
|
|
|
|
function main()
|
|
|
{
|
|
|
test_buffer_overflow();
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 检测释放后使用
|
|
|
|
|
|
```php
|
|
|
<?php
|
|
|
|
|
|
class TestClass
|
|
|
{
|
|
|
public function __destruct()
|
|
|
{
|
|
|
// 对象被销毁
|
|
|
}
|
|
|
}
|
|
|
|
|
|
function test_use_after_free()
|
|
|
{
|
|
|
$obj = new TestClass();
|
|
|
unset($obj); // 对象被销毁
|
|
|
|
|
|
// 如果继续访问 $obj，可能触发错误
|
|
|
// （PHP 的垃圾回收机制通常会防止这种情况）
|
|
|
}
|
|
|
|
|
|
function main()
|
|
|
{
|
|
|
test_use_after_free();
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 检测内存泄漏
|
|
|
|
|
|
```php
|
|
|
<?php
|
|
|
|
|
|
function test_memory_leak()
|
|
|
{
|
|
|
// 在 C++ 层分配的内存如果没有正确释放
|
|
|
// AddressSanitizer 会检测到
|
|
|
}
|
|
|
|
|
|
function main()
|
|
|
{
|
|
|
test_memory_leak();
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## ⚙️ 高级配置
|
|
|
|
|
|
### 环境变量
|
|
|
|
|
|
AddressSanitizer 支持通过环境变量进行配置：
|
|
|
|
|
|
#### Windows
|
|
|
|
|
|
```powershell
|
|
|
# 设置 ASan 选项
|
|
|
$env:ASAN_OPTIONS = "detect_leaks=1:print_stats=1"
|
|
|
|
|
|
# 运行程序
|
|
|
.\your-app.exe
|
|
|
```
|
|
|
|
|
|
#### Linux/macOS
|
|
|
|
|
|
```bash
|
|
|
# 设置 ASan 选项
|
|
|
export ASAN_OPTIONS="detect_leaks=1:print_stats=1"
|
|
|
|
|
|
# 运行程序
|
|
|
./your-app
|
|
|
```
|
|
|
|
|
|
### 常用选项
|
|
|
|
|
|
| 选项 | 说明 | 默认值 |
|
|
|
|------|------|--------|
|
|
|
| `detect_leaks` | 检测内存泄漏 | 1 |
|
|
|
| `print_stats` | 打印统计信息 | 0 |
|
|
|
| `abort_on_error` | 错误时中止程序 | 0 |
|
|
|
| `log_path` | 日志文件路径 | stderr |
|
|
|
| `halt_on_error` | 第一个错误后停止 | 1 |
|
|
|
|
|
|
**示例：**
|
|
|
|
|
|
```powershell
|
|
|
# Windows
|
|
|
$env:ASAN_OPTIONS = "detect_leaks=1:print_stats=1:log_path=asan.log"
|
|
|
.\your-app.exe
|
|
|
|
|
|
# Linux/macOS
|
|
|
export ASAN_OPTIONS="detect_leaks=1:print_stats=1:log_path=asan.log"
|
|
|
./your-app
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔧 平台特定说明
|
|
|
|
|
|
### Windows (MSVC)
|
|
|
|
|
|
**限制：**
|
|
|
- 仅支持 `address` sanitizer
|
|
|
- 需要 Visual Studio 2019 16.9+ 或更新版本
|
|
|
- 可能与某些第三方库不兼容
|
|
|
|
|
|
**注意事项：**
|
|
|
- AddressSanitizer 会增加可执行文件大小
|
|
|
- 运行时性能下降约 2x
|
|
|
- 内存使用增加约 2-3x
|
|
|
|
|
|
### Linux (GCC/Clang)
|
|
|
|
|
|
**支持的 sanitizer：**
|
|
|
- `address` - 地址错误
|
|
|
- `undefined` - 未定义行为
|
|
|
- `thread` - 线程竞争
|
|
|
- `memory` - 未初始化内存
|
|
|
- `leak` - 内存泄漏
|
|
|
|
|
|
**组合使用：**
|
|
|
|
|
|
```bash
|
|
|
# AddressSanitizer + UndefinedBehaviorSanitizer
|
|
|
php bin/compiler.php app.php --sanitize=address,undefined
|
|
|
|
|
|
# ThreadSanitizer（不能与其他 sanitizer 同时使用）
|
|
|
php bin/compiler.php app.php --sanitize=thread
|
|
|
```
|
|
|
|
|
|
### macOS (Clang)
|
|
|
|
|
|
与 Linux 类似，但需要注意：
|
|
|
- MemorySanitizer 在 macOS 上可能不可用
|
|
|
- 建议使用 Homebrew 安装最新版本的 Clang
|
|
|
|
|
|
```bash
|
|
|
brew install llvm
|
|
|
export CC=/usr/local/opt/llvm/bin/clang
|
|
|
export CXX=/usr/local/opt/llvm/bin/clang++
|
|
|
php bin/compiler.php app.php --sanitize=address
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🐛 故障排除
|
|
|
|
|
|
### Q: 编译时提示不支持 sanitizer？
|
|
|
|
|
|
A: 检查编译器版本：
|
|
|
|
|
|
```powershell
|
|
|
# Windows
|
|
|
cl
|
|
|
|
|
|
# Linux
|
|
|
gcc --version
|
|
|
clang --version
|
|
|
```
|
|
|
|
|
|
确保使用支持 sanitizer 的版本。
|
|
|
|
|
|
### Q: 运行时出现 "Sanitizer CHECK failed"？
|
|
|
|
|
|
A: 这可能是由于：
|
|
|
1. 库冲突 - 确保所有库都用相同的 sanitizer 编译
|
|
|
2. 不兼容的选项 - 尝试移除其他优化选项
|
|
|
3. 系统限制 - 检查是否有足够的内存
|
|
|
|
|
|
### Q: AddressSanitizer 报告误报？
|
|
|
|
|
|
A: 可能的原因：
|
|
|
1. 第三方库的问题 - 考虑抑制特定模块的检查
|
|
|
2. 已知的无害问题 - 使用 `__attribute__((no_sanitize))` 禁用特定函数
|
|
|
|
|
|
```cpp
|
|
|
// 在 C++ 代码中
|
|
|
__attribute__((no_sanitize("address")))
|
|
|
void safe_function() {
|
|
|
// 这个函数不会被 ASan 检查
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### Q: 性能太慢怎么办？
|
|
|
|
|
|
A:
|
|
|
1. 只在调试时使用 sanitizer
|
|
|
2. 发布版本禁用 sanitizer
|
|
|
3. 使用 `-O1` 而不是 `-O0`（仍保持较好的检测能力）
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📊 性能影响
|
|
|
|
|
|
| 配置 | 速度 | 内存 | 适用场景 |
|
|
|
|------|------|------|----------|
|
|
|
| 无 sanitizer, -O2 | 100% | 100% | 生产环境 |
|
|
|
| -fsanitize=address, -O0 | ~50% | ~200% | 开发调试 |
|
|
|
| -fsanitize=address, -O1 | ~60% | ~180% | 测试环境 |
|
|
|
| -fsanitize=undefined, -O0 | ~80% | ~120% | 轻量级检查 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎯 最佳实践
|
|
|
|
|
|
1. **持续集成中启用**
|
|
|
```yaml
|
|
|
# .github/workflows/test.yml
|
|
|
- name: Compile with ASan
|
|
|
run: php bin/compiler.php tests/*.php --sanitize=address
|
|
|
|
|
|
- name: Run tests
|
|
|
run: ./run-tests.sh
|
|
|
```
|
|
|
|
|
|
2. **定期扫描**
|
|
|
- 每周运行一次带 sanitizer 的完整测试套件
|
|
|
- 修复所有报告的问题
|
|
|
|
|
|
3. **结合其他工具**
|
|
|
- Valgrind（Linux）
|
|
|
- Dr. Memory（Windows）
|
|
|
- Static analyzers（静态分析器）
|
|
|
|
|
|
4. **文档化已知问题**
|
|
|
- 记录无法立即修复的 sanitizer 警告
|
|
|
- 说明为什么这些警告可以忽略
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📚 相关资源
|
|
|
|
|
|
- [AddressSanitizer 官方文档](https://github.com/google/sanitizers/wiki/AddressSanitizer)
|
|
|
- [MSVC AddressSanitizer](https://docs.microsoft.com/cpp/sanitizers/asan)
|
|
|
- [GCC Sanitizers](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
|
|
|
- [Clang Sanitizers](https://clang.llvm.org/docs/UsersManual.html#controlling-code-generation)
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔗 编译器命令参考
|
|
|
|
|
|
```powershell
|
|
|
# Windows - 基础用法
|
|
|
php bin/compiler.php app.php --sanitize=address
|
|
|
|
|
|
# Windows - 结合其他选项
|
|
|
php bin/compiler.php app.php --sanitize=address --debug-info --no-console
|
|
|
|
|
|
# Linux/macOS - 单个 sanitizer
|
|
|
php bin/compiler.php app.php --sanitize=address
|
|
|
|
|
|
# Linux/macOS - 多个 sanitizer
|
|
|
php bin/compiler.php app.php --sanitize=address,undefined
|
|
|
|
|
|
# Linux/macOS - 内存泄漏检测
|
|
|
php bin/compiler.php app.php --sanitize=leak
|
|
|
```
|
|
|
|
|
|
希望这个指南能帮助您有效使用 AddressSanitizer 来检测和修复内存错误！
|
|
|
|
