SyntaxPilot
Courses/Go Programming/Lesson 75
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 75 of 89

cgo and unsafe

cgoimport "C"calling C from GoC types and memory ownershipcgo call overheadcgo and cross-compilationunsafe.Pointer conversion rulesunsafe.Sliceunsafe.Stringunsafe.StringDatago:linkname (and why it is restricted)when to avoid cgo

These are the notes for Go episode 75. Raju's billing engine is written in C: fifteen years of tax rules, rounding rules and bug fixes that the accountants trust. Rewriting it in Go would take months and bring new bugs into old rules. When two business people speak different languages, they bring a translator; Go's translator is cgo. From there we invent everything needed to cross safely between Go and C: the preamble, type conversions, C strings and who frees them, the rules for Go pointers, the toll each crossing costs, and the unsafe package with its rules and inspectors.

All outputs below are from real runs (Go 1.24.7, linux/amd64, gcc), through the same runner the video's compiler uses. Each block shows the commands at the top (// $ ...) and the files separated by // ---- name ---- lines; to run one yourself, put each file in a folder with a go.mod (module shop, go 1.24) and run the commands. The runner prints normal output first and the error stream after it. Benchmark numbers change from run to run and machine to machine; the ones here are from one real run.

Facts and sources

The go.dev pages could not be opened from this episode's sandbox, so the same documents were read from their sources: the golang/website repository on GitHub (the blog and release notes) and the documentation comments in the Go 1.24.7 source tree (src/cmd/cgo/doc.go, src/unsafe/unsafe.go).

  • "C? Go? Cgo!" (go.dev/blog/cgo, Andrew Gerrand, 17 March 2011): "Cgo lets Go packages call C code." C is a "pseudo-package", "a special name interpreted by cgo as a reference to C's name space." The comment above import "C" is "used as a header when compiling the C parts of the package." "Memory allocations made by C code are not known to Go's memory manager. When you create a C string with C.CString (or any C memory allocation) you must remember to free the memory when you're done with it by calling C.free." C.CString, C.GoString and C.GoStringN "make a copy of the string data", and deferring the free right after allocating is "a common idiom".
  • cmd/cgo documentation: "Cgo enables the creation of Go packages that call C code." "If the import of "C" is immediately preceded by a comment, that comment, called the preamble, is used as a header when compiling the C parts of the package." The numeric types are C.char, C.schar, C.uchar, C.short, C.ushort, C.int, C.uint, C.long, C.ulong, C.longlong, C.ulonglong, C.float, C.double (and C.complexfloat, C.complexdouble); "The C type void* is represented by Go's unsafe.Pointer." "The cgo tool is enabled by default for native builds on systems where it is expected to work. It is disabled by default when cross-compiling." "When cross-compiling, you must specify a C cross-compiler for cgo to use ... or you can set the CC environment variable any time you run the go tool." "Go code may pass a Go pointer to C provided the memory to which it points does not contain any Go pointers to memory that is unpinned." "C code may not keep a copy of a Go pointer after the call returns, unless the memory it points to is pinned with runtime.Pinner". The checks are "controlled by the cgocheck setting of the GODEBUG environment variable. The default setting is GODEBUG=cgocheck=1".
  • unsafe documentation: Pointer has four special operations (any pointer to Pointer, Pointer to any pointer, uintptr to Pointer, Pointer to uintptr). "Pointer therefore allows a program to defeat the type system and read and write arbitrary memory. It should be used with extreme care." Six valid patterns follow; "Code not using these patterns is likely to be invalid today or to become invalid in the future." "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." For unsafe.String: "the bytes passed to String must not be modified as long as the returned string value exists." For unsafe.StringData: "the bytes returned by StringData must not be modified."
  • Go 1.17 release notes: added unsafe.Add and unsafe.Slice. Go 1.20 release notes: "The unsafe package defines three new functions SliceData, String, and StringData."
  • Go 1.23 release notes (Linker): "The linker now disallows using a //go:linkname directive to refer to internal symbols in the standard library (including the runtime) that are not marked with //go:linkname on their definitions." "For backward compatibility, existing usages of //go:linkname found in a large open-source code corpus remain supported. Any new references to standard library internal symbols will be disallowed." "A linker command line flag -checklinkname=0 can be used to disable this check, for debugging and experimenting purposes."

The problem: reuse a C library

A C library is code written in the C programming language, packed so other programs can use it. C is much older than Go and still runs a huge amount of software: databases, image and video codecs, compression, cryptography, device drivers. Raju's billing engine is one of these. The obvious attempt: put the C file next to the Go file and call it.

The obvious attempt fails (NOCGO)

// $ go run .
// ---- main.go ----
package main

import "fmt"

func main() {
    prices := []int{4999, 12050, 899} // in paise
    fmt.Println("total:", billTotal(prices)) // the C engine, in bill.c
}

// ---- bill.c ----
long bill_total(const int *paise, int n) {
    long sum = 0;
    for (int i = 0; i < n; i++) sum += paise[i];
    return sum + (sum * 18 + 50) / 100; /* plus 18% GST, rounded */
}

Output:

$ go run .

Error stream:

package shop: C source files not allowed when not using cgo or SWIG: bill.c

Why it fails: the Go compiler only compiles Go. A .c file in a Go package is refused unless the package uses cgo (or SWIG, an older tool that generates bindings between C/C++ and other languages).

cgo: the bridge to C

cgo is a tool built into the go command. When a Go file contains import "C", the go command runs cgo, which generates Go and C glue code, compiles the C parts with a C compiler (normally gcc, the GNU C compiler, or clang) and links everything into one binary.

  • Preamble: the comment written immediately above import "C" (no blank line in between). It is C code: #include lines that pull in C header files, declarations, or even whole C functions.
  • Header file (.h): a C file that lists functions and types so other files can use them, like a table of contents. bill.h lists gst.
  • Pseudo-package C: there is no real package named C; C.gst, C.int, C.free are cgo's names for things in C.
  • #cgo lines in the preamble set compiler and linker flags, e.g. #cgo LDFLAGS: -lm to link the C maths library.

Passing a Go value straight to C fails (TYPES)

// $ go run .
// ---- main.go ----
package main

/*
#include "bill.h"
*/
import "C"
import "fmt"

func main() {
    items := 3
    fmt.Println("items with GST:", C.gst(items))
}

// ---- bill.h ----
int gst(int paise);

// ---- bill.c ----
#include "bill.h"
int gst(int paise) { return paise + (paise * 18 + 50) / 100; }

Output:

$ go run .

Error stream:

# shop
./main.go:11:42: cannot use items (variable of type int) as _Ctype_int value in argument to (_Cfunc_gst)

Why: a Go int is 64 bits on this machine, while a C int is usually 32 bits. Go never converts types silently, not even across the bridge.

The fix: convert both ways (CALL)

// $ go run .
// ---- main.go ----
package main

/*
#include "bill.h"
*/
import "C"
import "fmt"

func main() {
    prices := []int{4999, 12050, 899} // in paise
    total := 0
    for _, p := range prices {
        total += int(C.gst(C.int(p))) // Go int → C int → C function → back to Go int
    }
    fmt.Println("total with GST (paise):", total)
}

// ---- bill.h ----
int gst(int paise); /* adds 18% GST, rounded */

// ---- bill.c ----
#include "bill.h"
int gst(int paise) { return paise + (paise * 18 + 50) / 100; }

Output:

$ go run .
total with GST (paise): 21179

C.int(p) converts the Go value to the C type; int(...) brings the result back. 4999 → 5899, 12050 → 14219, 899 → 1061: 21,179 paise in total, computed by the C code with its own rounding rule.

C type names

C type Go name with cgo Typical size here
char C.char 1 byte
int C.int 4 bytes
unsigned int C.uint 4 bytes
long C.long 8 bytes on linux/amd64
long long C.longlong 8 bytes
double C.double 8 bytes
size_t C.size_t 8 bytes
void * (a pointer to anything) unsafe.Pointer 8 bytes

C's sizes depend on the platform, which is one more reason cgo makes you convert explicitly.

C strings and C.free

A C string is a run of bytes in memory that ends with a zero byte ('\0'); C finds the end by looking for it. A Go string is a pointer plus a length and has no zero byte at the end. So they are not interchangeable.

A Go string can't go to C (STR)

// $ go run .
// ---- main.go ----
package main

/*
#include "bill.h"
*/
import "C"
import "fmt"

func main() {
    invoice := "INV-2026-0042"
    fmt.Println("check digit:", C.check_digit(invoice))
}

// ---- bill.h ----
int check_digit(const char *s); /* C string: bytes ending in a 0 byte */

// ---- bill.c ----
#include "bill.h"
int check_digit(const char *s) {
    int sum = 0;
    for (; *s; s++) sum = (sum * 31 + *s) % 97;
    return sum;
}

Output:

$ go run .

Error stream:

# shop
./main.go:11:47: cannot use invoice (variable of type string) as *_Ctype_char value in argument to (_Cfunc_check_digit)

C.CString, C.GoString and C.free (STR2)

// $ go run .
// ---- main.go ----
package main

/*
#include <stdlib.h>
#include <string.h>
#include "bill.h"
*/
import "C"
import (
    "fmt"
    "unsafe"
)

func checkDigit(invoice string) int {
    cs := C.CString(invoice)           // copies the bytes into C memory (malloc) + a 0 byte
    defer C.free(unsafe.Pointer(cs))   // C memory: Go's garbage collector never frees it
    return int(C.check_digit(cs))
}

func main() {
    fmt.Println("check digit:", checkDigit("INV-2026-0042"))
    cs := C.CString("hello")
    defer C.free(unsafe.Pointer(cs))
    fmt.Println("back to Go:", C.GoString(cs), "| C length:", C.strlen(cs))
}

// ---- bill.h ----
int check_digit(const char *s); /* C string: bytes ending in a 0 byte */

// ---- bill.c ----
#include "bill.h"
int check_digit(const char *s) {
    int sum = 0;
    for (; *s; s++) sum = (sum * 31 + *s) % 97;
    return sum;
}

Output:

$ go run .
check digit: 86
back to Go: hello | C length: 5
  • C.CString(s) copies the bytes of s into new C memory, adds the zero byte, and returns *C.char. That memory comes from malloc, C's function for asking the operating system for memory.
  • The Go garbage collector (the part of the Go runtime that frees memory nobody uses any more) does not know about malloc'd memory, so you must call C.free(unsafe.Pointer(cs)) yourself. defer right after allocating is the idiom.
  • C.GoString(cs) copies a C string back into a Go string; C.GoStringN(p, n) copies n bytes; C.GoBytes(p, n) copies into a []byte.

Forgetting C.free: a memory leak (LEAK)

// $ go run . leak
// $ go run . free
// ---- main.go ----
package main

/*
#include <stdlib.h>
*/
import "C"
import (
    "fmt"
    "os"
    "strings"
    "unsafe"
)

func rss() string { // resident memory of this process, from Linux
    b, _ := os.ReadFile("/proc/self/status")
    for _, l := range strings.Split(string(b), "\n") {
        if strings.HasPrefix(l, "VmRSS:") {
            return strings.Join(strings.Fields(l)[1:], " ")
        }
    }
    return "?"
}

func main() {
    invoice := strings.Repeat("x", 1000) // a 1 KB invoice line
    for i := 0; i < 100_000; i++ {
        cs := C.CString(invoice)
        if os.Args[1] == "free" {
            C.free(unsafe.Pointer(cs))
        }
    }
    fmt.Println(os.Args[1], "after 100,000 calls, memory in use:", rss())
}

Output:

$ go run . leak
leak after 100,000 calls, memory in use: 103844 kB
$ go run . free
free after 100,000 calls, memory in use: 3792 kB

A memory leak is memory a program takes and never gives back. There is no error and no warning: memory use just grows. Here 100,000 calls with a 1 KB string left about 100 MB behind (VmRSS, the memory the process really holds in RAM, read from /proc/self/status).

Who owns the memory?

  • C memory (malloc, C.CString, C.malloc): C owns it, Go's garbage collector never frees it. Free it with C.free, once.
  • Go memory passed to C: Go still owns it. C may use it during the call only.
  • A Go pointer is a pointer to memory allocated by Go. Slices, strings, maps, channels and many structs hold Go pointers inside them.

C must not keep Go pointers (GPTR)

// $ go run .
// ---- main.go ----
package main

/*
#include "bill.h"
*/
import "C"
import (
    "fmt"
    "unsafe"
)

type Cart struct {
    Prices []C.int // a slice: its header holds a Go pointer
}

func main() {
    prices := []C.int{4999, 12050, 899}
    // OK: a pointer to Go memory that holds no Go pointers
    fmt.Println("sum:", C.sum(&prices[0], C.int(len(prices))))

    cart := &Cart{Prices: prices}
    // NOT OK: the Cart holds a Go pointer (the slice's array)
    C.keep(unsafe.Pointer(cart))
}

// ---- bill.h ----
long sum(const int *p, int n);
void keep(void *p);

// ---- bill.c ----
#include "bill.h"
static void *saved; /* C keeps the pointer: forbidden for Go memory */
long sum(const int *p, int n) { long s = 0; for (int i = 0; i < n; i++) s += p[i]; return s; }
void keep(void *p) { saved = p; }

Output:

$ go run .
sum: 17948

Error stream:

panic: runtime error: cgo argument has Go pointer to unpinned Go pointer

goroutine 1 [running]:
main.main.func1(...)
    main.go:23
main.main()
    main.go:23 +0x10e
exit status 2

&prices[0] points at plain numbers: allowed. cart holds a slice whose header contains a Go pointer to its backing array: passing that is refused at run time by cgocheck, the runtime's pointer checker, with panic: runtime error: cgo argument has Go pointer to unpinned Go pointer. And keep stores the pointer in a C static variable, which would break the second rule even for allowed memory.

The rules (cgo docs):

  1. Go may pass a Go pointer to C if the memory it points to holds no Go pointers to unpinned memory.
  2. C may not keep a copy of a Go pointer after the call returns, unless the memory is pinned with runtime.Pinner.
  3. runtime.Pinner (Go 1.21+): var p runtime.Pinner; p.Pin(ptr) promises Go won't move or free that object until p.Unpin().
  4. GODEBUG=cgocheck=1 (the default) checks at run time; cgocheck=0 turns the checks off, which only hides bugs. A complete (slower) check is available with GOEXPERIMENT=cgocheck2 at build time.

If C must keep data, copy it into C memory (C.malloc + copy, or C.CString) and let C free it.

What a cgo call costs

Every call from Go into C has to switch from Go's world (small, growable goroutine stacks and Go's scheduler) to C's world (a normal thread stack) and back. That fixed cost is paid per call, like a translator who charges per sentence. A benchmark is a test function that times code (episode 42); ns/op is nanoseconds per operation (1 ns = one billionth of a second). The loops use b.Loop(), which the Go 1.24 release notes describe as "the faster and less error-prone" way to write benchmark loops; it also keeps the compiler from optimizing the measured call away.

Measured (BENCH)

// $ go test -bench=.
// ---- bill.go ----
package shop

/*
int gst(int paise) { return paise + (paise * 18 + 50) / 100; }
long total(const int *p, int n) {
    long s = 0;
    for (int i = 0; i < n; i++) s += gst(p[i]);
    return s;
}
*/
import "C"

func GstGo(p int) int { return p + (p*18+50)/100 }    // the maths in Go
func GstC(p int) int  { return int(C.gst(C.int(p))) } // one trip into C per item
func TotalC(p []int32) int { // one trip into C for the whole cart
    return int(C.total((*C.int)(&p[0]), C.int(len(p))))
}
// ---- bill_test.go ----
package shop

import "testing"

func BenchmarkGo(b *testing.B) {
    for b.Loop() {
        GstGo(4999)
    }
}
func BenchmarkC(b *testing.B) {
    for b.Loop() {
        GstC(4999)
    }
}
func BenchmarkCart1000(b *testing.B) {
    cart := make([]int32, 1000)
    for b.Loop() {
        TotalC(cart)
    }
}

Output:

$ go test -bench=.
goos: linux
goarch: amd64
pkg: shop
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkGo-2           812546310            1.600 ns/op
BenchmarkC-2            20835694            61.99 ns/op
BenchmarkCart1000-2      1000000          1191 ns/op
PASS
ok      shop    3.789s

Note the first try in the video's preparation: putting import "C" in the test file fails with the real error use of cgo in test bill_test.go not supported, so the C code lives in bill.go and the test only calls Go functions.

Benchmark What crosses into C Time per op (this run)
BenchmarkGo nothing (pure Go) about 1.2-2.5 ns (7.6 ns in the video's recording, on a busy machine)
BenchmarkC one call per item about 60 ns (178 ns in the video's recording, on a busy machine)
BenchmarkCart1000 one call for 1,000 items about 1,100-1,900 ns ≈ 1-2 ns per item (1,855 ns in the video's recording)

Lesson: crossing is expensive, work in C is not. Make few, large calls (batching).

cgo and cross-compiling

Cross-compiling means building a binary for a different operating system or processor than the one you build on (episode 73: GOOS=windows GOARCH=arm64 go build).

What happens with cgo (CROSS)

// $ go build -o shop .
// $ GOOS=windows go build -o shop.exe .
// $ GOOS=windows CGO_ENABLED=1 go build -o shop.exe .
// ---- main.go ----
package main

/*
int gst(int paise) { return paise + (paise * 18 + 50) / 100; }
*/
import "C"
import "fmt"

func main() { fmt.Println("with GST:", C.gst(4999)) }

Output:

$ go build -o shop .
$ GOOS=windows go build -o shop.exe .
$ GOOS=windows CGO_ENABLED=1 go build -o shop.exe .

Error stream:

package shop: build constraints exclude all Go files in .
# runtime/cgo
gcc: error: unrecognized command-line option ‘-mthreads’; did you mean ‘-pthread’?
  • With GOOS=windows, cgo is off by default (docs: "disabled by default when cross-compiling"). Files with import "C" get the implicit build constraint cgo, so they are skipped, and here nothing is left: build constraints exclude all Go files in ..
  • Forcing CGO_ENABLED=1 makes the go command call the Linux gcc with Windows flags: gcc: error: unrecognized command-line option '-mthreads'.
  • The fix is a C cross-compiler, a C compiler that produces code for the target: CGO_ENABLED=1 GOOS=windows CC=<a Windows-targeting C compiler> go build. Or avoid cgo and keep CGO_ENABLED=0.
  • A cgo binary is usually dynamically linked (it loads the C library when it starts), so it fails in a scratch container image with exec /shop: no such file or directory (episode 73).

unsafe: Go without guard rails

The unsafe package contains operations that step around Go's type safety. Type safety means the compiler stops you from using a value as a type it isn't, for example reading a float64 as an int64, or reading past the end of an array. unsafe switches those checks off for a few operations; it is called unsafe because mistakes can crash the program or silently corrupt memory, and it is not covered by the Go 1 compatibility promise.

unsafe.Slice over C memory (CSLICE)

// $ go run .
// ---- main.go ----
package main

/*
#include <stdlib.h>
long *week_totals(int *n) { // C allocates 7 numbers with malloc
    long *t = malloc(7 * sizeof(long));
    for (int i = 0; i < 7; i++) t[i] = 1000L * (i + 1);
    *n = 7;
    return t;
}
*/
import "C"
import (
    "fmt"
    "unsafe"
)

func main() {
    var n C.int
    p := C.week_totals(&n)            // *C.long: a pointer to C memory
    defer C.free(unsafe.Pointer(p))   // C allocated it, so C frees it

    days := unsafe.Slice(p, int(n))   // a Go slice view of the C array, no copy
    fmt.Println(len(days), days)

    kept := make([]int64, n)          // copy out before free, if Go keeps it
    for i, v := range days {
        kept[i] = int64(v)
    }
    fmt.Println("copied to Go memory:", kept)
}

Output:

$ go run .
7 [1000 2000 3000 4000 5000 6000 7000]
copied to Go memory: [1000 2000 3000 4000 5000 6000 7000]

unsafe.Slice(ptr, n) (Go 1.17) returns a slice whose backing array starts at ptr, with length and capacity n. No copy is made: days is C's memory. Once C.free runs, days points at freed memory, so copy the values into Go memory (kept) if you need them later.

unsafe.String: zero copies, and the danger (ZEROCOPY)

// $ go run .
// ---- main.go ----
package main

import (
    "fmt"
    "testing"
    "unsafe"
)

var sink string // keeps results alive, so Go really has to store them

func main() {
    line := []byte("order 42: paid") // bytes read from the network

    copied := string(line)                                  // safe: copies the bytes
    shared := unsafe.String(unsafe.SliceData(line), len(line)) // no copy: same bytes

    fmt.Println("allocations, string(b):     ", testing.AllocsPerRun(1000, func() { sink = string(line) }))
    fmt.Println("allocations, unsafe.String: ", testing.AllocsPerRun(1000, func() {
        sink = unsafe.String(unsafe.SliceData(line), len(line))
    }))

    copy(line[10:], "FAIL") // later, the buffer is reused for the next message
    fmt.Println("copied:", copied)
    fmt.Println("shared:", shared, " <- a Go string changed!")
}

Output:

$ go run .
allocations, string(b):      1
allocations, unsafe.String:  0
copied: order 42: paid
shared: order 42: FAIL  <- a Go string changed!
  • string(line) copies the bytes: 1 allocation (testing.AllocsPerRun counts heap allocations per call; storing to sink, a package-level variable, makes sure the compiler really keeps the result).
  • unsafe.String(unsafe.SliceData(line), len(line)) (Go 1.20) builds a string on the same bytes: 0 allocations.
  • But Go strings are immutable (they never change), and code everywhere relies on it: map keys, caches, other goroutines. When the buffer is reused, the "immutable" string changes from paid to FAIL. The docs: the bytes "must not be modified as long as the returned string value exists."

unsafe.StringData: read-only bytes (RODATA)

// $ go run .
// ---- main.go ----
package main

import (
    "fmt"
    "unsafe"
)

func main() {
    s := "chai"
    p := unsafe.StringData(s)        // *byte: the first byte of the string
    b := unsafe.Slice(p, len(s))     // view those bytes as a []byte, no copy
    fmt.Println(string(b[0]), len(b), cap(b))
    b[0] = 'C' // strings are immutable: this memory is read-only
    fmt.Println(s)
}

Output:

$ go run .
c 4 4

Error stream:

unexpected fault address 0x4b3c6f
fatal error: fault
[signal SIGSEGV: segmentation violation code=0x2 addr=0x4b3c6f pc=0x491d96]

goroutine 1 gp=0xc000002380 m=0 mp=0x55f4c0 [running]:
runtime.throw({0x4b3e1c?, 0x48cd68?})
    /usr/local/go1.24.7/src/runtime/panic.go:1101 +0x48 fp=0xc00010ce78 sp=0xc00010ce48 pc=0x467b08
runtime.sigpanic()
    /usr/local/go1.24.7/src/runtime/signal_unix.go:939 +0x26c fp=0xc00010ced8 sp=0xc00010ce78 pc=0x468eac
main.main()
    main.go:13 +0xb6 fp=0xc00010cf50 sp=0xc00010ced8 pc=0x491d96
runtime.main()
    /usr/local/go1.24.7/src/runtime/proc.go:283 +0x28b fp=0xc00010cfe0 sp=0xc00010cf50 pc=0x43928b
runtime.goexit({})
    /usr/local/go1.24.7/src/runtime/asm_amd64.s:1700 +0x1 fp=0xc00010cfe8 sp=0xc00010cfe0 pc=0x46ddc1

... (other goroutines trimmed)
exit status 2

unsafe.StringData(s) returns a *byte to the first byte of a string. A string literal like "chai" is stored in read-only memory (memory the operating system won't let the program write to), so writing through it crashes with a segmentation fault (SIGSEGV: the program touched memory it isn't allowed to). This is a fatal error, not a panic: recover cannot catch it and the whole program stops. (The goroutine list after the first lines is trimmed here.)

unsafe.Pointer rules

unsafe.Pointer is a pointer to anything. uintptr is an unsigned integer type big enough to hold a memory address. The four special operations: any *T → unsafe.Pointer, unsafe.Pointer → any *T, uintptr → unsafe.Pointer, unsafe.Pointer → uintptr.

The six valid patterns from the docs:

# Pattern Example
1 *T1 → Pointer → *T2, when T2 is no larger than T1 and they share a memory layout *(*uint64)(unsafe.Pointer(&f)) (this is how math.Float64bits works)
2 Pointer → uintptr, but not back; only to print or compare the address fmt.Printf("%#x", uintptr(p))
3 Pointer → uintptr → arithmetic → Pointer, in one expression unsafe.Pointer(uintptr(p) + off), or better unsafe.Add(p, off)
4 Pointer → uintptr in the argument list of syscall.Syscall syscall.Syscall(SYS_READ, fd, uintptr(unsafe.Pointer(&buf[0])), n)
5 the result of reflect.Value.Pointer / UnsafeAddr converted immediately (*int)(unsafe.Pointer(v.Pointer()))
6 reflect.SliceHeader / StringHeader Data fields (old code; use unsafe.Slice/String now)

Rules 1 and 3, and catching a broken rule (RULES)

// $ go run .
// $ go vet .
// ---- main.go ----
package main

import (
    "fmt"
    "math"
    "unsafe"
)

type Order struct {
    ID    int32
    Paise int64
}

func main() {
    // Rule 1: *T1 → Pointer → *T2 (same size, compatible layout)
    f := 49.99
    bits := *(*uint64)(unsafe.Pointer(&f))
    fmt.Printf("bits %x, same as math.Float64bits: %v\n", bits, bits == math.Float64bits(f))

    // Rule 3: Pointer → uintptr → arithmetic → Pointer, all in ONE expression
    o := Order{ID: 42, Paise: 4999}
    pp := (*int64)(unsafe.Pointer(uintptr(unsafe.Pointer(&o)) + unsafe.Offsetof(o.Paise)))
    fmt.Println("paise:", *pp, " offset:", unsafe.Offsetof(o.Paise), " size:", unsafe.Sizeof(o))

    // WRONG: the address is kept in a uintptr variable, then turned back into a Pointer
    addr := uintptr(unsafe.Pointer(&o))
    bad := (*int64)(unsafe.Pointer(addr + 8))
    fmt.Println("bad:", *bad)
}

Output:

$ go run .
bits 4048feb851eb851f, same as math.Float64bits: true
paise: 4999  offset: 8  size: 16
bad: 4999
$ go vet .

Error stream:

# shop
# [shop]
./main.go:27:21: possible misuse of unsafe.Pointer

The same program built with checkptr:

// $ go run -gcflags=all=-d=checkptr .
// ---- main.go ----
package main

import (
    "fmt"
    "math"
    "unsafe"
)

type Order struct {
    ID    int32
    Paise int64
}

func main() {
    // Rule 1: *T1 → Pointer → *T2 (same size, compatible layout)
    f := 49.99
    bits := *(*uint64)(unsafe.Pointer(&f))
    fmt.Printf("bits %x, same as math.Float64bits: %v\n", bits, bits == math.Float64bits(f))

    // Rule 3: Pointer → uintptr → arithmetic → Pointer, all in ONE expression
    o := Order{ID: 42, Paise: 4999}
    pp := (*int64)(unsafe.Pointer(uintptr(unsafe.Pointer(&o)) + unsafe.Offsetof(o.Paise)))
    fmt.Println("paise:", *pp, " offset:", unsafe.Offsetof(o.Paise), " size:", unsafe.Sizeof(o))

    // WRONG: the address is kept in a uintptr variable, then turned back into a Pointer
    addr := uintptr(unsafe.Pointer(&o))
    bad := (*int64)(unsafe.Pointer(addr + 8))
    fmt.Println("bad:", *bad)
}

Output:

$ go run -gcflags=all=-d=checkptr .
bits 4048feb851eb851f, same as math.Float64bits: true
paise: 4999  offset: 8  size: 16

Error stream:

fatal error: checkptr: pointer arithmetic result points to invalid allocation

goroutine 1 gp=0xc000002380 m=0 mp=0x5694e0 [running]:
runtime.throw({0x4c4462?, 0x21?})
    /usr/local/go1.24.7/src/runtime/panic.go:1101 +0x48 fp=0xc00010ce00 sp=0xc00010cdd0 pc=0x468508
runtime.checkptrArithmetic(0x4e1ac8?, {0x0, 0x0, 0x6?})
    /usr/local/go1.24.7/src/runtime/checkptr.go:69 +0x9c fp=0xc00010ce30 sp=0xc00010ce00 pc=0x40c3fc
main.main()
    main.go:27 +0x25a fp=0xc00010cf50 sp=0xc00010ce30 pc=0x4966da
runtime.main()
    /usr/local/go1.24.7/src/runtime/proc.go:283 +0x28b fp=0xc00010cfe0 sp=0xc00010cf50 pc=0x439b6b
runtime.goexit({})
    /usr/local/go1.24.7/src/runtime/asm_amd64.s:1700 +0x1 fp=0xc00010cfe8 sp=0xc00010cfe0 pc=0x46e7c1

... (other goroutines trimmed)
exit status 2
  • unsafe.Offsetof(o.Paise): the distance in bytes from the start of the struct to that field (8 here: ID is 4 bytes, then 4 bytes of padding so the int64 starts on an 8-byte boundary). unsafe.Sizeof(o): the struct's size, 16.
  • The broken part keeps the address in a uintptr variable. A uintptr is just a number: the garbage collector doesn't treat it as a pointer, and Go can move a goroutine's stack (stacks grow by being copied, episode 10), so the number can go stale. Plain go run prints bad: 4999 — it works today, by luck.
  • go vet reports possible misuse of unsafe.Pointer. Building with -gcflags=all=-d=checkptr adds run-time checks of unsafe conversions (the race detector -race turns them on too): fatal error: checkptr: pointer arithmetic result points to invalid allocation.

//go:linkname

A compiler directive is a special //go: comment that gives instructions to the compiler or linker. //go:linkname local target tells the linker (the tool that joins compiled packages into one binary) to connect the local, body-less function local to the symbol target in another package, even a private one. It needs import _ "unsafe".

// $ go run .
// $ go run -ldflags=-checklinkname=0 .
// ---- main.go ----
package main

import (
    "fmt"
    "runtime"
    _ "unsafe" // //go:linkname needs the unsafe import
)

//go:linkname gcount runtime.gcount
func gcount() int32 // no body: the linker points it at the runtime's private gcount

func main() {
    fmt.Println("private runtime.gcount:", gcount())
    fmt.Println("public runtime.NumGoroutine:", runtime.NumGoroutine())
}

Output:

$ go run .
$ go run -ldflags=-checklinkname=0 .
private runtime.gcount: 1
public runtime.NumGoroutine: 1

Error stream:

# shop
link: main: invalid reference to runtime.gcount

The linker refuses the reference to the runtime's private gcount; -ldflags=-checklinkname=0 turns the check off (the release notes: "for debugging and experimenting purposes"). The public runtime.NumGoroutine gives the same answer, and it's the one to use. Why the restriction: private functions can change or disappear in any release, so code linked to them breaks without warning, and every such use made it harder to change Go itself. Existing uses found in a large open-source corpus still work; new ones are refused.

When to avoid cgo

Cost Why it matters
Per-call overhead dozens of times a plain Go call per crossing (measured above: about 60 ns quiet, 80-180 ns while recording)
Builds need a C compiler; slower; C warnings and errors to deal with
Cross-compiling needs a C cross-compiler for every target
Deployment dynamically linked binaries; scratch images fail
Crashes a bug in C (a bad pointer, a double free) crashes the whole process; Go's bounds checks, race detector and garbage collector don't protect C code

Alternatives, in order: a pure Go package that does the same job; running the C program as a separate process with os/exec; and if you do use cgo, few large calls, free everything C allocates, and keep all of it inside one small package with a pure Go API.

cgo and unsafe in one page

  • C code goes in the preamble directly above import "C"; call it as C.name.
  • Convert values both ways: C.int(x), int(r).
  • C.CString allocates C memory → defer C.free(unsafe.Pointer(cs)); C.GoString copies back.
  • C never keeps Go pointers; never pass memory that contains Go pointers; runtime.Pinner if C must hold one.
  • Each crossing costs dozens × a Go call → batch.
  • Cross-compiling with cgo needs CC set to a C cross-compiler and CGO_ENABLED=1.
  • unsafe.Slice, unsafe.String, unsafe.StringData, unsafe.SliceData build views without copying; never modify bytes behind a string.
  • Use only the six unsafe.Pointer patterns; run go vet and -d=checkptr.
  • No new //go:linkname to standard library internals (Go 1.23+).

Mini project: a GST bridge

Build a package gstc that wraps the C billing code:

  1. A Go API: Total([]int) int (one C call per cart) and CheckDigit(string) int. No C types leave the package.
  2. Every C.CString is freed.
  3. Benchmarks: one C call per item vs one batched call vs pure Go.
  4. A pure Go version and a test that both give the same answers.
  5. go vet clean, tests passing with -gcflags=all=-d=checkptr.
Solution (built and run for real)
// $ go vet ./...
// $ go test -gcflags=all=-d=checkptr ./...
// $ go test -bench=. -benchtime=200000x ./gstc
// ---- gstc/gstc.go ----
// Package gstc wraps the C billing engine. No C types leave this package.
package gstc

/*
#include <stdlib.h>
static int gst(int paise) { return paise + (paise * 18 + 50) / 100; }
static long total(const int *p, int n) {
    long s = 0;
    for (int i = 0; i < n; i++) s += gst(p[i]);
    return s;
}
static int check_digit(const char *s) {
    int sum = 0;
    for (; *s; s++) sum = (sum * 31 + *s) % 97;
    return sum;
}
*/
import "C"
import "unsafe"

// Total returns the cart total with GST, in paise, using one C call.
func Total(paise []int) int {
    if len(paise) == 0 {
        return 0
    }
    cs := make([]C.int, len(paise)) // plain numbers: allowed to pass to C
    for i, p := range paise {
        cs[i] = C.int(p)
    }
    return int(C.total(&cs[0], C.int(len(cs))))
}

// TotalPerItem makes one C call per item (for the benchmark).
func TotalPerItem(paise []int) int {
    s := 0
    for _, p := range paise {
        s += int(C.gst(C.int(p)))
    }
    return s
}

// CheckDigit returns the invoice check digit.
func CheckDigit(invoice string) int {
    cs := C.CString(invoice)
    defer C.free(unsafe.Pointer(cs))
    return int(C.check_digit(cs))
}

// ---- gstc/pure.go ----
package gstc

// TotalGo is the same rule in pure Go.
func TotalGo(paise []int) int {
    s := 0
    for _, p := range paise {
        s += p + (p*18+50)/100
    }
    return s
}

// CheckDigitGo is the same check digit in pure Go (C's char is signed; ASCII input).
func CheckDigitGo(invoice string) int {
    sum := 0
    for i := 0; i < len(invoice); i++ {
        sum = (sum*31 + int(invoice[i])) % 97
    }
    return sum
}

// ---- gstc/gstc_test.go ----
package gstc

import "testing"

func TestSameAnswers(t *testing.T) {
    carts := [][]int{nil, {4999}, {4999, 12050, 899}, {1, 2, 3, 99999}}
    for _, c := range carts {
        if a, b := Total(c), TotalGo(c); a != b {
            t.Errorf("Total(%v) = %d, TotalGo = %d", c, a, b)
        }
    }
    for _, s := range []string{"", "INV-2026-0042", "A"} {
        if a, b := CheckDigit(s), CheckDigitGo(s); a != b {
            t.Errorf("CheckDigit(%q) = %d, Go = %d", s, a, b)
        }
    }
}

var cart = make([]int, 100)

func BenchmarkPerItem(b *testing.B) {
    for i := 0; i < b.N; i++ {
        TotalPerItem(cart)
    }
}

func BenchmarkBatched(b *testing.B) {
    for i := 0; i < b.N; i++ {
        Total(cart)
    }
}

func BenchmarkPureGo(b *testing.B) {
    for i := 0; i < b.N; i++ {
        TotalGo(cart)
    }
}

Output:

$ go vet ./...
$ go test -gcflags=all=-d=checkptr ./...
ok      shop/gstc   0.003s
$ go test -bench=. -benchtime=200000x ./gstc
goos: linux
goarch: amd64
pkg: shop/gstc
cpu: Intel(R) Xeon(R) Processor @ 2.10GHz
BenchmarkPerItem-2        200000          6160 ns/op
BenchmarkBatched-2        200000           330.6 ns/op
BenchmarkPureGo-2         200000            37.87 ns/op
PASS
ok      shop/gstc   1.317s

The per-item version pays the crossing 100 times per cart; the batched version pays it once; pure Go pays nothing. That's the honest comparison to show your team before choosing cgo.

Common mistakes (and the real messages)

Mistake Real message Why Fix
bill.c in the folder, no import "C" C source files not allowed when not using cgo or SWIG: bill.c go only compiles Go preamble + import "C"
Passing a Go int to C cannot use items (variable of type int) as _Ctype_int value in argument to (_Cfunc_gst) no implicit conversions C.int(items)
Passing a Go string to C cannot use invoice (variable of type string) as *_Ctype_char value in argument to (_Cfunc_check_digit) a Go string is not a C string C.CString + C.free
Calling a C library function not in the preamble could not determine what C.strlen refers to strlen is declared in string.h #include <string.h>
Forgetting C.free no message: leak after 100,000 calls, memory in use: 103876 kB the GC doesn't see C memory defer C.free(unsafe.Pointer(cs))
Passing a struct that holds Go pointers panic: runtime error: cgo argument has Go pointer to unpinned Go pointer pointer rules pass plain data, or copy into C memory
import "C" in a _test.go file use of cgo in test bill_test.go not supported cgo isn't allowed in test files put the C code in a normal file
Cross-compiling a cgo-only package build constraints exclude all Go files in . cgo is off when cross-compiling CGO_ENABLED=1 + CC= cross-compiler, or pure Go
Forcing cgo with the native gcc gcc: error: unrecognized command-line option '-mthreads'; did you mean '-pthread'? gcc targets Linux only a C cross-compiler
Writing through unsafe.StringData unexpected fault address ... fatal error: fault [signal SIGSEGV ...] read-only memory copy to a []byte first
Keeping an address in a uintptr variable possible misuse of unsafe.Pointer; with checkptr fatal error: checkptr: pointer arithmetic result points to invalid allocation breaks pattern 3 one expression, or unsafe.Add
//go:linkname to a runtime internal link: main: invalid reference to runtime.gcount Go 1.23 restriction the public API (runtime.NumGoroutine)

Practice

  1. Wrap C's sqrt from math.h. What #cgo line do you need, and which C type does it take?
  2. Write func ToUpperC(s string) string that calls a C function writing into a buffer you allocate with C.malloc. Who frees what?
  3. Why can't you pass a []string to C even for one call?
  4. Change the BENCH program so the cart has 10 items. Roughly what time per op do you expect for TotalC?
  5. A teammate converts every incoming []byte to a string with unsafe.String for speed. What question should you ask before approving?
  6. Rewrite the broken part of RULES with unsafe.Add so go vet and checkptr are happy.
Solutions

1. Add #cgo LDFLAGS: -lm and #include <math.h> to the preamble; C.sqrt takes a C.double: float64(C.sqrt(C.double(x))).

2.

/*
#include <stdlib.h>
#include <ctype.h>
static void upper(const char *in, char *out) {
    for (; *in; in++, out++) *out = toupper((unsigned char)*in);
    *out = 0;
}
*/
import "C"
import "unsafe"

func ToUpperC(s string) string {
    in := C.CString(s)
    defer C.free(unsafe.Pointer(in))
    out := (*C.char)(C.malloc(C.size_t(len(s) + 1)))
    defer C.free(unsafe.Pointer(out))
    C.upper(in, out)
    return C.GoString(out) // copies into Go memory before the frees run
}

Go allocated nothing C needs to keep; both C buffers are freed by Go with C.free because Go asked for them.

3. A []string is an array of string headers, and each header holds a Go pointer to the string's bytes. That memory contains Go pointers, so the first rule forbids passing it. Convert each string with C.CString into a C array of *C.char allocated with C.malloc.

4. About one crossing (around 60 ns on the episode's machine) plus about 1 ns per item: roughly 70 ns. The crossing dominates; measure it with go test -bench.

5. "Can these bytes ever change while the string is alive?" If the buffer is reused (bufio, network reads, pools), the string will change under you, as ZEROCOPY showed. Only use it when the bytes are never written again, and measure that the copy really matters.

6.

bad := (*int64)(unsafe.Add(unsafe.Pointer(&o), unsafe.Offsetof(o.Paise)))

unsafe.Add keeps the value an unsafe.Pointer the whole time, so the garbage collector always sees it as a pointer.

Quick quiz

1. What's wrong with this?

// #include "label.h"
import "C"

func printLabel(name string) {
    cs := C.CString(name)
    C.print_label(cs)
}
// called for every order: 1 lakh orders a day
Answer

A memory leak: C.CString allocates C memory with malloc and nothing frees it. Add defer C.free(unsafe.Pointer(cs)) (and include stdlib.h and import unsafe).

2. There's a blank line between the preamble comment and import "C". What happens?

Answer

The comment is no longer the preamble, so cgo doesn't see the C code, and calls like C.gst fail with could not determine what C.gst refers to.

3. True or false: if go vet prints nothing, my unsafe code is correct.

Answer

False. The unsafe docs: "silence from "go vet" is not a guarantee that the code is valid." Also run with -gcflags=all=-d=checkptr (or -race) and follow the six patterns.

4. Which is cheaper: 1,000 cgo calls with one item each, or one cgo call with 1,000 items?

Answer

One call with 1,000 items. Each crossing costs dozens of times a Go call; in the episode's runs, 1,000 items in one call took about the time of 20 single calls.

Interview questions

  1. What is cgo and what does it cost? A tool in the go command that lets Go call C (and C call exported Go functions). Costs: dozens × a Go call per call, a C toolchain for builds, harder cross-compiling, dynamic linking, and C bugs that crash the process.
  2. What are the cgo pointer passing rules? Go may pass a pointer to memory that holds no Go pointers (to unpinned memory); C may not keep a Go pointer after the call returns unless it's pinned with runtime.Pinner. GODEBUG=cgocheck=1 checks at run time.
  3. Why must you free C.CString? It's allocated with malloc; Go's garbage collector doesn't know about C memory.
  4. How do you make cgo calls cheaper? Batch: move loops into C so one call does many items; avoid per-item calls in hot paths.
  5. Is unsafe.String(unsafe.SliceData(b), len(b)) safe? Only if b is never modified while the string exists; otherwise an "immutable" string changes.
  6. Why is p := uintptr(unsafe.Pointer(x)); q := unsafe.Pointer(p + 8) wrong? A uintptr isn't seen as a pointer by the GC and stacks can move; pattern 3 requires the arithmetic in one expression (or unsafe.Add). go vet reports "possible misuse of unsafe.Pointer".
  7. What changed for //go:linkname in Go 1.23? The linker disallows references to standard-library internals not marked with //go:linkname; old uses from a large corpus stay supported; -checklinkname=0 disables the check for debugging.
  8. When would you choose cgo anyway? When a mature C library has no Go equivalent (some codecs, hardware SDKs, databases like SQLite via a cgo driver, episode 67) and the call pattern can be batched.

Glossary

Term Meaning Example
C an older programming language used for operating systems, databases and libraries int gst(int paise) { ... }
C library C code packed for other programs to reuse Raju's billing engine, zlib
cgo the go command's tool for calling C from Go import "C"
SWIG an older tool that generates bindings between C/C++ and other languages mentioned in the error message
gcc / clang C compilers: turn C source into machine code gcc -O2 bill.c
Preamble the comment directly above import "C", used as C code /* #include "bill.h" */
Header file (.h) a C file listing functions and types for other files bill.h
#include a C line that pastes a header in #include <stdlib.h>
Pseudo-package C cgo's name for everything in C; not a real package C.gst, C.int
#cgo directive a preamble line with C compiler/linker flags #cgo LDFLAGS: -lm
C.int, C.long, C.char, C.double Go names for C's types C.int(4999)
C string bytes ending in a zero byte "hello\0"
C.CString copies a Go string into new C memory (malloc) cs := C.CString(s)
C.GoString copies a C string into a Go string C.GoString(cs)
C.free frees C memory C.free(unsafe.Pointer(cs))
malloc C's function to allocate memory malloc(7 * sizeof(long))
Garbage collector (GC) the Go runtime part that frees unused Go memory never frees C memory
Memory leak memory taken and never given back 103876 kB after 100,000 calls
VmRSS the memory a Linux process really holds in RAM from /proc/self/status
Go pointer a pointer to memory Go allocated &prices[0]
Memory ownership who is responsible for freeing a piece of memory C memory: you call C.free
cgocheck the runtime's check of pointers passed to C GODEBUG=cgocheck=1
GODEBUG an environment variable with runtime settings GODEBUG=cgocheck=0
Pinning / runtime.Pinner promising Go won't move or free an object until unpinned p.Pin(x); defer p.Unpin()
cgo call overhead the fixed cost of switching from Go to C and back about 60 ns per call in this run
Benchmark / ns/op a timing test / nanoseconds per operation BenchmarkC-2 ... 61.80 ns/op
Batching doing many items in one call to pay a fixed cost once C.total(&cs[0], n)
Cross-compiling building for another OS or processor GOOS=windows go build
CGO_ENABLED turns cgo on (1) or off (0) CGO_ENABLED=0 go build
CC the C compiler cgo should use CC=<cross compiler>
C cross-compiler a C compiler that targets another system needed for cgo + GOOS=windows
Build constraint a condition for compiling a file; import "C" implies cgo //go:build cgo
Dynamic linking loading libraries (like libc) when the program starts cgo binaries usually need libc
unsafe package operations that step around Go's type safety unsafe.Pointer
Type safety the compiler stopping you from using a value as the wrong type can't read a float as an int
unsafe.Pointer a pointer to any type; converts to/from any pointer and uintptr unsafe.Pointer(&f)
uintptr an integer type big enough to hold an address; not a pointer to the GC uintptr(unsafe.Pointer(&o))
Valid patterns the six documented safe uses of unsafe.Pointer pattern 3: arithmetic in one expression
unsafe.Offsetof a field's distance in bytes from the start of its struct unsafe.Offsetof(o.Paise) = 8
unsafe.Sizeof a value's size in bytes unsafe.Sizeof(o) = 16
Padding unused bytes the compiler inserts so fields are aligned 4 bytes after ID int32
unsafe.Add adds an offset to a Pointer, keeping it a Pointer unsafe.Add(p, 8)
unsafe.Slice a slice over memory starting at a pointer, no copy (Go 1.17) unsafe.Slice(p, 7)
unsafe.SliceData a pointer to a slice's backing array (Go 1.20) unsafe.SliceData(line)
unsafe.String a string over bytes at a pointer, no copy (Go 1.20) unsafe.String(p, n)
unsafe.StringData a pointer to a string's bytes (Go 1.20) unsafe.StringData(s)
Immutable can never change after it's created Go strings
Zero-copy using existing bytes instead of copying them unsafe.String
Read-only memory memory the OS won't let the program write where "chai" lives
Segmentation fault (SIGSEGV) the program touched memory it may not use fatal error: fault
Fatal error a runtime failure that recover can't catch the whole program stops
testing.AllocsPerRun average heap allocations of a function 1 vs 0
go vet a tool that reports suspicious code possible misuse of unsafe.Pointer
checkptr run-time checks of unsafe pointer conversions -gcflags=all=-d=checkptr
Compiler directive a //go: comment with instructions for the compiler/linker //go:linkname, //go:build
Linker the tool that joins compiled code into one binary link: main: invalid reference ...
//go:linkname connects a local name to another package's (even private) symbol //go:linkname gcount runtime.gcount
-checklinkname=0 linker flag that disables the Go 1.23 linkname check -ldflags=-checklinkname=0
os/exec the package for running other programs run a C tool as a separate process

Summary

We needed fifteen years of C, so we built a bridge instead of a rewrite. The preamble and import "C" let Go call C; values are converted both ways; C strings are allocated with C.CString and freed by us, because the garbage collector never sees C memory; and C never keeps Go pointers, which cgocheck enforces. Every crossing costs dozens of times a Go call, so we batch. Cross-compiling needs a C cross-compiler. Then unsafe: unsafe.Slice and unsafe.String give views without copies, but only if nobody writes to the bytes; unsafe.Pointer has six allowed patterns, checked (not guaranteed) by go vet and checkptr; and //go:linkname into the standard library is closed since Go 1.23. Use all of it rarely, inside one small package, and prefer pure Go when you can.

Next episode: Code generation and Go tooling — go generate, stringer, text/template, go/ast, go/parser, go/types, writing an analyzer, gopls and compiler directives.