Go cgo 指针规则为什么不允许保存 Go 指针

Go cgo 不允许 C 代码随意保存 Go 指针，核心原因不是“C 语言不能接收 Go 指针”，而是 Go 的垃圾回收器必须持续知道 Go 内存中的指针关系。一个 Go 指针传给 C 时，只有被访问的内存在整个访问期间保持 pinned，并且其中不能再藏着未固定的 Go 指针，才符合规则。

最实用的判断方式是：C 只在本次调用里使用数据，就传递一段不含未固定 Go 指针的 pinned 内存；C 要跨调用保存值，就复制到 C 堆，或保存 runtime/cgo.Handle，不要把普通 Go 指针塞进 C 的全局变量或结构体。

官方资料：https://go.dev/src/cmd/cgo/doc.go

先区分 Go 指针、C 指针和可访问时间

cgo 文档中的“Go 指针”不是指 Go 语法里的某一种类型，而是指向 Go 分配内存的指针；“C 指针”是指向 C 分配内存的指针。即使两者在 Go 侧都表现为 unsafe.Pointer，来源仍然不同。换句话说，判断依据是内存如何分配，而不是变量声明成了什么类型。

还要把时间分成两种情况：

• C 函数正在执行：传入参数指向的 Go 内存会在调用期间隐式保持 pinned，但它可触达的 Go 内存也必须满足同样的要求。
• C 函数返回以后：C 不能继续保留普通 Go 指针的副本。只有使用 runtime.Pinner 明确固定，并且在 C 仍保存该地址时没有解除固定，才有例外。

所以“函数参数传过去没报错”不等于“把地址存到 C 结构体里以后还能用”。前者有调用边界，后者把生命周期扩大到了调用之外。

为什么调用期间也不能把任意 Go 内存交给 C

“调用期间可以传指针”还有一个容易忽略的前提：指针指向的内存不能包含 C 看不到、也没有被固定的 Go 指针。这里的“包含”不仅是直接字段，还包括通过切片 backing array、数组元素或结构体字段继续可达的内存。

例如，下面的结构体含有一个字符串。字符串内部带有指向 Go 字节数据的指针，因此把整个结构体地址交给 C，并不能因为外层只是一个结构体就自动安全：

package main

/*
#include 

// C 只在函数返回前读取传入的字节，不缓存这个地址。
static void consume_bytes(const void *p, size_t n) {
	const unsigned char *bytes = p;
	(void)bytes;
	(void)n;
}
*/
import "C"

import "unsafe"

type Packet struct {
	Payload []byte
	// 注意：切片描述符含有指针，不能把 Packet 整体当成无指针内存传给 C。
}

func sendBytes(data []byte) {
	if len(data) == 0 {
		return
	}
	// 这里只传 backing array 的字节区域，C 不得保存该地址。
	C.consume_bytes(unsafe.Pointer(&data[0]), C.size_t(len(data)))
}

上例只传递字节区域，且 C 函数不保存地址。若把 &Packet 传入 C，C 可能接触到切片描述符中的 Go 指针，就违反了“可达 Go 指针必须满足 pinned 条件”的限制。

C 需要长期保存数据时怎么改写

跨调用保存数据时，优先改变所有权，而不是想办法延长普通 Go 指针的寿命。最清晰的做法是让 C 拥有自己的内存，把 Go 字节复制进去；使用结束后由 C 的释放函数回收。

package main

/*
#include 
#include 

// C 复制数据后才保存副本，避免保存 Go 的地址。
static void *clone_bytes(const void *src, size_t n) {
	void *dst = malloc(n);
	if (dst == NULL) {
		return NULL;
	}
	memcpy(dst, src, n);
	return dst;
}
*/
import "C"

import (
	"fmt"
	"unsafe"
)

func cloneForC(data []byte) (unsafe.Pointer, error) {
	if len(data) == 0 {
		return nil, nil
	}
	// C 只在本次调用中读取 Go 数据，长期保存的是复制后的 C 内存。
	p := C.clone_bytes(unsafe.Pointer(&data[0]), C.size_t(len(data)))
	if p == nil {
		return nil, fmt.Errorf("C malloc failed")
	}
	return p, nil
}

func releaseC(p unsafe.Pointer) {
	if p != nil {
		// C 分配的内存必须用 C.free 释放，不能用 Go 的 delete 思路处理。
		C.free(p)
	}
}

如果 C 保存的不是字节，而是一个需要回调 Go 的业务对象，可以使用 runtime/cgo.Handle。Handle 是一个整数句柄，C 保存句柄值，回调到 Go 后再取回原始值；C 保存的不是 Go 对象地址。

package main

/*
#include 

// C 保存的是整数句柄，不保存 Go 指针。
static uintptr_t remember_handle(uintptr_t h) {
	return h;
}
*/
import "C"

import (
	"fmt"
	"runtime/cgo"
)

type Session struct {
	Name string
}

func passHandle(s Session) {
	// 创建句柄后，C 只接触这个整数值。
	h := cgo.NewHandle(s)
	defer h.Delete() // C 不再使用句柄后及时释放 Go 侧表项。

	stored := C.remember_handle(C.uintptr_t(h))
	value := cgo.Handle(stored).Value().(Session)
	fmt.Println(value.Name)
}

必须保留地址时怎样使用 runtime.Pinner

runtime.Pinner 不是“把任意 Go 值变成 C 可永久保存的指针”。它只能固定允许固定的 Go 内存，而且固定时间必须覆盖 C 保存指针的全部时间。内存被固定多次时，也必须对应解除固定多次。

package main

/*
#include 

static const void *saved;

// 这里只演示 C 保存地址的边界；真正使用时必须在 release_saved 前保持 pinned。
static void save_address(const void *p) { saved = p; }
static void release_saved(void) { saved = NULL; }
*/
import "C"

import (
	"runtime"
	"unsafe"
)

func keepAddressForC() {
	value := new(byte)
	var pinner runtime.Pinner
	pinner.Pin(value)
	defer pinner.Unpin() // Unpin 前必须确认 C 已经释放 saved。

	// 只有在 pinned 期间，C 才能把这个地址保存到全局状态。
	C.save_address(unsafe.Pointer(value))
	C.release_saved()
}

字符串、切片、channel 等值不能通过 runtime.Pinner 变成可长期保留的 Go 指针。它们的内部表示含有 Go 指针或长度等描述信息，正确方案通常是复制数据或用 Handle 保存值，而不是强行把地址留在 C 侧。

排查 cgo 指针错误的最小清单

遇到 cgo argument has Go pointer to unpinned Go pointer 或类似运行时错误时，可以按下面顺序检查：

1. 确认指针实际指向 Go 堆还是 C 堆，不要只看 unsafe.Pointer 类型。
2. 确认传入区域里没有切片、字符串、map、channel、interface 或 function 等会继续携带 Go 指针的值。
3. 确认 C 是否把指针写入了全局变量、缓存、异步任务或结构体字段；如果写入，调用返回后的生命周期就必须重新设计。
4. 如果使用 runtime.Pinner，确认 Pin 和 Unpin 与 C 的保存、释放严格成对。
5. 如果只是想让 C 关联一个 Go 对象，优先换成 runtime/cgo.Handle，不要把对象地址当作 ID。

# 开发环境保留默认动态检查，先观察违规发生在哪个 cgo 边界。
GODEBUG=cgocheck=1 go test ./...

# 需要更完整的指针检查时，在构建阶段启用增强实验选项。
GOEXPERIMENT=cgocheck2 go test ./...

cgocheck=0 只能关闭检查，不能把不符合规则的程序变安全。官方文档明确说明，绕过规则后程序可能以不可预测的方式失败；排查阶段应修正所有权和生命周期，而不是用关闭检查掩盖问题。

总结

相关问题

为什么 unsafe.Pointer 类型本身不能绕过规则？

因为规则判断的是指向内存的来源和可达指针关系，不是 Go 变量的静态类型。把值转换成 unsafe.Pointer 不会改变内存的分配来源。

把 Go 字符串传给 C 后，C 能不能保存返回的地址？

不能把 _GoString_ 或普通 Go 字符串的内容地址留到调用返回后。若 C 需要长期使用，应复制成 C 字符串，并在 C 侧负责释放。

什么时候应该选择 cgo.Handle？

当 C 只需要一个可回传给 Go 的对象标识，而不是直接访问 Go 对象内存时，Handle 更适合。C 保存整数句柄，Go 侧负责取值和删除句柄。