summaryrefslogtreecommitdiff
path: root/devdocs/go/runtime%2Fcgo%2Findex.html
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2025-08-14 22:58:58 -0500
committerCraig Jennings <c@cjennings.net>2025-08-14 22:58:58 -0500
commit82ba818ff456bcd6d56a06226e3f27e98fbb55c3 (patch)
tree158cfc17b2f644a10f063cb546752cfaae12c97f /devdocs/go/runtime%2Fcgo%2Findex.html
parent9278ddd4ea1a8b1a4c1edaa8894516e3f48d245b (diff)
downloaddotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.tar.gz
dotemacs-82ba818ff456bcd6d56a06226e3f27e98fbb55c3.zip
removing all downloaded devdocs files
Diffstat (limited to 'devdocs/go/runtime%2Fcgo%2Findex.html')
-rw-r--r--devdocs/go/runtime%2Fcgo%2Findex.html96
1 files changed, 0 insertions, 96 deletions
diff --git a/devdocs/go/runtime%2Fcgo%2Findex.html b/devdocs/go/runtime%2Fcgo%2Findex.html
deleted file mode 100644
index 1f504a91..00000000
--- a/devdocs/go/runtime%2Fcgo%2Findex.html
+++ /dev/null
@@ -1,96 +0,0 @@
-<h1> Package cgo </h1> <ul id="short-nav">
-<li><code>import "runtime/cgo"</code></li>
-<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
-<li><a href="#pkg-index" class="indexLink">Index</a></li>
-</ul> <h2 id="pkg-overview">Overview </h2> <p>Package cgo contains runtime support for code generated by the cgo tool. See the documentation for the cgo command for details on using cgo. </p> <h2 id="pkg-index">Index </h2> <ul id="manual-nav">
-<li><a href="#Handle">type Handle</a></li>
-<li> <a href="#NewHandle">func NewHandle(v any) Handle</a>
-</li>
-<li> <a href="#Handle.Delete">func (h Handle) Delete()</a>
-</li>
-<li> <a href="#Handle.Value">func (h Handle) Value() any</a>
-</li>
-<li><a href="#Incomplete">type Incomplete</a></li>
-</ul> <h3>Package files</h3> <p> <span>callbacks.go</span> <span>callbacks_traceback.go</span> <span>cgo.go</span> <span>handle.go</span> <span>iscgo.go</span> <span>linux.go</span> <span>mmap.go</span> <span>setenv.go</span> <span>sigaction.go</span> </p> <h2 id="Handle">type <span>Handle</span> </h2> <p>Handle provides a way to pass values that contain Go pointers (pointers to memory allocated by Go) between Go and C without breaking the cgo pointer passing rules. A Handle is an integer value that can represent any Go value. A Handle can be passed through C and back to Go, and Go code can use the Handle to retrieve the original Go value. </p>
-<p>The underlying type of Handle is guaranteed to fit in an integer type that is large enough to hold the bit pattern of any pointer. The zero value of a Handle is not valid, and thus is safe to use as a sentinel in C APIs. </p>
-<p>For instance, on the Go side: </p>
-<pre data-language="go">package main
-
-/*
-#include &lt;stdint.h&gt; // for uintptr_t
-
-extern void MyGoPrint(uintptr_t handle);
-void myprint(uintptr_t handle);
-*/
-import "C"
-import "runtime/cgo"
-
-//export MyGoPrint
-func MyGoPrint(handle C.uintptr_t) {
- h := cgo.Handle(handle)
- val := h.Value().(string)
- println(val)
- h.Delete()
-}
-
-func main() {
- val := "hello Go"
- C.myprint(C.uintptr_t(cgo.NewHandle(val)))
- // Output: hello Go
-}
-</pre> <p>and on the C side: </p>
-<pre data-language="go">#include &lt;stdint.h&gt; // for uintptr_t
-
-// A Go function
-extern void MyGoPrint(uintptr_t handle);
-
-// A C function
-void myprint(uintptr_t handle) {
- MyGoPrint(handle);
-}
-</pre> <p>Some C functions accept a void* argument that points to an arbitrary data value supplied by the caller. It is not safe to coerce a <a href="#Handle">cgo.Handle</a> (an integer) to a Go <span>unsafe.Pointer</span>, but instead we can pass the address of the cgo.Handle to the void* parameter, as in this variant of the previous example: </p>
-<pre data-language="go">package main
-
-/*
-extern void MyGoPrint(void *context);
-static inline void myprint(void *context) {
- MyGoPrint(context);
-}
-*/
-import "C"
-import (
- "runtime/cgo"
- "unsafe"
-)
-
-//export MyGoPrint
-func MyGoPrint(context unsafe.Pointer) {
- h := *(*cgo.Handle)(context)
- val := h.Value().(string)
- println(val)
- h.Delete()
-}
-
-func main() {
- val := "hello Go"
- h := cgo.NewHandle(val)
- C.myprint(unsafe.Pointer(&amp;h))
- // Output: hello Go
-}
-</pre> <pre data-language="go">type Handle uintptr</pre> <h3 id="NewHandle">func <span>NewHandle</span> </h3> <pre data-language="go">func NewHandle(v any) Handle</pre> <p>NewHandle returns a handle for a given value. </p>
-<p>The handle is valid until the program calls Delete on it. The handle uses resources, and this package assumes that C code may hold on to the handle, so a program must explicitly call Delete when the handle is no longer needed. </p>
-<p>The intended use is to pass the returned handle to C code, which passes it back to Go, which calls Value. </p>
-<h3 id="Handle.Delete">func (Handle) <span>Delete</span> </h3> <pre data-language="go">func (h Handle) Delete()</pre> <p>Delete invalidates a handle. This method should only be called once the program no longer needs to pass the handle to C and the C code no longer has a copy of the handle value. </p>
-<p>The method panics if the handle is invalid. </p>
-<h3 id="Handle.Value">func (Handle) <span>Value</span> </h3> <pre data-language="go">func (h Handle) Value() any</pre> <p>Value returns the associated Go value for a valid handle. </p>
-<p>The method panics if the handle is invalid. </p>
-<h2 id="Incomplete">type <span>Incomplete</span> </h2> <p>Incomplete is used specifically for the semantics of incomplete C types. </p>
-<pre data-language="go">type Incomplete struct {
- // contains filtered or unexported fields
-}
-</pre><div class="_attribution">
- <p class="_attribution-p">
- &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
- <a href="http://golang.org/pkg/runtime/cgo/" class="_attribution-link">http://golang.org/pkg/runtime/cgo/</a>
- </p>
-</div>