cgo enables Go programs to call C code directly, essential for accessing C libraries, system APIs, or performance-critical routines when pure Go solutions are insufficient. 1) Use import "C" with a preceding comment block to include C headers or inline code. 2) Call C functions using the C. prefix, such as C.printf. 3) Convert Go strings to C strings with C.CString and always free memory using C.free to prevent leaks. 4) Pass slices by obtaining a pointer to the underlying array via &data[0] and casting to the appropriate C pointer type. 5) Access C variables through pointers, preferably wrapped in C functions for safety. 6) Be aware of limitations: performance overhead at the Go/C boundary, lack of goroutine safety in C code, build complexity requiring a C compiler, memory management responsibility, reduced portability, and risks with long-term storage of Go pointers in C. 7) Use cgo when interfacing with system libraries, wrapping established C libraries, or accessing OS-specific features not in Go’s standard library. 8) Avoid cgo when pure Go alternatives exist, performance is critical, or maximum portability is required. With careful use, cgo integrates Go into the broader systems programming landscape effectively and safely.

Go’s cgo tool allows Go programs to call C code directly, enabling access to existing C libraries, system APIs, or performance-critical routines written in C. While Go is designed to be self-contained and portable, cgo bridges the gap when integration with native code is necessary—such as when working with operating system features, hardware interfaces, or legacy systems.

You don’t need cgo for most Go development. In fact, pure Go code is preferred for portability and simplicity. But when you do need it, understanding how cgo works is essential.

How cgo Works: The Basics

cgo is not a foreign function interface (FFI) in the traditional sense. Instead, it acts as a preprocessor and glue layer that generates Go and C code to enable interoperability.

To use cgo, you must import the special pseudo-package "C" and include C headers or inline code in a comment block above the import:

/*
#include <stdio.h>
*/
import "C"

This comment is processed by cgo. Everything in that block is treated as real C code—headers, function declarations, or even inline implementations.

After that, you can call C functions using the C. prefix:

func main() {
    C.printf(C.CString("Hello from C!\n"))
}

Note: CString converts a Go string to a *C.char, which is necessary because Go and C manage memory differently.

Passing Data Between Go and C

Data types in Go and C are not directly compatible. cgo provides type mappings and helper functions to convert between them.

Common Type Mappings

Converting Strings

Go strings are immutable and not null-terminated. C strings are null-terminated arrays of char.

Use C.CString() to convert a Go string to a C string:

cs := C.CString("hello")
C.printf(cs)
C.free(unsafe.Pointer(cs)) // Important: free memory!

?? Always free memory allocated by C.CString() using C.free, or you’ll leak memory.

Passing Slices and Arrays

To pass a Go slice to C:

data := []C.int{1, 2, 3, 4}
ptr := (*C.int)(&data[0])
C.process_array(ptr, C.int(len(data)))

Here, &data[0] gets a pointer to the underlying array, which is then cast to a C pointer.

For safety, ensure the slice isn’t empty and isn’t moved by the garbage collector during the C call (usually fine for synchronous calls).

Calling C Functions and Using C Variables

You can call any C function available in the included headers:

/*
#include <stdlib.h>
*/
import "C"
import "unsafe"

func mallocExample() {
    ptr := C.malloc(C.size_t(100))
    if ptr != nil {
        // Use memory...
        C.free(ptr)
    }
}

You can also declare C functions inline:

/*
int add(int a, int b) {
    return a   b;
}
*/
import "C"

func goAdd(x, y int) int {
    return int(C.add(C.int(x), C.int(y)))
}

Global C variables can be accessed via pointers:

/*
int counter = 0;
*/
import "C"

func increment() {
    C.counter  
}

Or from Go:

*(*C.int)(unsafe.Pointer(&C.counter))  = 1

But direct access is limited—usually, it’s cleaner to wrap variables in C getter/setter functions.

Limitations and Gotchas

While cgo is powerful, it comes with trade-offs:

• Performance overhead: Crossing the Go/C boundary has a cost. Avoid calling C functions in tight loops unless necessary.
• No goroutine safety in C: C code does not understand Go’s goroutines. Blocking C calls can stall the Go scheduler unless you use runtime.LockOSThread or ensure proper threading.
• Build complexity: cgo requires a C compiler and complicates cross-compilation.
• Memory management: You’re responsible for freeing C-allocated memory. Mixing Go and C allocators incorrectly leads to crashes or leaks.
• Portability: Code using cgo is not pure Go and won’t compile on all platforms without the right C dependencies.

Also, avoid passing Go pointers to C functions that store them long-term. The Go garbage collector doesn’t track C memory, so this can lead to dangling pointers.

If you must pass Go callbacks to C, use //go:cgo callback and //go:cgo no_mangle directives carefully, and pin Go functions using C.functionName references.

When to Use cgo

Use cgo when:

• You need to interface with system libraries (e.g., libc, libpthread, OpenGL)
• Wrapping a well-established C library (e.g., libpng, sqlite3)
• Accessing OS-specific features not exposed in Go’s standard library

Avoid cgo when:

• Pure Go alternatives exist (e.g., net package instead of raw socket C calls)
• Performance is critical and the overhead matters
• You need maximum portability (e.g., WebAssembly, embedded systems)

Summary

cgo enables Go to call C code seamlessly by combining Go and C compilation with a binding layer. It supports calling C functions, sharing data, and even embedding C code directly in Go files.

Key points:

• Use import "C" and comment blocks for C code
• Convert strings and slices carefully using C.CString, C.free, and pointer casting
• Mind memory management and threading implications
• Prefer pure Go when possible

Used wisely, cgo is a powerful tool for integrating Go with the wider systems programming ecosystem. Just remember: with great power comes great responsibility.

The above is the detailed content of Understanding `cgo`: Calling C Code from Go. For more information, please follow other related articles on the PHP Chinese website!