Specification

//go:linkname Directive — Specification¶

Focus: Precise reference for the //go:linkname compiler directive — its syntax, semantics, restrictions, version history, and interactions with the compiler and linker.

Sources: - cmd/compile documentation: https://pkg.go.dev/cmd/compile - Go runtime source: https://github.com/golang/go/tree/master/src/runtime - Go 1.23 release notes: https://go.dev/doc/go1.23 - Russ Cox proposal on restricting //go:linkname: https://github.com/golang/go/issues/67401

1. Syntax¶

The directive is a magic comment recognized by cmd/compile. Two forms exist.

//go:linkname localname
//go:linkname localname importpath.name

importpath is the canonical import path of the package that owns the target (e.g., runtime, time, sync). name is the unqualified function or variable name as it appears in that package's source (it may be unexported).

The directive must appear immediately above the declaration it modifies (no blank lines between).

2. Semantics¶

//go:linkname is processed by the compiler and resolved by the linker. It does not produce code at the call site; instead, it changes the symbol name the compiler emits for the local declaration.

Two patterns dominate:

1. Body-less local declaration linked to an external implementation.

//go:linkname nanotime runtime.nanotime
func nanotime() int64

The compiler emits a call to runtime.nanotime; the linker resolves it to the actual symbol at link time. No function body is allowed locally.

1. Local variable linked to an external variable.

//go:linkname startNanoTime runtime.startNanoTime
var startNanoTime int64

The local startNanoTime is the same storage as runtime.startNanoTime. Reads and writes go through the same word in memory.

3. The Go 1.23 restriction¶

Starting in Go 1.23, //go:linkname is gated behind an unsafe import. A package that uses the directive must import unsafe, even if it does not call any function from the package.

package mypkg

import _ "unsafe" // required by //go:linkname

//go:linkname nanotime runtime.nanotime
func nanotime() int64

If the unsafe import is missing, the compiler reports:

linkname directive must be used with import "unsafe"

The blank import is a signal that the package is opting out of the language's normal safety guarantees, the same convention used for unsafe.Pointer itself.

4. Targeting unexported symbols¶

The directive bypasses Go's package visibility rules. A two-argument //go:linkname may name an unexported symbol of another package:

//go:linkname fastrand runtime.fastrand
func fastrand() uint32

runtime.fastrand is lowercase and unexported. Without //go:linkname, no other package could call it. The directive is the only mechanism in Go that breaks export visibility.

The compiler does not require source access to the target package; only the linker needs to resolve the symbol. As long as the named symbol exists in the final binary, the link succeeds.

5. Restrictions¶

There is no syntactic check that the local signature matches the remote one — the compiler accepts any signature and the linker only resolves names. The programmer is responsible for keeping the two in sync.

6. Compiler and linker pipeline¶

source.go        ── compile ──▶  .o file        ── link ──▶  binary
   │                                │                          │
   //go:linkname  ───────────────▶ symbol table entry
   localname        ──renamed──▶  external symbol name

Because the resolution is at link time, you can compile a package against header declarations only — the bodies of runtime.nanotime, runtime.fastrand, etc., are never visible to your compiler invocation.

7. Common targets in the standard library¶

These symbols are routinely linked from inside the standard library and (carefully) from external packages.

The sync package's mutex implementation calls into the runtime through these runtime_ symbols so the runtime can park and unpark goroutines without exporting the goroutine APIs.

8. The bidirectional pattern¶

The standard library frequently uses both ends of the same link to form a closed contract between runtime and a user-facing package.

In runtime/sema.go:

//go:linkname sync_runtime_Semacquire sync.runtime_Semacquire
func sync_runtime_Semacquire(addr *uint32) { ... }

In sync/runtime.go:

//go:linkname runtime_Semacquire
func runtime_Semacquire(s *uint32)

The runtime side defines the body and announces "I provide the symbol sync.runtime_Semacquire". The sync side declares a body-less function with the matching local name, and the linker connects them. This pattern keeps the bridging symbols invisible to user code.

9. Interaction with other directives¶

//go:linkname is frequently combined with other compiler directives.

Each of these directives must appear on its own line above the declaration; order among them does not matter.

10. Version history¶

The trajectory is clear: //go:linkname is for the standard library; external use will become harder, not easier.

11. Constraints summary¶

The unverified signature match is the single largest source of trouble: a function rename or argument-order change in the standard library produces a binary that links but corrupts memory.

12. Tooling¶

The -checklinkname linker flag (added in 1.23) lets release engineers detect external dependencies on internal symbols during integration testing.

13. Non-goals¶

//go:linkname is not:

• A way to override Go's type system. Signature mismatches are silently miscompiled.
• A general FFI mechanism. Use cgo for C interop.
• A stable public API. Linkname targets in runtime may be renamed or removed between releases.
• A substitute for proper API design. The standard library uses it as an internal bridging tool, not a public extension point.

14. Related references¶

• cmd/compile directives index: https://pkg.go.dev/cmd/compile#hdr-Compiler_Directives
• runtime source for popular linkname targets: https://github.com/golang/go/blob/master/src/runtime/time.go
• The 1.23 restriction discussion: https://github.com/golang/go/issues/67401
• "What is //go:linkname?" — Dave Cheney: https://dave.cheney.net/