cmd/cgo: add note about bug writing C pointers to uninitialized C memory
Describe the problem as a bug, since it is not implied by the rest of
the pointer passing rules, and it may be possible to fix it.
Updates #19928
Change-Id: I2d336e7336b2a215c0b8cf909a203201ef1b054e
Reviewed-on: https://go-review.googlesource.com/123658
Reviewed-by: Austin Clements <austin@google.com>
diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index 4bd82eb..980906b 100644
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -377,6 +377,14 @@
it likes. However, programs that break these rules are likely to fail
in unexpected and unpredictable ways.
+Note: the current implementation has a bug. While Go code is permitted
+to write nil or a C pointer (but not a Go pointer) to C memory, the
+current implementation may sometimes cause a runtime error if the
+contents of the C memory appear to be a Go pointer. Therefore, avoid
+passing uninitialized C memory to Go code if the Go code is going to
+store pointer values in it. Zero out the memory in C before passing it
+to Go.
+
Special cases
A few special C types which would normally be represented by a pointer
