cmd/cgo: document errno value semantics

Added a section about errno values vs normal go
error value semantics, and checking the return
value of C functions for error before looking at
errno.

Fixes #63485

Change-Id: Id0132a9f11e4127f4adc14e010b7e17f57a0f7d3
Reviewed-on: https://go-review.googlesource.com/c/go/+/616264
Reviewed-by: Michael Knyszek <mknyszek@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>

diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index 16d0c0fa816c6e86e2d649b657fb42d7ed3bcdf8..a2b69b20dcdc3a33b1c672dddb92b180d4770eba 100644 (file)
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -209,6 +209,17 @@ function returns void). For example:
        _, err := C.voidFunc()
        var n, err = C.sqrt(1)
 
+Note that the C errno value may be non-zero, and thus the err result may be
+non-nil, even if the function call is successful. Unlike normal Go conventions,
+you should first check whether the call succeeded before checking the error
+result. For example:
+
+       n, err := C.setenv(key, value, 1)
+       if n != 0 {
+               // we know the call failed, so it is now valid to use err
+               return err
+       }
+
 Calling C function pointers is currently not supported, however you can
 declare Go variables which hold C function pointers and pass them
 back and forth between Go and C. C code may call function pointers