How do GODEBUG=cgocheck=1 and GOEXPERIMENT=cgocheck2 differ in the cgo pointer violations they catch?

## Why a checker is needed at all The pointer-passing rules cannot be enforced by the compiler, because the interesting half of each rule is about what C does after it has your pointer. The runtime therefore does what it can dynamically, and it comes in two strengths with very different costs. ## cgocheck=1, the default Every cgo call goes through generated code that inspects the pointer arguments before entering C. It follows a passed Go pointer and checks whether the memory it leads to contains further Go pointers to unpinned memory; if it does, the program aborts with a message naming that condition. It also checks that a Go function exported to C does not return a Go pointer. This mode is on by default, and it is deliberately cheap: it inspects only the argument being passed, at the moment of the call. That means it catches the *content* rule reliably and the *retention* rule not at all. If C stashes your `*int` in a global and dereferences it three calls later, cgocheck=1 saw a legal argument and said nothing. `GODEBUG=cgocheck=0` switches it off. There is a narrow performance argument for that in a hot cgo loop and essentially no good reason to ship it; if the checks cost enough to matter, the call itself almost certainly does too. ## cgocheck2, the thorough mode The expensive mode is enabled at build time with `GOEXPERIMENT=cgocheck2`. It used to be `GODEBUG=cgocheck=2` and moved to a build-time experiment in Go 1.21 — a detail worth knowing, because a runbook written before that change tells you to set a `GODEBUG` that no longer does anything. It works by keeping write barriers enabled on **all** pointer writes, not just the ones the collector needs, so the runtime can inspect every store of a Go pointer and complain when the destination is not Go memory. That is the class of violation the cheap mode structurally cannot see: C writing a Go pointer into a C struct, or Go code itself writing one into memory that turns out to be C-allocated. The cost is the whole program, not just the cgo calls. Every pointer write in every package pays. It is a mode you build for a CI job, a soak test, or a bisect when you have corruption you cannot localise — never a production posture. ## What both modes cannot tell you They are dynamic checks, with the same epistemics as the race detector: they report violations that **actually happened** during the run. A clean run proves nothing about a path that did not execute — the error branch that passes a different struct, the retry that reuses a stale context, the code path only a particular input reaches. "We ran the suite under cgocheck2 and it was clean" is a real signal about the covered paths and no signal at all about the rest. If the C boundary is worth checking, it is worth a test that deliberately drives the unusual paths through it. ## Diagnosing the failure they exist to prevent The underlying bug — a Go pointer retained on the C side and later invalidated — does not present as a panic. It presents as corruption: a field with an impossible value, a map that misbehaves, a crash in code that never touched cgo, all of it minutes and megabytes away from the cause. That distance is what makes the checkers worth building into a pipeline rather than reaching for after the fact. A workable sequence when you suspect it: reproduce under the default checks first, since a content-rule violation aborts immediately and is the cheapest possible answer; then rebuild with `GOEXPERIMENT=cgocheck2` and rerun the suite, which catches the storing class; then, if it is still hiding, build with `-asan` or `-msan` to bring a C-level memory checker to bear on the C side, which is where a retention violation actually manifests. Alongside all of it, re-read the C API's documentation for anything that retains what you pass — that reading often finds the bug faster than any of the tools. ## The reviewer's version of this For the pull request that adds a repository's first cgo call, the useful posture is: default checks stay on in every build, a CI job builds the package with `GOEXPERIMENT=cgocheck2` and runs its tests, and any C function that retains a pointer is called out in a comment at the call site. None of that is expensive, and it converts a class of bug that is nearly undebuggable into one that fails loudly in a pipeline.