Linker on Opensource internals

unsafe.Pointer and //go:linkname: The Escape Hatches That Break Abstraction

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: unsafe.Pointer is the type system with the safety catch removed. //go:linkname is the other escape hatch: it lets one package call another package’s unexported function by its link-time symbol name. The linker now keeps an explicit allowlist of who may pull which linkname.

Go’s type system is one of its best features and also, occasionally, an obstacle. Sometimes you need to reinterpret a []byte as a []int32. Sometimes you need to call a function the standard library clearly meant to keep to itself. Go provides two doors for both situations, and both of them are unlocked with a comment that says unsafe or linkname.

Understanding how these work matters even if you never use them, because they explain a lot about how the compiler and linker are put together, and because the guard rails around them have changed a lot in the last few releases.

unsafe.Pointer: the type system, optional

The unsafe package documentation opens with the deal:

 go
 
 
// src/unsafe/unsafe.go:21
// Pointer represents a pointer to an arbitrary type. There are four special operations
// available for type Pointer that are not available for other types:
// - A pointer value of any type can be converted to a Pointer.
// - A Pointer can be converted to a pointer value of any type.
// - A uintptr can be converted to a Pointer.
// - A Pointer can be converted to a uintptr.
//
// Pointer therefore allows a program to defeat the type system and read and write
// arbitrary memory. It should be used with extreme care.
//
// The following patterns involving Pointer are valid.
// Code not using these patterns is likely to be invalid today
// or to become invalid in the future.
// Even the valid patterns below come with important caveats.
//
// Running "go vet" can help find uses of Pointer that do not conform to these patterns,
// but silence from "go vet" is not a guarantee that the code is valid.

Then it enumerates the legal patterns. There are five of them, and the distinctions between them are not academic — they are the difference between code that works and code that breaks the moment the garbage collector moves something.

Pattern 1: reinterpret a pointer.

 go
 
 
// src/unsafe/unsafe.go:39
// (1) Conversion of a *T1 to Pointer to *T2.
//
// Provided that T2 is no larger than T1 and that the two share an equivalent
// memory layout, this conversion allows reinterpreting data of one type as
// data of another type. An example is the implementation of
// math.Float64bits:
//
//	func Float64bits(f float64) uint64 {
//		return *(*uint64)(unsafe.Pointer(&f))
//	}

Pattern 2: convert to uintptr and stop. A uintptr is an integer, not a reference. The collector will not update it and will not keep the object alive.

Pattern 3: convert to uintptr, add an offset, convert back — and the conversion must appear in the same expression:

 go
 
 
// src/unsafe/unsafe.go:68
// (3) Conversion of a Pointer to a uintptr and back, with arithmetic.
//
// If p points into an allocated object, it can be advanced through the object
// by conversion to uintptr, addition of an offset, and conversion back to Pointer.
//
//	p = unsafe.Pointer(uintptr(p) + offset)

If you stash the uintptr in a variable in between, the collector is free to move the object and you get a dangling pointer. This is the single most common way people get unsafe wrong, and it is why go vet has a unsafeptr check for it.

Pattern 4: pass a pointer as a uintptr to a syscall, in the argument list, because the compiler knows to keep the object alive across the call.

Pattern 5: convert the result of reflect.Value.Pointer() back immediately, in the same expression.

Pattern 6: use reflect.SliceHeader / reflect.StringHeader, which are only valid when pointing at an actual slice or string.

The modern intrinsics

The unsafe package has grown a set of functions that are much safer than the raw uintptr dance, and these are what you should reach for first:

 go
 
 
// src/unsafe/unsafe.go:229
// The function Slice returns a slice whose underlying array starts at ptr
// and whose length and capacity are len.
// Slice(ptr, len) is equivalent to
//
//	(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
//
// except that, as a special case, if ptr is nil and len is zero,
// Slice returns nil.
//
// The len argument must be of integer type or an untyped constant.
// A constant len argument must be non-negative and representable by a value of type int;
// if it is an untyped constant it is given type int.
// At run time, if len is negative, or if ptr is nil and len is not zero,
// a run-time panic occurs.
func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType

// SliceData returns a pointer to the underlying array of the argument
// slice.
// - If cap(slice) > 0, SliceData returns &slice[:1][0].
// - If slice == nil, SliceData returns nil.
// - Otherwise, SliceData returns a non-nil pointer to an
// unspecified memory address.
func SliceData(slice []ArbitraryType) *ArbitraryType

unsafe.Slice is the modern replacement for the (*[n]T)(ptr)[:] idiom. It takes a *T rather than an unsafe.Pointer, which means the compiler knows the element type and can size the resulting slice correctly. unsafe.SliceData is the inverse, and unsafe.StringData / unsafe.String do the same job for strings.

None of these are ordinary Go functions. They have no bodies. The compiler gives them dedicated opcodes:

 go
 
 
// src/cmd/compile/internal/typecheck/typecheck.go:456
	case ir.OUNSAFESLICE:
		n := n.(*ir.BinaryExpr)
		return tcUnsafeSlice(curfunc, n)

	case ir.OUNSAFESLICEDATA:
		n := n.(*ir.UnaryExpr)
		return tcUnsafeData(curfunc, n)

	case ir.OUNSAFESTRING:
		n := n.(*ir.BinaryExpr)
		return tcUnsafeString(curfunc, n)

	case ir.OUNSAFESTRINGDATA:
		n := n.(*ir.UnaryExpr)
		return tcUnsafeData(curfunc, n)

The type checker enforces the preconditions:

 go
 
 
// src/cmd/compile/internal/typecheck/func.go:767
// tcUnsafeSlice typechecks an OUNSAFESLICE node.
func tcUnsafeSlice(curfunc *ir.Func, n *ir.BinaryExpr) *ir.BinaryExpr {
	n.X = Expr(curfunc, n.X)
	n.Y = Expr(curfunc, n.Y)
	if n.X.Type() == nil || n.Y.Type() == nil {
		n.SetType(nil)
		return n
	}
	t := n.X.Type()
	if !t.IsPtr() {
		base.Errorf("first argument to unsafe.Slice must be pointer; have %L", t)
	} else if t.Elem().NotInHeap() {
		// TODO(mdempsky): This can be relaxed, but should only affect the
		// Go runtime itself. End users should only see not-in-heap
		// types due to incomplete C structs in cgo, and those types don't
		// have a meaningful size anyway.
		base.Errorf("unsafe.Slice of incomplete (or unallocatable) type not allowed")
	}

And then the compiler inlines the runtime check rather than calling it, to avoid the call overhead:

 go
 
 
// src/cmd/compile/internal/walk/builtin.go:783
func (w *walkState) walkUnsafeSlice(n *ir.BinaryExpr, init *ir.Nodes) ir.Node {
	ptr := w.safeExpr(n.X, init)
	len := w.safeExpr(n.Y, init)
	sliceType := n.Type()

	lenType := types.Types[types.TINT64]
	unsafePtr := typecheck.Conv(w.curfunc, ptr, types.Types[types.TUNSAFEPTR])

	// If checkptr enabled, call runtime.unsafeslicecheckptr to check ptr and len.
	// for simplicity, unsafeslicecheckptr always uses int64.
	// Type checking guarantees that TIDEAL len/cap are positive and fit in an int.
	// The case of len or cap overflow when converting TUINT or TUINTPTR to TINT
	// will be handled by the negative range checks in unsafeslice during runtime.
	if ir.ShouldCheckPtr(w.curfunc, 1) {
		fnname := "unsafeslicecheckptr"
		fn := typecheck.LookupRuntime(fnname)
		init.Append(w.mkcall1(fn, nil, init, reflectdata.UnsafeSliceElemRType(w.curfunc, base.Pos, n), unsafePtr, typecheck.Conv(w.curfunc, len, lenType)))
	} else {
		// Otherwise, open code unsafe.Slice to prevent runtime call overhead.
		// Keep this code in sync with runtime.unsafeslice{,64}

The comment “Keep this code in sync with runtime.unsafeslice{,64}” is a loose end the maintainers knowingly accept: the fast path is open-coded in the compiler, and the slow path lives in the runtime, and they have to agree.

 go
 
 
// src/runtime/unsafe.go:53
// Keep this code in sync with cmd/compile/internal/walk/builtin.go:walkUnsafeSlice
func unsafeslice(et *_type, ptr unsafe.Pointer, len int) {
	if len < 0 {
		panicunsafeslicelen1(sys.GetCallerPC())
	}

	if et.Size_ == 0 {
		if ptr == nil && len > 0 {
			panicunsafeslicenilptr1(sys.GetCallerPC())
		}
	}

	mem, overflow := math.MulUintptr(et.Size_, uintptr(len))
	if overflow || mem > -uintptr(ptr) {
		if ptr == nil {
			panicunsafeslicenilptr1(sys.GetCallerPC())
		}
		panicunsafeslicelen1(sys.GetCallerPC())
	}
}

The mem > -uintptr(ptr) test is the interesting one: it checks that the slice would not extend past the end of the address space, which catches the classic “I multiplied a length by a size and it wrapped around” bug.

checkptr: the runtime’s unsafe sanity checker

Go has a mode that checks the unsafe rules at runtime. It is called checkptr, and it is enabled by -d=checkptr, by -race, and by -msan/-asan:

 go
 
 
// src/cmd/compile/internal/base/flag.go:355
	if Flag.Race || Flag.MSan || Flag.ASan {
		// -race, -msan and -asan imply -d=checkptr for now.
		if Debug.Checkptr == -1 { // if not set explicitly
			Debug.Checkptr = 1
		}
	}

It catches two classes of bug. The first is a conversion that produces a misaligned or out-of-bounds pointer:

 go
 
 
// src/runtime/checkptr.go:9
func checkptrAlignment(p unsafe.Pointer, elem *_type, n uintptr) {
	// nil pointer is always suitably aligned (#47430).
	if p == nil {
		return
	}

	// Check that (*[n]elem)(p) is appropriately aligned.
	// Note that we allow unaligned pointers if the types they point to contain
	// no pointers themselves. See issue 37298.
	// TODO(mdempsky): What about fieldAlign?
	if elem.Pointers() && uintptr(p)&(uintptr(elem.Align_)-1) != 0 {
		throw("checkptr: misaligned pointer conversion")
	}

	// Check that (*[n]elem)(p) doesn't straddle multiple heap objects.
	// TODO(mdempsky): Fix #46938 so we don't need to worry about overflow here.
	if checkptrStraddles(p, n*elem.Size_) {
		throw("checkptr: converted pointer straddles multiple allocations")
	}
}

The second is pointer arithmetic that wanders off into a different allocation:

 go
 
 
// src/runtime/checkptr.go:50
func checkptrArithmetic(p unsafe.Pointer, originals []unsafe.Pointer) {
	if 0 < uintptr(p) && uintptr(p) < minLegalPointer {
		throw("checkptr: pointer arithmetic computed bad pointer value")
	}

	// Check that if the computed pointer p points into a heap
	// object, then one of the original pointers must have pointed
	// into the same object.
	base := checkptrBase(p)
	if base == 0 {
		return
	}

	for _, original := range originals {
		if base == checkptrBase(original) {
			return
		}
	}

	throw("checkptr: pointer arithmetic result points to invalid allocation")
}

The compiler injects the calls. For unsafe.Slice and unsafe.String, the runtime versions do a stricter check that the result does not straddle two heap objects:

 go
 
 
// src/runtime/unsafe.go:83
func unsafeslicecheckptr(et *_type, ptr unsafe.Pointer, len64 int64) {
	unsafeslice64(et, ptr, len64)

	// Check that underlying array doesn't straddle multiple heap objects.
	// unsafeslice64 has already checked for overflow.
	if checkptrStraddles(ptr, uintptr(len64)*et.Size_) {
		throw("checkptr: unsafe.Slice result straddles multiple allocations")
	}
}

And there is an escape hatch for the runtime itself, which cannot afford the checks:

 go
 
 
// src/runtime/mcleanup.go:75
//go:nocheckptr
func AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) Cleanup {
	// This is marked nocheckptr because checkptr doesn't understand the
	// pointer manipulation done when looking at closure pointers.
	// Similar code in mbitmap.go works because the functions are
	// go:nosplit, which implies go:nocheckptr (CL 202158).

//go:nocheckptr on a function tells the compiler not to instrument it. It is also implied by //go:nosplit.

//go:linkname: calling things you were not invited to call

//go:linkname tells the compiler to give a symbol a different link-time name, or to look up a symbol under a different name. The syntax is:

 go
 
 
// src/cmd/compile/internal/noder/noder.go:281
	case strings.HasPrefix(text, "go:linkname "), strings.HasPrefix(text, "go:linknamestd "):
		f := strings.Fields(text)
		if !(2 <= len(f) && len(f) <= 3) {
			p.error(syntax.Error{Pos: pos, Msg: fmt.Sprintf("usage: //%s localname [linkname]", f[0])})
			break
		}
		// The second argument is optional. If omitted, we use
		// the default object symbol name for this and
		// linkname only serves to mark this symbol as
		// something that may be referenced via the object
		// symbol name from another package.
		var target string
		if len(f) == 3 {
			target = f[2]
		} else if base.Ctxt.Pkgpath != "" {
			// Use the default object symbol name if the
			// user didn't provide one.
			target = objabi.PathToPrefix(base.Ctxt.Pkgpath) + "." + f[1]
		} else {
			panic("missing pkgpath")
		}
		p.linknames = append(p.linknames, linkname{pos, f[0] == "go:linknamestd", f[1], target})

There are two directions. A push is //go:linkname localname other.name on a declaration in the defining package, which publishes a symbol under a different name. A pull is a bodyless declaration with a //go:linkname in the using package, which imports the symbol by that name.

The runtime uses pushes extensively, to expose internal machinery to packages that need it:

 go
 
 
// src/runtime/linkname.go:9
// used in internal/godebug and syscall
//go:linkname write

// used by cgo
//go:linkname _cgo_panic_internal
//go:linkname cgoAlwaysFalse
//go:linkname cgoUse
//go:linkname cgoKeepAlive
//go:linkname cgoCheckPointer
//go:linkname cgoCheckResult
//go:linkname cgoNoCallback
//go:linkname gobytes
//go:linkname gostringn

// used in plugin
//go:linkname doInit

// used in math/bits
//go:linkname overflowError
//go:linkname divideError

A one-argument //go:linkname foo is a push that keeps the default symbol name; it exists purely to say “this symbol may be referenced by name from another package”.

The hall of shame

Some of these pushes exist only because third-party code broke in and the Go team decided to accommodate rather than break. The runtime marks those symbols explicitly, and the comment format is consistent enough to grep for:

 go
 
 
// src/runtime/map.go:30
// makemap_small implements Go map creation for make(map[k]v) and
// make(map[k]v, hint) when hint is known to be at most abi.MapGroupSlots
// at compile time and the map needs to be allocated on the heap.
//
// makemap_small should be an internal detail,
// but widely used packages access it using linkname.
// Notable members of the hall of shame include:
// - github.com/bytedance/sonic
//
// Do not remove or change the type signature.
// See go.dev/issue/67401.
//
//go:linkname makemap_small
func makemap_small() *maps.Map {
	return maps.NewEmptyMap()
}

The instruction is explicit: do not remove or change the type signature. The signature is now an ABI contract with half a dozen high-profile libraries, whether those libraries like it or not.

The pattern extends well beyond maps. The runtime maintains a whole file of compatibility shims for the Go 1.24 map iterator rewrite:

 go
 
 
// src/runtime/linkname_shim.go:60
type linknameIter struct {
	// Fields from hiter.
	key unsafe.Pointer
	elem unsafe.Pointer
	typ *abi.MapType

	// The real iterator.
	it *maps.Iter
}

with a comment explaining that the shim’s layout has to match the old hiter struct exactly, or the collector will not track the pointers in it correctly:

Our structure must maintain compatibility with the old structure. This means:

Our structure must be the same size or smaller than hiter. Otherwise we may write outside the caller’s hiter allocation.

Our structure must have the same pointer layout as hiter, so that the GC tracks pointers properly.

The full list of shims in that file includes mapiterinit, mapiternext, reflect_mapiterinit, reflect_mapiternext, reflect_mapiterkey and reflect_mapiterelem — six symbols that exist only so that github.com/bytedance/sonic, github.com/segmentio/encoding, github.com/ugorji/go/codec and others keep working.

The linker enforces who may pull what

Go 1.23 tightened this substantially. The linker now checks every linkname reference against an explicit allowlist:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2438
// A list of blocked linknames. Some linknames are allowed only
// in specific packages. This maps symbol names to allowed packages.
// If a name is not in this map, it is allowed iff the definition
// has a linkname (push).
// If a name is in this map, it is allowed only in listed packages,
// even if it has a linknamed definition.
var blockedLinknames = map[string][]string{
	// fips info
	"go:fipsinfo": {"crypto/internal/fips140/check"},
	// New internal linknames in Go 1.24
	// Pushed from runtime
	"crypto/internal/fips140.fatal": {"crypto/internal/fips140"},
	"crypto/internal/fips140.getIndicator": {"crypto/internal/fips140"},
	"crypto/internal/fips140.setIndicator": {"crypto/internal/fips140"},
	"crypto/internal/sysrand.fatal": {"crypto/internal/sysrand"},
	"crypto/rand.fatal": {"crypto/rand"},
	"internal/runtime/maps.errNilAssign": {"internal/runtime/maps"},
	"internal/runtime/maps.fatal": {"internal/runtime/maps"},
	"internal/runtime/maps.newarray": {"internal/runtime/maps"},
	"internal/runtime/maps.newobject": {"internal/runtime/maps"},
	"internal/runtime/maps.rand": {"internal/runtime/maps"},
	"internal/runtime/maps.typedmemclr": {"internal/runtime/maps"},
	"internal/runtime/maps.typedmemmove": {"internal/runtime/maps"},

and at the bottom, the entry that is allowed from nowhere at all:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2527
	"runtime.addmoduledata": {}, // assembly symbol, disallow all packages
}

The check itself:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2530
// check if a linkname reference to symbol s from refpkg is allowed
func (l *Loader) checkLinkname(refpkg *oReader, name string, s Sym) {
	if l.flags&FlagCheckLinkname == 0 {
		return
	}

	pkg := refpkg.unit.Lib.Pkg
	error := func() {
		log.Fatalf("%s: invalid reference to %s", pkg, name)
	}
	pkgs, ok := blockedLinknames[name]
	if ok {
		for _, p := range pkgs {
			if pkg == p {
				return // pkg is allowed
			}
			// crypto/internal/fips140/vX.Y.Z/... is the frozen version of
			// crypto/internal/fips140/... and is similarly allowed.
			if strings.HasPrefix(pkg, "crypto/internal/fips140/v") {
				parts := strings.Split(pkg, "/")
				parts = append(parts[:3], parts[4:]...)
				pkg := strings.Join(parts, "/")
				if pkg == p {
					return
				}
			}
		}
		error()
	}

The default rule, stated in the comment above the map, is the important one: if a name is not in this map, it is allowed iff the definition has a linkname (push). So the ordinary case still works — a package that pushes a symbol can be pulled by anyone. The map is the exception list, for symbols the runtime wants to keep to itself.

And there is a second tier, for symbols pushed with //go:linknamestd, which are restricted to the standard library:

 go
 
 
// src/cmd/link/internal/loader/loader.go:2599
	if osym.IsLinknameStd() {
		// It is pushed with linknamestd. Allow only pulls from the
		// standard library.
		if refpkg.Std() {
			return
		}
	}
	if osym.IsLinkname() {
		// Allow if the def has a linkname (push).
		return
	}
	error()
}

//go:linknamestd is the newer, stricter directive. A symbol pushed with it can only be pulled from within the standard library. That is how the runtime can expose internal machinery to internal/... packages without opening it to the entire ecosystem.

The whole check is behind -checklinkname, which is on by default for standard-library builds:

 go
 
 
// src/cmd/link/internal/ld/lib.go:531
	if *flagCheckLinkname {
		flags |= loader.FlagCheckLinkname
	}

Dead code elimination and method pruning

Now, the part that connects //go:linkname to binary size. The linker performs a reachability analysis from the entry point and deletes everything that is unreachable. But it cannot simply delete every method of every type, because reflection can find methods at runtime by name.

The linker’s dead code pass describes the problem and the three ways a method can be invoked:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:402
// deadcode marks all reachable symbols.
//
// The basis of the dead code elimination is a flood fill of symbols,
// following their relocations, beginning at *flagEntrySymbol.
//
// This flood fill is wrapped in logic for pruning unused methods.
// All methods are mentioned by relocations on their receiver's *rtype.
// These relocations are specially defined as R_METHODOFF by the compiler
// so we can detect and manipulated them here.
//
// There are three ways a method of a reachable type can be invoked:
//
// 1. direct call
// 2. through a reachable interface type
// 3. reflect.Value.Method (or MethodByName), or reflect.Type.Method
// (or MethodByName)
//
// The first case is handled by the flood fill, a directly called method
// is marked as reachable.
//
// The second case is handled by decomposing all reachable interface
// types into method signatures. Each encountered method is compared
// against the interface method signatures, if it matches it is marked
// as reachable. This is extremely conservative, but easy and correct.
//
// The third case is handled by looking for functions that compiler flagged
// as REFLECTMETHOD. REFLECTMETHOD on a function F means that F does a method
// lookup with reflection, but the compiler was not able to statically determine
// the method name.
//
// All functions that call reflect.Value.Method or reflect.Type.Method are REFLECTMETHODs.
// Functions that call reflect.Value.MethodByName or reflect.Type.MethodByName with
// a non-constant argument are REFLECTMETHODs, too. If we find a REFLECTMETHOD,
// we give up on static analysis, and mark all exported methods of all reachable
// types as reachable.
//
// If the argument to MethodByName is a compile-time constant, the compiler
// emits a relocation with the method name. Matching methods are kept in all
// reachable types.
//
// Any unreached text symbols are removed from ctxt.Textp.

The “REFLECTMETHOD” flag is set by the compiler, in two places. One is when you call MethodByName with a non-constant argument:

 go
 
 
// src/cmd/compile/internal/walk/expr.go:1146
	} else {
		w.curfunc.LSym.Set(obj.AttrReflectMethod, true)
	}

The other is when a function value of reflect.Value.Method is taken:

 go
 
 
// src/cmd/compile/internal/staticdata/data.go:291
		// A function value of reflect.Value.Method or MethodByName may be
		// called with a method name the compiler cannot see; see usemethod.
		if s.Pkg.Path == "reflect" && (s.Name == "Value.Method" || s.Name == "Value.MethodByName") {
			sf.Set(obj.AttrReflectMethod, true)
		}

The linker reads that flag:

 go
 
 
// src/cmd/link/internal/loader/loader.go:1252
// Returns whether the i-th symbol has ReflectMethod attribute set.
func (l *Loader) IsReflectMethod(i Sym) bool {
	return l.SymAttr(i)&goobj.SymFlagReflectMethod != 0
}

and uses it to decide whether to give up on pruning:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:460
		rem := d.markableMethods[:0]
		for _, m := range d.markableMethods {
			if (d.reflectSeen && (m.isExported() || d.dynlink)) || d.ifaceMethod[m.m] || d.genericIfaceMethod[m.m.name] {
				d.markMethod(m)
			} else {
				rem = append(rem, m)
			}
		}

Read that condition carefully. If any function in the program does a non-constant MethodByName, then every exported method of every reachable type is kept. One reflect-by-name call anywhere in your dependency tree can cost you a substantial fraction of your binary size. That is a real and frequently surprising effect.

There is a mitigation. If the argument to MethodByName is a compile-time constant, the compiler emits a relocation naming the method, and the linker can keep only the matching methods. That is the R_USENAMEDMETHOD relocation visible in the same compiler file.

Trade-offs

What the escape hatches buy you:

Zero-copy reinterpretation. unsafe.Slice and unsafe.String let you build a view over memory you already have without copying it.
Access to runtime internals. The standard library’s own packages use //go:linkname to share machinery that is not part of the public API.
Interoperability. Talking to C, to the kernel, or to a memory-mapped device requires unsafe.Pointer somewhere.
A working reflect. reflect itself is a large pile of unsafe.

What they cost:

The compiler stops helping. No bounds checks, no nil checks, no escape analysis guarantees you can rely on.
The collector stops helping. A uintptr in a variable is not a reference. The object can move, or be collected, while you hold it.
You break the compatibility promise. The unsafe package’s own docs say so: “Packages that import unsafe may be non-portable and are not protected by the Go 1 compatibility guidelines.”
You break the linker. A linkname pull from a package that is not allowed is a hard log.Fatalf at link time, not a compile error.
You opt out of method pruning. One MethodByName with a non-constant argument keeps every exported method of every reachable type.

Caveats

unsafe code is not “mostly safe”. The rules in the package doc are precise, and the moment you deviate from them the failure is silent corruption rather than a panic.

checkptr is not on by default. -race turns it on, but a normal production build does not check anything. If your code depends on unsafe being correct, test it with -race or -d=checkptr=1.

//go:nocheckptr silently disables the checks for that function. It is used sparingly in the runtime and it is exactly the sort of thing you should not reach for.

Linkname pulls are checked at link time, not compile time. The compiler will happily compile //go:linkname foo runtime.someInternalThing and you will find out when the linker says invalid reference to runtime.someInternalThing.

The allowlist changes. The blockedLinknames map is updated every release, with sections marked “New internal linknames in Go 1.24”, “Go 1.25”, “Go 1.26”. A linkname that works today can stop working.

//go:linknamestd is the one to prefer if you are writing a package that legitimately needs a runtime internal. It restricts the pull to the standard library, so you are not opening your package’s internals to the world.

Do not linkname into the runtime from a third-party package. It works until it does not. The Go team’s position is visible in the runtime’s own comments: “Do not remove or change the type signature. See go.dev/issue/67401.” That is a promise made under duress.

Wrapping up

The one thing to remember: unsafe.Pointer is where the type system ends and //go:linkname is where the package boundary ends. Both are deliberate, documented holes, and both are policed by machinery that has got much stricter over the last few releases.

The part people get wrong: unsafe.Pointer converted to uintptr and stored in a variable is no longer a pointer. The garbage collector does not update it and does not keep the object alive. The conversion has to happen inside a single expression.

What to go do about it: turn on -race in your test suite. It implies -d=checkptr, it catches misaligned and straddling unsafe conversions, and it costs you nothing in production. If you have a MethodByName with a non-constant argument anywhere in your dependency tree, replace it with a constant one — you may be keeping a lot of dead methods alive.

Go's Linker Deletes Code You Never Call: Method Pruning and Reachability

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Go binaries are not “the standard library plus your code”. The linker floods the symbol graph starting at main.main, keeps only what it reaches, and then throws away the method tables of surviving types unless an interface or a reflective call could reach them. Everything it drops is gone from the binary — code, DWARF, and (with -s) the symbol table.

Every Go binary you ship contains a net/http server, a crypto/tls stack, a JSON encoder, and about nine hundred other packages’ worth of code. Almost none of it is running. Most of it is not even in the binary.

The Go linker does a reachability analysis over the symbol graph and deletes what it cannot prove is live. The interesting part is not that it deletes unreachable functions — that is easy. It is what it does with methods, because a method can be reached three ways and only one is visible in the object file.

This is a walk through how it works, based on reading the Go 1.28 development tree.

The rule the linker follows

The whole design is stated in one comment, in src/cmd/link/internal/ld/deadcode.go, and it comes down to three ways a method of a reachable type can be invoked:

A direct call — handled by the flood fill.
A call through an interface — handled by signature matching, which is deliberately over-conservative.
A call through reflection — handled by giving up.

The flood fill

The pass itself is a worklist algorithm over the symbol graph. The deadcodePass struct holds the state:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:22
type deadcodePass struct {
	ctxt *Link
	ldr *loader.Loader
	wq heap // work queue, using min-heap for better locality

	ifaceMethod map[methodsig]bool // methods called from reached interface call sites
	genericIfaceMethod map[string]bool // names of methods called from reached generic interface call sites
	markableMethods []methodref // methods of reached types
	reflectSeen bool // whether we have seen a reflect method call
	dynlink bool

The roots are main.main (or the entry symbol), runtime.unreachableMethod, the dynamic exports, and the package init tasks:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:82
	// runtime.unreachableMethod is a function that will throw if called.
	// We redirect unreachable methods to it.
	names = append(names, "runtime.unreachableMethod")

Marking is simple — a bitmap on the loader, and a push onto a min-heap so the traversal visits symbols in a cache-friendly order:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:359
func (d *deadcodePass) mark(symIdx, parent loader.Sym) {
	if symIdx != 0 && !d.ldr.AttrReachable(symIdx) {
		d.wq.push(symIdx)
		d.ldr.SetAttrReachable(symIdx, true)
		if buildcfg.Experiment.FieldTrack && d.ldr.Reachparent[symIdx] == 0 {
			d.ldr.Reachparent[symIdx] = parent
		}
		if *flagDumpDep {

Reachparent is a nice touch: with the FieldTrack experiment on, the linker records which symbol made each symbol live.

Where the method table lives

A method is not a symbol you can point at directly from the type descriptor. The rtype holds an array of reflect.method structs, and each entry has three relocations (mtyp, ifn, tfn). The compiler marks those relocations with a special type, R_METHODOFF, so the linker can find them:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:384
func dmethodptrOff(c rttype.Cursor, x *obj.LSym) {
	c.WriteInt32(0)
	c.Reloc(obj.Reloc{Type: objabi.R_METHODOFF, Sym: x})
}

And the table itself is written into the UncommonType section that follows the common type data:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:345
	c.Field("Mcount").WriteUint16(uint16(mcount))
	c.Field("Xcount").WriteUint16(uint16(xcount))
	c.Field("Moff").WriteUint32(uint32(dataAdd))
	// Note: there is an unused uint32 field here.

	// Write the backing array for the []method field.
	array := rttype.NewArrayCursor(lsym, off+int64(dataAdd), rttype.Method, mcount)
	for i, a := range m {
		exported := types.IsExported(a.name.Name)
		var pkg *types.Pkg
		if !exported && a.name.Pkg != typePkg(t) {
			pkg = a.name.Pkg

Note Mcount (all methods) and Xcount (exported methods). Different numbers, and that distinction is what makes pruning possible: the exported prefix is the part reflection can reach.

The linker sees these relocations while flooding but does not follow them immediately — that would keep every method of every reachable type alive. Instead it records them as “markable”:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:184
			case objabi.R_METHODOFF:
				if i+2 >= relocs.Count() {
					panic("expect three consecutive R_METHODOFF relocs")
				}
				if usedInIface {
					methods = append(methods, methodref{src: symIdx, r: i})
					// The method descriptor is itself a type descriptor, and
					// it can be used to reach other types, e.g. by using
					// reflect.Type.Method(i).Type.In(j). We need to traverse
					// its child types with UsedInIface set. (See also the
					// comment below.)
					rs := r.Sym()
					if !d.ldr.AttrUsedInIface(rs) {
						d.ldr.SetAttrUsedInIface(rs, true)

Two things are happening. The method is only a candidate if its type is “used in interface” — converted to an interface somewhere, so an interface call might dispatch to it. And the method’s own type descriptor is marked reachable, because reflect.Type.Method(i).Type.In(j) reaches types through it.

At the end of the flood, the candidate methods are decoded. The linker reads the method’s name and type straight out of the type descriptor:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:543
func (d *deadcodePass) decodetypeMethods(ldr *loader.Loader, arch *sys.Arch, symIdx loader.Sym, relocs *loader.Relocs) []methodsig {
	p := ldr.Data(symIdx)
	if !decodetypeHasUncommon(arch, p) {
		panic(fmt.Sprintf("no methods on %q", ldr.SymName(symIdx)))
	}
	off := abi.RTypeSize(decodetypeKind(arch, p), arch.PtrSize)

	mcount := int(decodeInuxi(arch, p[off+4:], 2))
	moff := int(decodeInuxi(arch, p[off+4+2+2:], 4))
	off += moff // offset to array of reflect.method values

mcount and moff are read straight out of the UncommonType header the compiler wrote. This is the linker and the compiler agreeing on a binary layout — which is why internal/abi exists, and why the compiler has a separate rttype package mirroring it.

The pruning loop

Pruning is not a single pass, because pruning a method can reveal new interfaces, which keep more methods alive. The loop repeats until the work queue drains:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:455
	for {
		// Mark all methods that could satisfy a discovered
		// interface as reachable. We recheck old marked interfaces
		// as new types (with new methods) may have been discovered
		// in the last pass.
		rem := d.markableMethods[:0]
		for _, m := range d.markableMethods {
			if (d.reflectSeen && (m.isExported() || d.dynlink)) || d.ifaceMethod[m.m] || d.genericIfaceMethod[m.m.name] {
				d.markMethod(m)
			} else {
				rem = append(rem, m)
			}

That single if is the whole method-pruning policy. A candidate method survives if any of these hold:

reflectSeen and the method is exported — reflection could call it.
d.ifaceMethod[m.m] — some reachable interface has a method with the same name and the same function type.
d.genericIfaceMethod[m.m.name] — some reachable generic interface call site named this method.

The matching is by signature, not by implementation. If any reachable interface declares a Read([]byte) (int, error), every interface-used type with a matching method keeps it — even if it could never be assigned to that interface. The comment calls this “extremely conservative, but easy and correct”, and it is: the analysis is linear and cannot drop a live method.

The reflection escape hatch

The third route — reflection — is where the linker gives up, and when it gives up is the single biggest lever on binary size. The compiler sets a flag on the function that does the reflective lookup. If the method name is a compile-time constant, it can emit a precise relocation:

 go
 
 
// src/cmd/compile/internal/walk/expr.go:1140
	if ir.IsConst(targetName, constant.String) {
		name := constant.StringVal(targetName.Val())
		w.curfunc.LSym.AddRel(base.Ctxt, obj.Reloc{
			Type: objabi.R_USENAMEDMETHOD,
			Sym: staticdata.StringSymNoCommon(name),
		})
	} else {
		w.curfunc.LSym.Set(obj.AttrReflectMethod, true)
	}

If the name is not constant, the function gets the REFLECTMETHOD attribute and the linker will keep every exported method of every reachable type. The linker sees this through the loader:

 go
 
 
// src/cmd/link/internal/loader/loader.go:1252
// Returns whether the i-th symbol has ReflectMethod attribute set.
func (l *Loader) IsReflectMethod(i Sym) bool {
	return l.SymAttr(i)&goobj.SymFlagReflectMethod != 0
}

And the flood pass flips a single global boolean the moment it sees one:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:141
		// Methods may be called via reflection. Give up on static analysis,
		// and mark all exported methods of all reachable types as reachable.
		d.reflectSeen = d.reflectSeen || d.ldr.IsReflectMethod(symIdx)

There is a second, sneakier way to get flagged. reflect.Value.Method and reflect.Value.MethodByName are function values, and the compiler flags any function whose address is taken for that purpose:

 go
 
 
// src/cmd/compile/internal/staticdata/data.go:291
		// A function value of reflect.Value.Method or MethodByName may be
		// called with a method name the compiler cannot see; see usemethod.
		if s.Pkg.Path == "reflect" && (s.Name == "Value.Method" || s.Name == "Value.MethodByName") {
			sf.Set(obj.AttrReflectMethod, true)
		}

So even m := reflect.Value.Method; m(v, 3) — where v is not even an interface — turns on “keep every exported method” for the whole binary. A documented cost, and reflect says so out loud:

 go
 
 
// src/reflect/value.go:1895
// Calling this method will force the linker to retain all exported methods in all packages.
// This may make the executable binary larger but will not affect execution time.
func (v Value) Method(i int) Value {

“Will not affect execution time” is the important half. Pruning is a link-time decision that never adds a runtime branch: a binary with all its methods retained runs exactly as fast as one with half of them removed. It is just bigger.

What happens to the pruned methods

Pruned methods are not merely unreferenced — they are actively poisoned. A relocation to a symbol the linker considers unreachable is redirected to a runtime stub that throws:

 go
 
 
// src/cmd/link/internal/ld/data.go:353
		case objabi.R_ADDR, objabi.R_PEIMAGEOFF:
			if weak && !ldr.AttrReachable(rs) {
				// Redirect it to runtime.unreachableMethod, which will throw if called.
				rs = syms.unreachableMethod
			}

And that stub is deliberately loud:

 go
 
 
// src/runtime/iface.go:726
// unreachable to a reference to this function, so it will throw if
// ever called.
func unreachableMethod() {
	throw("unreachable method called. linker bug?")
}

“linker bug?” — because if this fires, the linker was wrong. A canary, not a feature.

The linker also checks itself. Any non-weak relocation to a symbol it believes is unreachable is a hard error:

 go
 
 
// src/cmd/link/internal/ld/data.go:260
		if rs != 0 && rst != sym.STLSBSS && !weak && rt != objabi.R_METHODOFF && !ldr.AttrReachable(rs) {
			st.err.Errorf(s, "unreachable sym in relocation: %s", ldr.SymName(rs))
		}

R_METHODOFF is excluded precisely because those relocations are supposed to point at not-yet-decided methods.

The size effect

A Go binary’s size is dominated by three things: reachable code, type metadata, and debug information. Dead code elimination takes the first. Method pruning takes a slice of the second — a bigger slice than you would think, because a method’s metadata is not just the function body. Each method carries a reflect.method entry, a method wrapper (the ABI0→ABIInternal thunk), a type descriptor for its signature, and its name string. Pruning one method can take five or six objects with it.

The most dramatic size effect is not method pruning at all — it is reflection. A program that calls reflect.Value.MethodByName(name) with a runtime string keeps every exported method of every reachable type in the program. That is the difference between a 4 MB binary and an 11 MB one, and it comes down to a single boolean.

`-w` and `-s`: the other half of the size story

Reachability pruning is about code. Debug information is a separate lever, and a much bigger one for most binaries. The linker has two flags for it:

 go
 
 
// src/cmd/link/internal/ld/main.go:64
	flag.Var(&flagW, "w", "disable DWARF generation")

 go
 
 
// src/cmd/link/internal/ld/main.go:100
	FlagS = flag.Bool("s", false, "disable symbol table")

-s implies -w, which the linker resolves at startup:

 go
 
 
// src/cmd/link/internal/ld/main.go:270
	switch flagW {
	case ternaryFlagFalse:
		*FlagW = false
	case ternaryFlagTrue:
		*FlagW = true
	case ternaryFlagUnset:
		*FlagW = *FlagS // -s implies -w if not explicitly set
		if ctxt.IsDarwin() && ctxt.BuildMode == BuildModeCShared && !*FlagSplitDWARF {

In external-linking mode the same flags are handed down to the host linker as -s or -Wl,-S.

-w short-circuits DWARF generation:

 go
 
 
// src/cmd/link/internal/ld/dwarf.go:1841
func dwarfEnabled(ctxt *Link) bool {
	if *FlagW { // disable dwarf
		return false
	}
	if ctxt.HeadType == objabi.Hplan9 || ctxt.HeadType == objabi.Hjs || ctxt.HeadType == objabi.Hwasip1 {
		return false
	}

The two flags do different things:

Flag	Removes	Kept
`-w`	DWARF debug info: types, variables, line tables, inlined frames	The symbol table — you can still `nm` the binary
`-s`	The symbol table: function and object names	Nothing extra; also implies `-w`

-w is nearly free in production: you lose the debugger and the profiler’s symbolication but keep go tool nm. -s is more aggressive — the symbol table is what objdump, pprof and most crash symbolizers read, and without it your stack traces become raw addresses. The usual production recipe is -ldflags="-s -w", or just -w if you want a profile-able binary.

Trade-offs

What pruning buys: smaller binaries, faster cold starts, less page cache pressure. On a typical service binary the difference between -ldflags="-s -w" and no flags is easily 25-30% of file size.

What it costs:

Reflection is a size cliff. One MethodByName with a runtime string keeps every exported method in the program. This is the single most common cause of “why is my Go binary 10 MB”.
The interface matching is conservative. Any reachable interface with a matching signature keeps that method on every interface-used type, whether or not that type could ever satisfy the interface.
Pruning happens at link time. You pay for the analysis on every link, and the result depends on the whole program, so it cannot be cached per-package.
Stripping symbols breaks tooling. -s removes what pprof, objdump and most error reporters need. You trade observability for bytes.

Caveats

-s and -w are not the same. -w only removes DWARF. The symbol table survives, so go tool nm still works. -s implies -w, and you can negate that with -w=0.

Pruning does not change runtime behaviour, only size. If a reachable method was removed, the linker would have redirected the call to unreachableMethod and thrown “unreachable method called. linker bug?” at runtime. Seeing that panic means the linker is wrong — most likely an unsupported //go:linkname, a plugin, or a -linkshared build.

Shared libraries and plugins disable most of this. A -buildmode=shared library marks every symbol it defines as reachable, and dynamic linking forces reflectSeen = true:

 go
 
 
// src/cmd/link/internal/ld/deadcode.go:449
	if ctxt.DynlinkingGo() {
		// Exported methods may satisfy interfaces we don't know
		// about yet when dynamically linking.
		d.reflectSeen = true
	}

The linker catches its own mistakes. Any strong relocation to an unreachable symbol is a link-time error, not a silent corruption.

The reflection escape hatch only keeps exported methods. Unexported methods are never kept by it, because reflect cannot reach them by name either.

Wrapping up

The one thing to remember: the Go linker deletes code you never call. It floods the symbol graph from main.main, follows relocations, and keeps only what it reaches. Everything else never makes it into the binary.

The part people get wrong: the linker cannot see reflection. One reflect.Value.MethodByName with a non-constant argument — or even taking the address of reflect.Value.Method — sets a flag that keeps every exported method of every reachable type in the binary. If your Go binary is inexplicably huge, look there first.

What to go do about it: build with -ldflags="-w" (or -s -w if you do not need a symbolisable binary) and measure. Then run go tool nm -size on the result and look for functions from packages you never imported by hand — net/http, crypto/x509, regexp — and ask whether something in your dependency graph is calling MethodByName.

Linker on Opensource internals

unsafe.Pointer and //go:linkname: The Escape Hatches That Break Abstraction

unsafe.Pointer: the type system, optional

The modern intrinsics

checkptr: the runtime’s unsafe sanity checker

//go:linkname: calling things you were not invited to call

The hall of shame

The linker enforces who may pull what

Dead code elimination and method pruning

Trade-offs

Caveats

Wrapping up

Further reading

Go's Linker Deletes Code You Never Call: Method Pruning and Reachability

The rule the linker follows

The flood fill

Where the method table lives

The pruning loop

The reflection escape hatch

What happens to the pruned methods

The size effect

`-w` and `-s`: the other half of the size story

Trade-offs

Caveats

Wrapping up

Further reading

Linker on Opensource internals

unsafe.Pointer and //go:linkname: The Escape Hatches That Break Abstraction

unsafe.Pointer: the type system, optional

The modern intrinsics

checkptr: the runtime’s unsafe sanity checker

//go:linkname: calling things you were not invited to call

The hall of shame

The linker enforces who may pull what

Dead code elimination and method pruning

Trade-offs

Caveats

Wrapping up

Further reading

Go's Linker Deletes Code You Never Call: Method Pruning and Reachability

The rule the linker follows

The flood fill

Where the method table lives

The pruning loop

The reflection escape hatch

What happens to the pruned methods

The size effect

-w and -s: the other half of the size story

Trade-offs

Caveats

Wrapping up

Further reading

`-w` and `-s`: the other half of the size story