From: Brian Palmer <brian@codekitchen.net>
Date: Fri, 27 Sep 2024 20:09:11 +0000 (-0600)
Subject: cmd/cgo: document errno value semantics
X-Git-Tag: go1.24rc1~781
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=b37b27b595898f6c5e65e3c78d76bc50caef8622;p=gostls13.git

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 16d0c0fa81..a2b69b20dc 100644
--- 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