Go & cgo: integrating existing C code with Go

Andreas Krennmair <ak@synflood.at>

Golang User Group Berlin

Twitter: @der_ak

Introduction

• Go is meant to be a practical language
• Integration with existing software, infrastructure and protocols necessary
• Ability to use existing C code is crucial for success (case in point: C++)
• Go's solution: cgo
• Tool to generate code to access C library functions and global variables

cgo: Basic Steps

1. start a new .go source file
2. import "C"
3. embed the C code you want to interface as comment (e.g. #include <foo.h>) prior to the import
4. Imported C functions, types and global variables are available under the virtual "C" package
5. Add CGOFILES=foo.go to your Makefile
6. optional: #cgo preprocessor instructions to set C defines and linker flags

Yes, it's that simple.

First Example

package pwnam
/*
#include <sys/types.h>
#include <pwd.h>
#include <stdlib.h>
*/
import ( "C" ; "unsafe" )

type Passwd struct {
	Uid uint32 ; Gid uint32 ; Dir string ; Shell string
}

func Getpwnam(name string) *Passwd {
	cname := C.CString(name)
	defer C.free(unsafe.Pointer(cname))
	cpw := C.getpwnam(cname)
	return &Passwd{
		Uid: uint32(cpw.pw_uid), Gid: uint32(cpw.pw_uid),
		Dir: C.GoString(cpw.pw_dir), Shell: C.GoString(cpw.pw_shell)}
}

Linking

• Usually, you want to access functions outside of libc
• Linking to external libraries required
• Two possibilities:
  1. Add CGO_LDFLAGS to Makefile
  2. Embed in .go source file using #cgo directive (preferred)
• One step further: cgo can use pkg-config

Linking Examples

• #cgo LDFLAGS:

  package pcap
  /*
  #cgo LDFLAGS: -lpcap
  #include <stdlib.h>
  #include <pcap.h>
  */
  import "C"

• #cgo pkg-config:

  package stfl
  /*
  #cgo pkg-config: stfl
  #cgo LDFLAGS: -lncursesw
  #include <stdlib.h>
  #include <stfl.h>
  */
  import "C"

Mapping the C namespace to Go

• Everything declared in the C code is available in the C pseudo-package
• Fundamental C data types have their counterpart, e.g. int → C.int, unsigned short → C.ushort, etc.
• The Go equivalent to void * is unsafe.Pointer
• typedefs are available under their own name
• structs are available with a struct_ prefix, e.g. struct foo → C.struct_foo, same goes for unions and enums

Conversion between C and Go strings

• The C package contains conversion functions to convert Go to C strings and vice versa
• Also: opaque data (behind void *) to []byte

// Go string to C string; result must be freed with C.free
func C.CString(string) *C.char

// C string to Go string
func C.GoString(*C.char) string

// C string, length to Go string
func C.GoStringN(*C.char, C.int) string

// C pointer, length to Go []byte
func C.GoBytes(unsafe.Pointer, C.int) []byte

Calling Go code from C (1)

• Go code can be exported via comment: //export <function-name>
• It can then be called from C

package foo

/*
extern void myprint(int i);

void dofoo(void) {
	int i;
	for (i=0;i<10;i++) {
		myprint(i);
	}
}
*/
import "C"

Calling Go code from C (2)

//export myprint
func myprint(i C.int) {
	fmt.Printf("i = %v\n", uint32(i))
}

func DoFoo() {
	C.dofoo()
}

Questions?

Useful Links:

• Slides: http://akrennmair.github.com/golang-cgo-slides/
• gopcap: https://github.com/akrennmair/gopcap
• go-stfl: https://github.com/akrennmair/go-stfl
• List of Go library bindings: http://go-lang.cat-v.org/library-bindings