cgo.md - wiki - Git at Google

 # Introduction

 First, http://golang.org/cmd/cgo is the primary cgo documentation.

 There is also a good introduction article at http://golang.org/doc/articles/c_go_cgo.html.

 ## The basics

 If a Go source file imports ` "C" `, it is using cgo. The Go file will have access to anything appearing in the comment immediately preceding the line ` import "C" `, and will be linked against all other cgo comments in other Go files, and all C files included in the build process.

 Note that there must be no blank lines in between the cgo comment and the import statement.

 To access a symbol originating from the C side, use the package name ` C `. That is, if you want to call the C function ` printf() ` from Go code, you write ` C.printf() `.  Since variable argument methods like printf aren't supported yet (issue [975](https://github.com/golang/go/issues/975)), we will wrap it in the C method "myprint":

 ```go
 package cgoexample

 /*
 #include <stdio.h>
 #include <stdlib.h>

 void myprint(char* s) {
 	printf("%s", s);
 }
 */
 import "C"

 import "unsafe"

 func Example() {
 	cs := C.CString("Hello from stdio\n")
 	C.myprint(cs)
 	C.free(unsafe.Pointer(cs))
 }
 ```

 ## Calling Go functions from C

 It is possible to call both top-level Go functions and function variables from C code invoked from Go code using cgo.

 ### Global functions

 Go makes its functions available to C code through use of a special ` //export ` comment.
 Note: you can't define any C functions in preamble if you're using exports.

 For example, there are two files, foo.c and foo.go:
 foo.go contains:

 ```go
 package gocallback

 import "fmt"

 /*
 #include <stdio.h>
 extern void ACFunction();
 */
 import "C"

 //export AGoFunction
 func AGoFunction() {
 	fmt.Println("AGoFunction()")
 }

 func Example() {
 	C.ACFunction()
 }
 ```

 foo.c contains:

 ```go
 #include "_cgo_export.h"
 void ACFunction() {
 	printf("ACFunction()\n");
 	AGoFunction();
 }
 ```

 ### Function variables

 The following code shows an example of invoking a Go callback from C code. Go passes the function variable to the CGo code by calling ` CallMyFunction() `. ` CallMyFunction() ` invokes the callback by sending it back into the Go code, with the desired parameters, for unpacking and calling.

 ```go
 package gocallback

 import (
 	"fmt"
 	"unsafe"
 )

 /*
 extern void go_callback_int(void* foo, int p1);

 // normally you will have to define function or variables
 // in another separate C file to avoid the multiple definition
 // errors, however, using "static inline" is a nice workaround
 // for simple functions like this one.
 static inline void CallMyFunction(void* pfoo) {
 	go_callback_int(pfoo, 5);
 }
 */
 import "C"

 //export go_callback_int
 func go_callback_int(pfoo unsafe.Pointer, p1 C.int) {
 	foo := *(*func(C.int))(pfoo)
 	foo(p1)
 }

 func MyCallback(x C.int) {
 	fmt.Println("callback with", x)
 }

 // we store it in a global variable so that the garbage collector
 // doesn't clean up the memory for any temporary variables created.
 var MyCallbackFunc = MyCallback

 func Example() {
 	C.CallMyFunction(unsafe.Pointer(&MyCallbackFunc))
 }
 ```

 ### Function pointer callbacks

 C code can call exported Go functions with their explicit name. But if a C-program wants a function pointer, a gateway function has to be written. This is because we can't take the address of a Go function and give that to C-code since the cgo tool will generate a stub in C that should be called. The following example shows how to integrate with C code wanting a function pointer of a give type.

 Place these source files under _$GOPATH/src/ccallbacks/_. Compile and run with:

 ```console
 $ gcc -c clibrary.c
 $ ar cru libclibrary.a clibrary.o
 $ go build
 $ ./ccallbacks
 Go.main(): calling C function with callback to us
 C.some_c_func(): calling callback with arg = 2
 C.callOnMeGo_cgo(): called with arg = 2
 Go.callOnMeGo(): called with arg = 2
 C.some_c_func(): callback responded with 3
 ```

 **goprog.go**

 ```go
 package main

 /*
 #cgo CFLAGS: -I .
 #cgo LDFLAGS: -L . -lclibrary

 #include "clibrary.h"

 int callOnMeGo_cgo(int in); // Forward declaration.
 */
 import "C"

 import (
 	"fmt"
 	"unsafe"
 )

 //export callOnMeGo
 func callOnMeGo(in int) int {
 	fmt.Printf("Go.callOnMeGo(): called with arg = %d\n", in)
 	return in + 1
 }

 func main() {
 	fmt.Printf("Go.main(): calling C function with callback to us\n")
 	C.some_c_func((C.callback_fcn)(unsafe.Pointer(C.callOnMeGo_cgo)))
 }
 ```

 **cfuncs.go**

 ```go
 package main

 /*

 #include <stdio.h>

 // The gateway function
 int callOnMeGo_cgo(int in)
 {
 	printf("C.callOnMeGo_cgo(): called with arg = %d\n", in);
 	return callOnMeGo(in);
 }
 */
 import "C"
 ```

 **clibrary.h**
 ```
 #ifndef CLIBRARY_H
 #define CLIBRARY_H
 typedef int (*callback_fcn)(int);
 void some_c_func(callback_fcn);
 #endif
 ```

 **clibrary.c**

 ```go
 #include <stdio.h>

 #include "clibrary.h"

 void some_c_func(callback_fcn callback)
 {
 	int arg = 2;
 	printf("C.some_c_func(): calling callback with arg = %d\n", arg);
 	int response = callback(2);
 	printf("C.some_c_func(): callback responded with %d\n", response);
 }
 ```

 ## Go strings and C strings

 Go strings and C strings are different. Go strings are the combination of a length and a pointer to the first character in the string. C strings are just the pointer to the first character, and are terminated by the first instance of the null character, ` '\0' `.

 Go provides means to go from one to another in the form of the following three functions:
   * ` func C.CString(goString string) *C.char `
   * ` func C.GoString(cString *C.char) string `
   * ` func C.GoStringN(cString *C.char, length C.int) string `

 One important thing to remember is that ` C.CString() ` will allocate a new string of the appropriate length, and return it. That means the C string is not going to be garbage collected and it is up to **you** to free it. A standard way to do this follows.

 ```go
 // #include <stdlib.h>
 import "C"
 import "unsafe"
 ...
 	var cmsg *C.char = C.CString("hi")
 	defer C.free(unsafe.Pointer(cmsg))
 	// do something with the C string
 ```

 Of course, you aren't required to use ` defer ` to call ` C.free() `. You can free the C string whenever you like, but it is your responsibility to make sure it happens.

 ## Turning C arrays into Go slices

 C arrays are typically either null-terminated or have a length kept elsewhere.

 Go provides the following function to make a new Go byte slice from a C array:
   * ` func C.GoBytes(cArray unsafe.Pointer, length C.int) []byte `

 To create a Go slice backed by a C array (without copying the original data), one needs to acquire this length at runtime and use ` reflect.SliceHeader `.

 ```go
 import "C"
 import "unsafe"
 ...
 	var theCArray *C.YourType = C.getTheArray()
 	length := int(C.getTheArrayLength())
 	hdr := reflect.SliceHeader{
 		Data: uintptr(unsafe.Pointer(theCArray)),
 		Len:  length,
 		Cap:  length,
 	}
 	goSlice := *(*[]C.YourType)(unsafe.Pointer(&hdr))
         // now goSlice is a Go slice backed by the C array
 ```

 It is important to keep in mind that the Go garbage collector will not interact with this data, and that if it is freed from the C side of things, the behavior of any Go code using the slice is nondeterministic.

 Another simpler solution is casting the pointer to a pointer to a very big array and then
 slice it to the length that you want (also remember to set the cap if you're using Go 1.2
 or later), for example (see http://play.golang.org/p/XuC0xqtAIC for a runnable example):

 ```go
 import "C"
 import "unsafe"
 ...
         var theCArray *C.YourType = C.getTheArray()
         length := C.getTheArrayLength()
         slice := (*[1 << 30]C.YourType)(unsafe.Pointer(theCArray))[:length:length]
 ```

 ## Common Pitfalls
 ### Struct Alignment Issues
 As Go doesn't support packed struct (e.g., structs where maximum alignment is 1 byte), you can't
 use packed C struct in Go. Even if you program passes compilation, it won't do what you want.
 To use it, you have to read/write the struct as byte array/slice.

 Another problem is that some types has lower alignment requirement than their counterpart in Go,
 and if that type happens to be aligned in C but not in Go rules, that struct simply can't be represented
 in Go. An example is this ([issue 7560](https://github.com/golang/go/issues/7560)):

 ```go
 struct T {
     uint32_t pad;
     complex float x;
 };
 ```
 Go's complex64 has an alignment of 8-byte, where as C has only 4-byte (because C treats the
 complex float internally as a ` struct { float real; float imag; } `, not a basic type), this T struct simply
 doesn't have a Go representation. For this case, if you control the layout of the struct, move the
 complex float so that it is also aligned to 8-byte is better, and if you're not willing to move it,
 use this form will force it to align to 8-byte (and waste 4-byte):

 ```go
 struct T {
    uint32_t pad;
    __attribute__((align(8))) complex float x;
 };
 ```

 However, if you don't control the struct layout, you will have to define accessor C functions for
 that struct because cgo won't be able to translate that struct into equivalent Go struct.

 ### ` //export ` and definition in preamble
 If a Go source file uses any ` //export ` directives, then the C code in the comment may only include declarations (` extern int f(); `), not definitions (` int f() { return 1; }  ` or ` int n; `).
 Note: you can use ` static inline ` trick to work around this restriction for tiny functions defined
 in the preamble (see above for a complete example).

 ### Windows

 In order to use cgo on Windows, you'll also need to first install a gcc compiler (for instance, mingw-w64) and have gcc.exe (etc.) in your PATH environment variable before compiling with cgo will work.
	# Introduction

	First, http://golang.org/cmd/cgo is the primary cgo documentation.

	There is also a good introduction article at http://golang.org/doc/articles/c_go_cgo.html.

	## The basics

	If a Go source file imports ` "C" `, it is using cgo. The Go file will have access to anything appearing in the comment immediately preceding the line ` import "C" `, and will be linked against all other cgo comments in other Go files, and all C files included in the build process.

	Note that there must be no blank lines in between the cgo comment and the import statement.

	To access a symbol originating from the C side, use the package name ` C `. That is, if you want to call the C function ` printf() ` from Go code, you write ` C.printf() `. Since variable argument methods like printf aren't supported yet (issue [975](https://github.com/golang/go/issues/975)), we will wrap it in the C method "myprint":

	```go
	package cgoexample

	/*
	#include <stdio.h>
	#include <stdlib.h>

	void myprint(char* s) {
	printf("%s", s);
	}
	*/
	import "C"

	import "unsafe"

	func Example() {
	cs := C.CString("Hello from stdio\n")
	C.myprint(cs)
	C.free(unsafe.Pointer(cs))
	}
	```

	## Calling Go functions from C

	It is possible to call both top-level Go functions and function variables from C code invoked from Go code using cgo.

	### Global functions

	Go makes its functions available to C code through use of a special ` //export ` comment.
	Note: you can't define any C functions in preamble if you're using exports.

	For example, there are two files, foo.c and foo.go:
	foo.go contains:

	```go
	package gocallback

	import "fmt"

	/*
	#include <stdio.h>
	extern void ACFunction();
	*/
	import "C"

	//export AGoFunction
	func AGoFunction() {
	fmt.Println("AGoFunction()")
	}

	func Example() {
	C.ACFunction()
	}
	```

	foo.c contains:

	```go
	#include "_cgo_export.h"
	void ACFunction() {
	printf("ACFunction()\n");
	AGoFunction();
	}
	```

	### Function variables

	The following code shows an example of invoking a Go callback from C code. Go passes the function variable to the CGo code by calling ` CallMyFunction() `. ` CallMyFunction() ` invokes the callback by sending it back into the Go code, with the desired parameters, for unpacking and calling.

	```go
	package gocallback

	import (
	"fmt"
	"unsafe"
	)

	/*
	extern void go_callback_int(void* foo, int p1);

	// normally you will have to define function or variables
	// in another separate C file to avoid the multiple definition
	// errors, however, using "static inline" is a nice workaround
	// for simple functions like this one.
	static inline void CallMyFunction(void* pfoo) {
	go_callback_int(pfoo, 5);
	}
	*/
	import "C"

	//export go_callback_int
	func go_callback_int(pfoo unsafe.Pointer, p1 C.int) {
	foo := (func(C.int))(pfoo)
	foo(p1)
	}

	func MyCallback(x C.int) {
	fmt.Println("callback with", x)
	}

	// we store it in a global variable so that the garbage collector
	// doesn't clean up the memory for any temporary variables created.
	var MyCallbackFunc = MyCallback

	func Example() {
	C.CallMyFunction(unsafe.Pointer(&MyCallbackFunc))
	}
	```

	### Function pointer callbacks

	C code can call exported Go functions with their explicit name. But if a C-program wants a function pointer, a gateway function has to be written. This is because we can't take the address of a Go function and give that to C-code since the cgo tool will generate a stub in C that should be called. The following example shows how to integrate with C code wanting a function pointer of a give type.

	Place these source files under _$GOPATH/src/ccallbacks/_. Compile and run with:

	```console
	$ gcc -c clibrary.c
	$ ar cru libclibrary.a clibrary.o
	$ go build
	$ ./ccallbacks
	Go.main(): calling C function with callback to us
	C.some_c_func(): calling callback with arg = 2
	C.callOnMeGo_cgo(): called with arg = 2
	Go.callOnMeGo(): called with arg = 2
	C.some_c_func(): callback responded with 3
	```

	goprog.go

	```go
	package main

	/*
	#cgo CFLAGS: -I .
	#cgo LDFLAGS: -L . -lclibrary

	#include "clibrary.h"

	int callOnMeGo_cgo(int in); // Forward declaration.
	*/
	import "C"

	import (
	"fmt"
	"unsafe"
	)

	//export callOnMeGo
	func callOnMeGo(in int) int {
	fmt.Printf("Go.callOnMeGo(): called with arg = %d\n", in)
	return in + 1
	}

	func main() {
	fmt.Printf("Go.main(): calling C function with callback to us\n")
	C.some_c_func((C.callback_fcn)(unsafe.Pointer(C.callOnMeGo_cgo)))
	}
	```

	cfuncs.go

	```go
	package main

	/*

	#include <stdio.h>

	// The gateway function
	int callOnMeGo_cgo(int in)
	{
	printf("C.callOnMeGo_cgo(): called with arg = %d\n", in);
	return callOnMeGo(in);
	}
	*/
	import "C"
	```

	clibrary.h
	```
	#ifndef CLIBRARY_H
	#define CLIBRARY_H
	typedef int (*callback_fcn)(int);
	void some_c_func(callback_fcn);
	#endif
	```

	clibrary.c

	```go
	#include <stdio.h>

	#include "clibrary.h"

	void some_c_func(callback_fcn callback)
	{
	int arg = 2;
	printf("C.some_c_func(): calling callback with arg = %d\n", arg);
	int response = callback(2);
	printf("C.some_c_func(): callback responded with %d\n", response);
	}
	```

	## Go strings and C strings

	Go strings and C strings are different. Go strings are the combination of a length and a pointer to the first character in the string. C strings are just the pointer to the first character, and are terminated by the first instance of the null character, ` '\0' `.

	Go provides means to go from one to another in the form of the following three functions:
	* ` func C.CString(goString string) *C.char `
	* ` func C.GoString(cString *C.char) string `
	* ` func C.GoStringN(cString *C.char, length C.int) string `

	One important thing to remember is that ` C.CString() ` will allocate a new string of the appropriate length, and return it. That means the C string is not going to be garbage collected and it is up to you to free it. A standard way to do this follows.

	```go
	// #include <stdlib.h>
	import "C"
	import "unsafe"
	...
	var cmsg *C.char = C.CString("hi")
	defer C.free(unsafe.Pointer(cmsg))
	// do something with the C string
	```

	Of course, you aren't required to use ` defer ` to call ` C.free() `. You can free the C string whenever you like, but it is your responsibility to make sure it happens.

	## Turning C arrays into Go slices

	C arrays are typically either null-terminated or have a length kept elsewhere.

	Go provides the following function to make a new Go byte slice from a C array:
	* ` func C.GoBytes(cArray unsafe.Pointer, length C.int) []byte `

	To create a Go slice backed by a C array (without copying the original data), one needs to acquire this length at runtime and use ` reflect.SliceHeader `.

	```go
	import "C"
	import "unsafe"
	...
	var theCArray *C.YourType = C.getTheArray()
	length := int(C.getTheArrayLength())
	hdr := reflect.SliceHeader{
	Data: uintptr(unsafe.Pointer(theCArray)),
	Len: length,
	Cap: length,
	}
	goSlice := ([]C.YourType)(unsafe.Pointer(&hdr))
	// now goSlice is a Go slice backed by the C array
	```

	It is important to keep in mind that the Go garbage collector will not interact with this data, and that if it is freed from the C side of things, the behavior of any Go code using the slice is nondeterministic.

	Another simpler solution is casting the pointer to a pointer to a very big array and then
	slice it to the length that you want (also remember to set the cap if you're using Go 1.2
	or later), for example (see http://play.golang.org/p/XuC0xqtAIC for a runnable example):

	```go
	import "C"
	import "unsafe"
	...
	var theCArray *C.YourType = C.getTheArray()
	length := C.getTheArrayLength()
	slice := (*[1 << 30]C.YourType)(unsafe.Pointer(theCArray))[:length:length]
	```

	## Common Pitfalls
	### Struct Alignment Issues
	As Go doesn't support packed struct (e.g., structs where maximum alignment is 1 byte), you can't
	use packed C struct in Go. Even if you program passes compilation, it won't do what you want.
	To use it, you have to read/write the struct as byte array/slice.

	Another problem is that some types has lower alignment requirement than their counterpart in Go,
	and if that type happens to be aligned in C but not in Go rules, that struct simply can't be represented
	in Go. An example is this ([issue 7560](https://github.com/golang/go/issues/7560)):

	```go
	struct T {
	uint32_t pad;
	complex float x;
	};
	```
	Go's complex64 has an alignment of 8-byte, where as C has only 4-byte (because C treats the
	complex float internally as a ` struct { float real; float imag; } `, not a basic type), this T struct simply
	doesn't have a Go representation. For this case, if you control the layout of the struct, move the
	complex float so that it is also aligned to 8-byte is better, and if you're not willing to move it,
	use this form will force it to align to 8-byte (and waste 4-byte):

	```go
	struct T {
	uint32_t pad;
	__attribute__((align(8))) complex float x;
	};
	```

	However, if you don't control the struct layout, you will have to define accessor C functions for
	that struct because cgo won't be able to translate that struct into equivalent Go struct.

	### ` //export ` and definition in preamble
	If a Go source file uses any ` //export ` directives, then the C code in the comment may only include declarations (` extern int f(); `), not definitions (` int f() { return 1; } ` or ` int n; `).
	Note: you can use ` static inline ` trick to work around this restriction for tiny functions defined
	in the preamble (see above for a complete example).

	### Windows

	In order to use cgo on Windows, you'll also need to first install a gcc compiler (for instance, mingw-w64) and have gcc.exe (etc.) in your PATH environment variable before compiling with cgo will work.