unsafe & Pointers

The escape hatch from the type system

The unsafe package lets you do three things the language otherwise forbids:

• ask a type’s layout: Sizeof, Alignof, Offsetof (compile-time constants — see memory layout);
• convert any *T to unsafe.Pointer and back to any *U, reinterpreting the same bytes as a different type;
• convert unsafe.Pointer ↔ uintptr to do pointer arithmetic.

The first is harmless. The second and third are where the power and the danger live. The compiler stops type-checking through an unsafe.Pointer, so the correctness of the reinterpretation is entirely yours to guarantee.

Pointer vs uintptr: the critical distinction

This is the whole game:

• unsafe.Pointer is a real pointer. The garbage collector knows about it — it keeps the pointed-to object alive and, for stack objects, updates it if the stack moves.
• uintptr is just an integer that happens to hold an address. The GC treats it as a number: it does not keep anything alive, and does not fix it up if the object moves.

So storing uintptr(unsafe.Pointer(&x)) in a variable is a latent bug: between that statement and using it, the GC could move or collect x, leaving you with a stale number. The official unsafe rules require any Pointer → uintptr → arithmetic → Pointer round-trip to happen in a single expression, with no GC-observable pause in the middle.

graph LR
P["unsafe.Pointer<br/>(GC tracks it)"] -->|"in ONE expression"| U["uintptr + offset<br/>(just a number)"]
U -->|"back to"| P2["unsafe.Pointer<br/>(GC tracks again)"]
U -.->|"⚠ stored in a var"| Bad["stale address<br/>(GC may move/free)"]

The valid patterns, runnable

This program shows the three everyday legitimate uses: reinterpreting a same-layout type, reaching a struct field by offset (single expression!), and zero-copy string/[]byte conversion with the modern unsafe.String/unsafe.Slice helpers.

package main

import (
"fmt"
"unsafe"
)

// Two structs with identical layout.
type RGBA struct{ R, G, B, A uint8 }
type Pixel struct{ R, G, B, A uint8 }

type Vec struct {
X, Y, Z float64
}

func main() {
// 1. Reinterpret *RGBA as *Pixel (same layout, no copy).
c := RGBA{255, 128, 0, 255}
p := (*Pixel)(unsafe.Pointer(&c))
fmt.Printf("reinterpreted pixel: %+v\n", *p)

// 2. Pointer to a field via offset — all in ONE expression.
v := Vec{1, 2, 3}
zPtr := (*float64)(unsafe.Pointer(
	uintptr(unsafe.Pointer(&v)) + unsafe.Offsetof(v.Z),
))
*zPtr = 99
fmt.Printf("v after writing Z via offset: %+v\n", v)

// 3. Zero-copy []byte -> string (no allocation) with Go 1.20 helpers.
b := []byte("hello, internals")
s := unsafe.String(unsafe.SliceData(b), len(b))
fmt.Println("zero-copy string:", s)

// ...and back, string -> []byte view (read-only! see the gotcha).
view := unsafe.Slice(unsafe.StringData(s), len(s))
fmt.Println("first byte:", view[0])
}

Every conversion here is layout-safe and respects the single-expression rule for the uintptr arithmetic. Run it and you’ll see the reinterpreted pixel, the field written through a raw offset, and a string that shares the slice’s bytes with no copy.

Reference

See also

• memory layout & alignment — the Sizeof/Offsetof constants and why layout must match.
• interfaces, itab & eface — interface internals you can inspect with unsafe.
• the garbage collector — why uintptr isn’t a reference.
• framing & protocols (web) — use encoding/binary, not raw struct bytes, for the wire.

Next: how interfaces are really represented — interfaces, itab & eface.

Related topics