CGO Basics

Advanced ~45 min read

CGO enables Go programs to call C code and vice versa. This powerful feature allows you to leverage existing C libraries, optimize performance-critical sections, and integrate with legacy systems. Learn the fundamentals of CGO, from basic function calls to memory management and build configuration.

What is CGO?

CGO is a foreign function interface (FFI) that allows Go code to call C functions and use C types. It's built into the Go toolchain and requires a C compiler.

CGO Use Cases:

Legacy Integration - Use existing C libraries
Performance - Optimize critical paths with C
System APIs - Access OS-specific C APIs
Hardware - Interface with device drivers

CGO Tradeoffs:

⚠️ Slower build times
⚠️ Cross-compilation complexity
⚠️ Debugging is harder
⚠️ Memory management complexity
⚠️ Not pure Go (loses some benefits)

Hello CGO

The basic CGO syntax uses a special comment block before import "C":

package main

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

void hello() {
    printf("Hello from C!\n");
}

int add(int a, int b) {
    return a + b;
}

char* greet(const char* name) {
    static char buffer[100];
    sprintf(buffer, "Hello, %s from C!", name);
    return buffer;
}
*/
import "C"
import (
	"fmt"
	"unsafe"
)

func main() {
	fmt.Println("CGO Hello World Demo")
	fmt.Println("====================\n")

// Call C function with no parameters
	fmt.Println("1. Calling C hello():")
	C.hello()
	fmt.Println()

// Call C function with parameters
	fmt.Println("2. Calling C add(10, 20):")
	result := C.add(10, 20)
	fmt.Printf("   Result: %d\n\n", result)

// Call C function with string
	fmt.Println("3. Calling C greet(\"Gopher\"):")
	name := C.CString("Gopher")
	greeting := C.greet(name)
	fmt.Printf("   %s\n\n", C.GoString(greeting))

// Important: Free C memory
	C.free(unsafe.Pointer(name))

fmt.Println("CGO Basics:")
	fmt.Println("  • Use import \"C\" to access C code")
	fmt.Println("  • C code goes in comment block above import")
	fmt.Println("  • Prefix C functions with C.")
	fmt.Println("  • Convert between Go and C types")
	fmt.Println("  • Always free C memory!")
}

Output

Click Run to execute your code

CGO Syntax Rules:

C code goes in comment block before import "C"
No blank line between comment and import
Prefix C functions with C.
Use #include for C headers

Type Conversions

Converting between Go and C types requires explicit conversions:

package main

/*
#include <stdint.h>

// C types
int c_int = 42;
float c_float = 3.14;
double c_double = 2.718;
char c_char = 'A';

// Type conversion functions
int64_t to_int64(int x) {
    return (int64_t)x;
}

double to_double(float x) {
    return (double)x;
}
*/
import "C"
import (
	"fmt"
	"unsafe"
)

func main() {
	fmt.Println("CGO Type Conversions")
	fmt.Println("====================\n")

// Go to C conversions
	fmt.Println("1. Go → C conversions:")

goInt := 100
	cInt := C.int(goInt)
	fmt.Printf("   Go int %d → C int %d\n", goInt, cInt)

goFloat := 3.14159
	cFloat := C.float(goFloat)
	fmt.Printf("   Go float64 %.5f → C float %.5f\n", goFloat, cFloat)

goString := "Hello"
	cString := C.CString(goString)
	fmt.Printf("   Go string \"%s\" → C string\n", goString)
	C.free(unsafe.Pointer(cString))
	fmt.Println()

// C to Go conversions
	fmt.Println("2. C → Go conversions:")

fmt.Printf("   C int %d → Go int %d\n", C.c_int, int(C.c_int))
	fmt.Printf("   C float %.2f → Go float32 %.2f\n", C.c_float, float32(C.c_float))
	fmt.Printf("   C double %.3f → Go float64 %.3f\n", C.c_double, float64(C.c_double))
	fmt.Printf("   C char '%c' → Go byte '%c'\n", C.c_char, byte(C.c_char))
	fmt.Println()

// Using C functions for conversion
	fmt.Println("3. Using C conversion functions:")

result64 := C.to_int64(42)
	fmt.Printf("   C to_int64(42) = %d (type: int64)\n", result64)

resultDouble := C.to_double(3.14)
	fmt.Printf("   C to_double(3.14) = %.2f (type: double)\n", resultDouble)
	fmt.Println()

fmt.Println("Type Mapping:")
	fmt.Println("  Go int     ↔ C int")
	fmt.Println("  Go int32   ↔ C int32_t")
	fmt.Println("  Go int64   ↔ C int64_t")
	fmt.Println("  Go float32 ↔ C float")
	fmt.Println("  Go float64 ↔ C double")
	fmt.Println("  Go string  ↔ C char* (via C.CString)")
	fmt.Println("  Go []byte  ↔ C char* (via C.CBytes)")
}

Output

Click Run to execute your code

Go Type	C Type	Conversion
int	int	C.int(x)
int32	int32_t	C.int32_t(x)
int64	int64_t	C.int64_t(x)
float32	float	C.float(x)
float64	double	C.double(x)
string	char*	C.CString(s)
[]byte	void*	C.CBytes(b)

String Handling

Strings require special care because Go strings are immutable and C strings are null-terminated:

package main

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

// String manipulation in C
char* concat_strings(const char* a, const char* b) {
    size_t len = strlen(a) + strlen(b) + 1;
    char* result = (char*)malloc(len);
    strcpy(result, a);
    strcat(result, b);
    return result;
}

// String length in C
int string_length(const char* s) {
    return strlen(s);
}

// Convert to uppercase
void to_upper(char* s) {
    for (int i = 0; s[i]; i++) {
        if (s[i] >= 'a' && s[i] <= 'z') {
            s[i] = s[i] - 32;
        }
    }
}
*/
import "C"
import (
	"fmt"
	"unsafe"
)

func main() {
	fmt.Println("CGO String Handling")
	fmt.Println("===================\n")

// Go string to C string
	fmt.Println("1. Go → C string conversion:")
	goStr := "Hello, CGO!"
	cStr := C.CString(goStr)
	fmt.Printf("   Go string: %s\n", goStr)
	fmt.Printf("   C string created\n")

// Get length using C function
	length := C.string_length(cStr)
	fmt.Printf("   Length (from C): %d\n\n", length)

// Free the C string
	C.free(unsafe.Pointer(cStr))

// Concatenate strings in C
	fmt.Println("2. String concatenation in C:")
	str1 := C.CString("Hello, ")
	str2 := C.CString("World!")

result := C.concat_strings(str1, str2)
	goResult := C.GoString(result)
	fmt.Printf("   \"%s\" + \"%s\" = \"%s\"\n\n",
		C.GoString(str1), C.GoString(str2), goResult)

// Free all C memory
	C.free(unsafe.Pointer(str1))
	C.free(unsafe.Pointer(str2))
	C.free(unsafe.Pointer(result))

// Modify string in place
	fmt.Println("3. In-place string modification:")
	original := "hello world"
	cOriginal := C.CString(original)
	fmt.Printf("   Before: %s\n", C.GoString(cOriginal))

C.to_upper(cOriginal)
	fmt.Printf("   After:  %s\n\n", C.GoString(cOriginal))

C.free(unsafe.Pointer(cOriginal))

// Working with byte slices
	fmt.Println("4. Go []byte to C:")
	goBytes := []byte("Binary data")
	cBytes := C.CBytes(goBytes)
	fmt.Printf("   Go []byte: %v\n", goBytes)
	fmt.Printf("   Converted to C bytes\n")
	C.free(cBytes)
	fmt.Println()

fmt.Println("String Handling Rules:")
	fmt.Println("  ✓ Use C.CString() to convert Go string → C char*")
	fmt.Println("  ✓ Use C.GoString() to convert C char* → Go string")
	fmt.Println("  ✓ Use C.CBytes() for []byte → C")
	fmt.Println("  ✓ Always C.free() C-allocated memory")
	fmt.Println("  ✓ C strings are null-terminated")
	fmt.Println("  ✓ Go strings are immutable, C strings are not")
}

Output

Click Run to execute your code

String Conversion Functions:

C.CString(s) - Go string → C char* (allocates, must free)
C.GoString(cs) - C char* → Go string (copies)
C.GoStringN(cs, n) - C char* → Go string (with length)
C.CBytes(b) - Go []byte → C void* (allocates, must free)
C.GoBytes(p, n) - C void* → Go []byte (copies)

Callbacks

Go functions can be called from C using the //export directive:

package main

/*
#include <stdio.h>

// C callback type
typedef void (*callback_func)(int);

// C function that accepts a callback
void process_numbers(int* numbers, int count, callback_func callback) {
    for (int i = 0; i < count; i++) {
        callback(numbers[i]);
    }
}

// C function that calls a callback multiple times
void repeat_callback(callback_func callback, int times) {
    for (int i = 0; i < times; i++) {
        callback(i);
    }
}
*/
import "C"
import (
	"fmt"
	"unsafe"
)

// Go callback function
//
//export goCallback
func goCallback(n C.int) {
	fmt.Printf("  Go callback received: %d\n", n)
}

// Another Go callback
//
//export printSquare
func printSquare(n C.int) {
	square := int(n) * int(n)
	fmt.Printf("  Square of %d = %d\n", n, square)
}

func main() {
	fmt.Println("CGO Callbacks")
	fmt.Println("=============\n")

// Example 1: Process array with callback
	fmt.Println("1. Processing array with Go callback:")
	numbers := []C.int{1, 2, 3, 4, 5}
	C.process_numbers(
		(*C.int)(unsafe.Pointer(&numbers[0])),
		C.int(len(numbers)),
		(C.callback_func)(unsafe.Pointer(C.goCallback)),
	)
	fmt.Println()

// Example 2: Repeat callback
	fmt.Println("2. Repeating callback 3 times:")
	C.repeat_callback(
		(C.callback_func)(unsafe.Pointer(C.printSquare)),
		3,
	)
	fmt.Println()

fmt.Println("Callback Rules:")
	fmt.Println("  • Use //export directive for Go functions")
	fmt.Println("  • Go callbacks must use C types")
	fmt.Println("  • Cast function pointer with unsafe.Pointer")
	fmt.Println("  • Callbacks run on C stack")
	fmt.Println("  • Keep callbacks simple and fast")

fmt.Println("\nLimitations:")
	fmt.Println("  ⚠ Cannot call Go functions that allocate")
	fmt.Println("  ⚠ Cannot use goroutines in callbacks")
	fmt.Println("  ⚠ Cannot panic in callbacks")
	fmt.Println("  ⚠ Must be careful with Go pointers")
}

Output

Click Run to execute your code

Callback Restrictions:

Exported functions must use C types
Cannot call Go functions that allocate
Cannot use goroutines
Cannot panic
Keep callbacks simple and fast

Memory Management

Understanding memory ownership is critical when using CGO:

package main

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

// Allocate memory in C
void* allocate_memory(size_t size) {
    return malloc(size);
}

// Free memory in C
void free_memory(void* ptr) {
    free(ptr);
}

// Create a C string
char* create_string(const char* content) {
    char* str = (char*)malloc(strlen(content) + 1);
    strcpy(str, content);
    return str;
}

// Create an integer array
int* create_int_array(int size) {
    return (int*)malloc(size * sizeof(int));
}

// Fill array with values
void fill_array(int* arr, int size) {
    for (int i = 0; i < size; i++) {
        arr[i] = i * 10;
    }
}
*/
import "C"
import (
	"fmt"
	"unsafe"
)

func main() {
	fmt.Println("CGO Memory Management")
	fmt.Println("=====================\n")

// Example 1: Allocate and free C memory
	fmt.Println("1. Basic C memory allocation:")
	size := C.size_t(100)
	ptr := C.allocate_memory(size)
	fmt.Printf("   Allocated %d bytes at %p\n", size, ptr)
	C.free_memory(ptr)
	fmt.Println("   Memory freed\n")

// Example 2: C string allocation
	fmt.Println("2. C string allocation:")
	cStr := C.create_string(C.CString("Hello from C"))
	goStr := C.GoString(cStr)
	fmt.Printf("   C string: %s\n", goStr)
	C.free(unsafe.Pointer(cStr))
	fmt.Println("   String freed\n")

// Example 3: C array allocation
	fmt.Println("3. C array allocation:")
	arraySize := 5
	cArray := C.create_int_array(C.int(arraySize))
	C.fill_array(cArray, C.int(arraySize))

// Convert C array to Go slice
	goSlice := (*[1 << 30]C.int)(unsafe.Pointer(cArray))[:arraySize:arraySize]
	fmt.Printf("   Array values: ")
	for i := 0; i < arraySize; i++ {
		fmt.Printf("%d ", goSlice[i])
	}
	fmt.Println()

C.free(unsafe.Pointer(cArray))
	fmt.Println("   Array freed\n")

// Example 4: Go memory passed to C
	fmt.Println("4. Passing Go memory to C:")
	goData := []byte("Go data")
	cData := C.CBytes(goData)
	fmt.Printf("   Copied %d bytes to C\n", len(goData))
	C.free(cData)
	fmt.Println("   C copy freed\n")

fmt.Println("Memory Management Rules:")
	fmt.Println("  ✓ C.malloc() allocates C memory")
	fmt.Println("  ✓ C.free() frees C memory")
	fmt.Println("  ✓ C.CString() allocates (must free)")
	fmt.Println("  ✓ C.CBytes() allocates (must free)")
	fmt.Println("  ✓ C.GoString() copies (no free needed)")
	fmt.Println("  ✓ C.GoBytes() copies (no free needed)")

fmt.Println("\nDanger Zone:")
	fmt.Println("  ⚠ Don't pass Go pointers to C that outlive the call")
	fmt.Println("  ⚠ Don't store Go pointers in C memory")
	fmt.Println("  ⚠ Always free C-allocated memory")
	fmt.Println("  ⚠ Memory leaks are easy with CGO")
}

Output

Click Run to execute your code

Memory Rules:

✓ C-allocated memory must be freed with C.free()
✓ C.CString() allocates - always free
✓ C.CBytes() allocates - always free
✓ C.GoString() copies - no free needed
✓ Don't pass Go pointers to C that outlive the call
✓ Don't store Go pointers in C memory

Build Configuration

Use #cgo directives to configure the C compiler and linker:

//go:build cgo
// +build cgo

package main

// Build tags for conditional compilation

/*
#cgo CFLAGS: -Wall -O2
#cgo LDFLAGS: -lm

#include <math.h>
#include <stdio.h>

double calculate_circle_area(double radius) {
    return M_PI * radius * radius;
}

void print_build_info() {
    printf("Built with CGO\n");
    #ifdef __linux__
    printf("Platform: Linux\n");
    #elif __APPLE__
    printf("Platform: macOS\n");
    #elif _WIN32
    printf("Platform: Windows\n");
    #endif
}
*/
import "C"
import "fmt"

func main() {
	fmt.Println("CGO Build Configuration")
	fmt.Println("=======================\n")

// Use C math library
	fmt.Println("1. Using C math library:")
	radius := 5.0
	area := C.calculate_circle_area(C.double(radius))
	fmt.Printf("   Circle area (radius=%.1f): %.2f\n\n", radius, area)

// Print build info
	fmt.Println("2. Build information:")
	C.print_build_info()
	fmt.Println()

fmt.Println("Build Configuration:")
	fmt.Println("  #cgo CFLAGS: -Wall -O2")
	fmt.Println("    → Compiler flags for C code")
	fmt.Println("  #cgo LDFLAGS: -lm")
	fmt.Println("    → Linker flags (link math library)")
	fmt.Println()

fmt.Println("Build Tags:")
	fmt.Println("  // +build cgo")
	fmt.Println("    → Only build when CGO is enabled")
	fmt.Println("  // +build linux")
	fmt.Println("    → Only build on Linux")
	fmt.Println("  // +build !windows")
	fmt.Println("    → Build on all platforms except Windows")
	fmt.Println()

fmt.Println("Platform-Specific Flags:")
	fmt.Println("  #cgo linux CFLAGS: -D_GNU_SOURCE")
	fmt.Println("  #cgo darwin LDFLAGS: -framework CoreFoundation")
	fmt.Println("  #cgo windows LDFLAGS: -lws2_32")
	fmt.Println()

fmt.Println("Build Commands:")
	fmt.Println("  go build                  # Build with CGO")
	fmt.Println("  CGO_ENABLED=0 go build    # Build without CGO")
	fmt.Println("  go build -tags nocgo      # Skip CGO files")
	fmt.Println()

fmt.Println("Environment Variables:")
	fmt.Println("  CGO_ENABLED=1             # Enable CGO (default)")
	fmt.Println("  CGO_CFLAGS                # Additional C flags")
	fmt.Println("  CGO_LDFLAGS               # Additional linker flags")
	fmt.Println("  CC=gcc                    # C compiler to use")
}

Output

Click Run to execute your code

Common #cgo Directives:

// Compiler flags
#cgo CFLAGS: -Wall -O2 -I/usr/local/include

// Linker flags
#cgo LDFLAGS: -L/usr/local/lib -lmylib

// Platform-specific
#cgo linux CFLAGS: -D_GNU_SOURCE
#cgo darwin LDFLAGS: -framework CoreFoundation
#cgo windows LDFLAGS: -lws2_32

// Package config
#cgo pkg-config: gtk+-3.0

Common Mistakes

1. Forgetting to free C memory

// ❌ Wrong - memory leak
func bad() {
    s := C.CString("hello")
    // Forgot to free!
}

// ✅ Correct - always free
func good() {
    s := C.CString("hello")
    defer C.free(unsafe.Pointer(s))
    // Use s...
}

2. Passing Go pointers incorrectly

// ❌ Wrong - Go pointer stored in C
var globalPtr *C.char
func bad() {
    s := "hello"
    globalPtr = C.CString(s) // Dangerous!
}

// ✅ Correct - manage lifetime properly
func good() {
    s := C.CString("hello")
    defer C.free(unsafe.Pointer(s))
    // Use s within this scope
}

3. Blank line before import "C"

// ❌ Wrong - blank line breaks CGO
/*
#include 
*/

import "C" // Error!

// ✅ Correct - no blank line
/*
#include 
*/
import "C" // Works!

Exercise: C Library Wrapper

Task: Create a Go wrapper for a simple C math library.

Requirements:

C functions for basic math operations
Go wrapper with proper error handling
Memory management
Type conversions

Show Solution

package main

/*
#include 
#include 

typedef struct {
    double result;
    int error;
} MathResult;

MathResult safe_divide(double a, double b) {
    MathResult r;
    if (b == 0.0) {
        r.error = 1;
        r.result = 0.0;
    } else {
        r.error = 0;
        r.result = a / b;
    }
    return r;
}

double* create_array(int size) {
    return (double*)malloc(size * sizeof(double));
}

void fill_array(double* arr, int size) {
    for (int i = 0; i < size; i++) {
        arr[i] = sqrt((double)i);
    }
}
*/
import "C"
import (
    "fmt"
    "unsafe"
)

// SafeDivide wraps C division with error handling
func SafeDivide(a, b float64) (float64, error) {
    result := C.safe_divide(C.double(a), C.double(b))
    
    if result.error != 0 {
        return 0, fmt.Errorf("division by zero")
    }
    
    return float64(result.result), nil
}

// CalculateSquareRoots creates array of square roots
func CalculateSquareRoots(n int) []float64 {
    // Allocate C array
    cArray := C.create_array(C.int(n))
    defer C.free(unsafe.Pointer(cArray))
    
    // Fill with values
    C.fill_array(cArray, C.int(n))
    
    // Convert to Go slice
    goSlice := make([]float64, n)
    cSlice := (*[1 << 30]C.double)(unsafe.Pointer(cArray))[:n:n]
    
    for i := 0; i < n; i++ {
        goSlice[i] = float64(cSlice[i])
    }
    
    return goSlice
}

func main() {
    // Test division
    result, err := SafeDivide(10, 2)
    if err != nil {
        fmt.Println("Error:", err)
    } else {
        fmt.Printf("10 / 2 = %.2f\n", result)
    }
    
    // Test division by zero
    _, err = SafeDivide(10, 0)
    if err != nil {
        fmt.Println("Error:", err)
    }
    
    // Test array
    roots := CalculateSquareRoots(5)
    fmt.Println("Square roots:", roots)
}

Summary

CGO enables Go to call C code
import "C" provides access to C functions
Type conversions are explicit (C.int, C.CString)
Memory management is critical - always free C memory
C.CString() allocates, must free with C.free()
C.GoString() copies, no free needed
//export allows C to call Go functions
#cgo directives configure compiler and linker
Build tags control conditional compilation
Tradeoffs - power vs complexity

What's Next?

You've learned CGO basics! While powerful, CGO should be used judiciously. Next, you'll explore the unsafe package, which provides low-level memory operations and type conversions that bypass Go's type safety - use with extreme caution!

Previous Escape Analysis

Next Unsafe Package

What is CGO?

Hello CGO

Type Conversions

String Handling

Callbacks

Memory Management

Build Configuration

Common Mistakes

1. Forgetting to free C memory

2. Passing Go pointers incorrectly

3. Blank line before import "C"

Exercise: C Library Wrapper

Summary

What's Next?

Enjoying these tutorials?