checklinkname Analyzer

checklinkname is an analyzer to provide rudimentary type-checking for //go:linkname directives. Since //go:linkname only affects linker behavior, there is no built-in type safety and it is the programmer's responsibility to ensure the types on either side are compatible.

checklinkname helps with this by checking that uses match expectations, as defined in this package.

known.go contains the set of known linkname targets. For most functions, we expect identical types on both sides of the linkname. In a few cases, the types may be slightly different (e.g., local redefinition of internal type). It is still the responsibility of the programmer to ensure the signatures in known.go are compatible and safe.

Findings

Here are the most common findings from this package, and how to resolve them.

runtime.foo signature got "BAR" want "BAZ"; stdlib type changed?

The definition of runtime.foo in the standard library does not match the expected type in known.go. This means that the function signature in the standard library changed.

Addressing this will require creating a new linkname directive in a new Go version build-tagged in any packages using this symbol. Be sure to also check to ensure use with the new version is safe, as function constraints may have changed in addition to the signature.

<!-- TODO(b/165820485): This isn't yet explicitly supported. -->

known.go will also need to be updated to accept the new signature for the new version of Go.

Cannot find known symbol "runtime.foo"

The standard library has removed runtime.foo entirely. Handling is similar to above, except existing code must transition away from the symbol entirely (note that is may simply be renamed).

linkname to unknown symbol "mypkg.foo"; add this symbol to checklinkname.knownLinknames type-check against the remote type

A package has added a new linkname directive for a symbol not listed in known.go. Address this by adding a new entry for the target symbol. The local field should be the expected type in your package, while remote should be expected type in the remote package (e.g., in the standard library). These are typically identical, in which case remote can be omitted.

usage: //go:linkname localname [linkname]

Malformed //go:linkname directive. This should be accompanied by a build failure in the package.