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 4bd82ebd12462543a125651846d6e4f7fa3a150c..980906b9212d70c949d4fd3a798de2cebe28092d 100644 (file)
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -377,6 +377,14 @@ and of course there is nothing stopping the C code from doing anything
 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