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."
Cis a "pseudo-package", "a special name interpreted by cgo as a reference to C's name space." The comment aboveimport "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.GoStringandC.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(andC.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." Forunsafe.StringData: "the bytes returned by StringData must not be modified." - Go 1.17 release notes: added
unsafe.Addandunsafe.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:#includelines 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.hlistsgst. - Pseudo-package
C: there is no real package named C;C.gst,C.int,C.freeare cgo's names for things in C. #cgolines in the preamble set compiler and linker flags, e.g.#cgo LDFLAGS: -lmto 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 ofsinto 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.deferright after allocating is the idiom. C.GoString(cs)copies a C string back into a Go string;C.GoStringN(p, n)copiesnbytes;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 withC.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):
- Go may pass a Go pointer to C if the memory it points to holds no Go pointers to unpinned memory.
- C may not keep a copy of a Go pointer after the call returns, unless the memory is pinned with
runtime.Pinner. runtime.Pinner(Go 1.21+):var p runtime.Pinner; p.Pin(ptr)promises Go won't move or free that object untilp.Unpin().GODEBUG=cgocheck=1(the default) checks at run time;cgocheck=0turns the checks off, which only hides bugs. A complete (slower) check is available withGOEXPERIMENT=cgocheck2at 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 withimport "C"get the implicit build constraintcgo, so they are skipped, and here nothing is left:build constraints exclude all Go files in .. - Forcing
CGO_ENABLED=1makes 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 keepCGO_ENABLED=0. - A cgo binary is usually dynamically linked (it loads the C library when it starts), so it fails in a
scratchcontainer image withexec /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.AllocsPerRuncounts heap allocations per call; storing tosink, 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
paidtoFAIL. 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:IDis 4 bytes, then 4 bytes of padding so theint64starts on an 8-byte boundary).unsafe.Sizeof(o): the struct's size, 16.- The broken part keeps the address in a
uintptrvariable. Auintptris 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. Plaingo runprintsbad: 4999— it works today, by luck. go vetreportspossible misuse of unsafe.Pointer. Building with-gcflags=all=-d=checkptradds run-time checks of unsafe conversions (the race detector-raceturns 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 1.23 refuses it (LINK)
// $ 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 asC.name. - Convert values both ways:
C.int(x),int(r). C.CStringallocates C memory →defer C.free(unsafe.Pointer(cs));C.GoStringcopies back.- C never keeps Go pointers; never pass memory that contains Go pointers;
runtime.Pinnerif C must hold one. - Each crossing costs dozens × a Go call → batch.
- Cross-compiling with cgo needs
CCset to a C cross-compiler andCGO_ENABLED=1. unsafe.Slice,unsafe.String,unsafe.StringData,unsafe.SliceDatabuild views without copying; never modify bytes behind a string.- Use only the six
unsafe.Pointerpatterns; rungo vetand-d=checkptr. - No new
//go:linknameto standard library internals (Go 1.23+).
Mini project: a GST bridge
Build a package gstc that wraps the C billing code:
- A Go API:
Total([]int) int(one C call per cart) andCheckDigit(string) int. No C types leave the package. - Every
C.CStringis freed. - Benchmarks: one C call per item vs one batched call vs pure Go.
- A pure Go version and a test that both give the same answers.
go vetclean, 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
- Wrap C's
sqrtfrommath.h. What#cgoline do you need, and which C type does it take? - Write
func ToUpperC(s string) stringthat calls a C function writing into a buffer you allocate withC.malloc. Who frees what? - Why can't you pass a
[]stringto C even for one call? - Change the BENCH program so the cart has 10 items. Roughly what time per op do you expect for
TotalC? - A teammate converts every incoming
[]byteto a string withunsafe.Stringfor speed. What question should you ask before approving? - Rewrite the broken part of RULES with
unsafe.Addsogo vetand 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
- 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.
- 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=1checks at run time. - Why must you free
C.CString? It's allocated with malloc; Go's garbage collector doesn't know about C memory. - 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.
- Is
unsafe.String(unsafe.SliceData(b), len(b))safe? Only ifbis never modified while the string exists; otherwise an "immutable" string changes. - 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 (orunsafe.Add).go vetreports "possible misuse of unsafe.Pointer". - What changed for
//go:linknamein 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=0disables the check for debugging. - 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.