cmd/cgo: document C.malloc behavior

Fixes #16309.

Change-Id: Ifcd28b0746e1af30e2519a7b118485aecfb12396
Reviewed-on: https://go-review.googlesource.com/31811
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index e6f9173aaf83f6daa3e4fba4c238b1a40cdcdeb4..e5d288167ecc2562486bed318eb03c665232757d 100644 (file)
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -216,6 +216,13 @@ by making copies of the data.  In pseudo-Go definitions:
        // C data with explicit length to Go []byte
        func C.GoBytes(unsafe.Pointer, C.int) []byte
 
+As a special case, C.malloc does not call the C library malloc directly
+but instead calls a Go helper function that wraps the C library malloc
+but guarantees never to return nil. If C's malloc indicates out of memory,
+the helper function crashes the program, like when Go itself runs out
+of memory. Because C.malloc cannot fail, it has no two-result form
+that returns errno.
+
 C references to Go
 
 Go functions can be exported for use by C code in the following way: