gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/tools/checklinkname/README.md (about) 1 # `checklinkname` Analyzer 2 3 `checklinkname` is an analyzer to provide rudimentary type-checking for 4 `//go:linkname` directives. Since `//go:linkname` only affects linker behavior, 5 there is no built-in type safety and it is the programmer's responsibility to 6 ensure the types on either side are compatible. 7 8 `checklinkname` helps with this by checking that uses match expectations, as 9 defined in this package. 10 11 `known.go` contains the set of known linkname targets. For most functions, we 12 expect identical types on both sides of the linkname. In a few cases, the types 13 may be slightly different (e.g., local redefinition of internal type). It is 14 still the responsibility of the programmer to ensure the signatures in 15 `known.go` are compatible and safe. 16 17 ## Findings 18 19 Here are the most common findings from this package, and how to resolve them. 20 21 ### `runtime.foo signature got "BAR" want "BAZ"; stdlib type changed?` 22 23 The definition of `runtime.foo` in the standard library does not match the 24 expected type in `known.go`. This means that the function signature in the 25 standard library changed. 26 27 Addressing this will require creating a new linkname directive in a new Go 28 version build-tagged in any packages using this symbol. Be sure to also check to 29 ensure use with the new version is safe, as function constraints may have 30 changed in addition to the signature. 31 32 <!-- TODO(b/165820485): This isn't yet explicitly supported. --> 33 34 `known.go` will also need to be updated to accept the new signature for the new 35 version of Go. 36 37 ### `Cannot find known symbol "runtime.foo"` 38 39 The standard library has removed runtime.foo entirely. Handling is similar to 40 above, except existing code must transition away from the symbol entirely (note 41 that is may simply be renamed). 42 43 ### `linkname to unknown symbol "mypkg.foo"; add this symbol to checklinkname.knownLinknames type-check against the remote type` 44 45 A package has added a new linkname directive for a symbol not listed in 46 `known.go`. Address this by adding a new entry for the target symbol. The 47 `local` field should be the expected type in your package, while `remote` should 48 be expected type in the remote package (e.g., in the standard library). These 49 are typically identical, in which case `remote` can be omitted. 50 51 ### `usage: //go:linkname localname [linkname]` 52 53 Malformed `//go:linkname` directive. This should be accompanied by a build 54 failure in the package.