From 208a1ea564e8b1ce8d6d85a315a410f29d5e952e Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Thu, 15 May 2014 16:16:26 -0400
Subject: [PATCH] doc/go1.3.html: add note about unsafe.Pointer strictness

The vet check is in CL 10470044.

LGTM=bradfitz, r
R=r, bradfitz
CC=golang-codereviews
https://golang.org/cl/91480044
---
 doc/go1.3.html | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/go1.3.html b/doc/go1.3.html
index e13faa1b085..056c4cbe81a 100644
--- a/doc/go1.3.html
+++ b/doc/go1.3.html
@@ -117,6 +117,26 @@ This means that a non-pointer Go value such as an integer will never be mistaken
 pointer and prevent unused memory from being reclaimed.
 </p>
 
+<p>
+Starting with Go 1.3, the runtime assumes that values with pointer type
+contain pointers and other values do not.
+This assumption is fundamental to the precise behavior of both stack expansion
+and garbage collection.
+Programs that use <a href="/pkg/unsafe/">package unsafe</a>
+to store <code>uintptrs</code> in pointer values are illegal and will crash if the runtime detects the behavior.
+Programs that use <a href="/pkg/unsafe/">package unsafe</a> to store pointers
+in <code>uintptr</code> values are also illegal but more difficult to diagnose during execution.
+Because the pointers are hidden from the runtime, a stack expansion or garbage collection
+may reclaim the memory they point at, creating
+<a href="http://en.wikipedia.org/wiki/Dangling_pointer">dangling pointers</a>.
+</p>
+
+<p>
+<em>Updating</em>: Code that converts a <code>uintptr</code> value stored in memory
+to <code>unsafe.Pointer</code> is illegal and must be rewritten.
+Such code can be identified by <code>go vet</code>.
+</p>
+
 <h3 id="liblink">The linker</h3>
 
 <p>