From ef90a565b50af191c4f20b62770b084d6978a88d Mon Sep 17 00:00:00 2001 From: Cherry Mui Date: Thu, 2 Apr 2026 11:37:19 -0400 Subject: runtime: mention linknamestd in HACKING.md Change-Id: Icc89533e4cfc737bfee8b0c7a72006bdc79746c2 Reviewed-on: https://go-review.googlesource.com/c/go/+/762280 Reviewed-by: Michael Pratt LUCI-TryBot-Result: Go LUCI --- src/runtime/HACKING.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'src/runtime') diff --git a/src/runtime/HACKING.md b/src/runtime/HACKING.md index 924471e835..28b90c4455 100644 --- a/src/runtime/HACKING.md +++ b/src/runtime/HACKING.md @@ -279,6 +279,7 @@ Linkname conventions ``` //go:linkname localname [importpath.name] +//go:linknamestd localname [importpath.name] ``` `//go:linkname` specifies the symbol name (`importpath.name`) used to a @@ -286,10 +287,17 @@ reference a local identifier (`localname`). The target symbol name is an arbitrary ELF/macho/etc symbol name, but by convention we typically use a package-prefixed symbol name to keep things organized. +`//go:linknamestd`, introduced in Go 1.27, is similar. The difference is that +`linknamestd` allows the symbol to be accessed within the standard library +only, whereas `linkname` permits external accesses. See "Linker check" below. +The linkname conventions discussed here apply to `linknamestd` as well. + The full generality of `//go:linkname` is very flexible, so as a convention to simplify things, we define three standard forms of `//go:linkname` directives. When possible, always prefer to use the linkname "handshake" described below. +If the linkname is needed only within the standard library, `linknamestd` is +preferred. "Push linkname" --------------- @@ -389,6 +397,9 @@ package otherpkg func runtime_foo() ``` +Linker check +------------ + As of Go 1.23, the linker forbids pull linknames of symbols in the standard library unless they participate in a handshake. Since many third-party packages already have pull linknames to standard library functions, for backwards -- cgit v1.3-6-g1900