1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
6 Cgo enables the creation of Go packages that call C code.
8 # Using cgo with the go command
10 To use cgo write normal Go code that imports a pseudo-package "C".
11 The Go code can then refer to types such as C.size_t, variables such
12 as C.stdout, or functions such as C.putchar.
14 If the import of "C" is immediately preceded by a comment, that
15 comment, called the preamble, is used as a header when compiling
16 the C parts of the package. For example:
22 The preamble may contain any C code, including function and variable
23 declarations and definitions. These may then be referred to from Go
24 code as though they were defined in the package "C". All names
25 declared in the preamble may be used, even if they start with a
26 lower-case letter. Exception: static variables in the preamble may
27 not be referenced from Go code; static functions are permitted.
29 See $GOROOT/cmd/cgo/internal/teststdio and $GOROOT/misc/cgo/gmp for examples. See
30 "C? Go? Cgo!" for an introduction to using cgo:
31 https://golang.org/doc/articles/c_go_cgo.html.
33 CFLAGS, CPPFLAGS, CXXFLAGS, FFLAGS and LDFLAGS may be defined with pseudo
34 #cgo directives within these comments to tweak the behavior of the C, C++
35 or Fortran compiler. Values defined in multiple directives are concatenated
36 together. The directive can include a list of build constraints limiting its
37 effect to systems satisfying one of the constraints
38 (see https://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).
41 // #cgo CFLAGS: -DPNG_DEBUG=1
42 // #cgo amd64 386 CFLAGS: -DX86=1
43 // #cgo LDFLAGS: -lpng
47 Alternatively, CPPFLAGS and LDFLAGS may be obtained via the pkg-config tool
48 using a '#cgo pkg-config:' directive followed by the package names.
51 // #cgo pkg-config: png cairo
55 The default pkg-config tool may be changed by setting the PKG_CONFIG environment variable.
57 For security reasons, only a limited set of flags are allowed, notably -D, -U, -I, and -l.
58 To allow additional flags, set CGO_CFLAGS_ALLOW to a regular expression
59 matching the new flags. To disallow flags that would otherwise be allowed,
60 set CGO_CFLAGS_DISALLOW to a regular expression matching arguments
61 that must be disallowed. In both cases the regular expression must match
62 a full argument: to allow -mfoo=bar, use CGO_CFLAGS_ALLOW='-mfoo.*',
63 not just CGO_CFLAGS_ALLOW='-mfoo'. Similarly named variables control
64 the allowed CPPFLAGS, CXXFLAGS, FFLAGS, and LDFLAGS.
66 Also for security reasons, only a limited set of characters are
67 permitted, notably alphanumeric characters and a few symbols, such as
68 '.', that will not be interpreted in unexpected ways. Attempts to use
69 forbidden characters will get a "malformed #cgo argument" error.
71 When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS, CGO_FFLAGS and
72 CGO_LDFLAGS environment variables are added to the flags derived from
73 these directives. Package-specific flags should be set using the
74 directives, not the environment variables, so that builds work in
75 unmodified environments. Flags obtained from environment variables
76 are not subject to the security limitations described above.
78 All the cgo CPPFLAGS and CFLAGS directives in a package are concatenated and
79 used to compile C files in that package. All the CPPFLAGS and CXXFLAGS
80 directives in a package are concatenated and used to compile C++ files in that
81 package. All the CPPFLAGS and FFLAGS directives in a package are concatenated
82 and used to compile Fortran files in that package. All the LDFLAGS directives
83 in any package in the program are concatenated and used at link time. All the
84 pkg-config directives are concatenated and sent to pkg-config simultaneously
85 to add to each appropriate set of command-line flags.
87 When the cgo directives are parsed, any occurrence of the string ${SRCDIR}
88 will be replaced by the absolute path to the directory containing the source
89 file. This allows pre-compiled static libraries to be included in the package
90 directory and linked properly.
91 For example if package foo is in the directory /go/src/foo:
93 // #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo
97 // #cgo LDFLAGS: -L/go/src/foo/libs -lfoo
99 When the Go tool sees that one or more Go files use the special import
100 "C", it will look for other non-Go files in the directory and compile
101 them as part of the Go package. Any .c, .s, .S or .sx files will be
102 compiled with the C compiler. Any .cc, .cpp, or .cxx files will be
103 compiled with the C++ compiler. Any .f, .F, .for or .f90 files will be
104 compiled with the fortran compiler. Any .h, .hh, .hpp, or .hxx files will
105 not be compiled separately, but, if these header files are changed,
106 the package (including its non-Go source files) will be recompiled.
107 Note that changes to files in other directories do not cause the package
108 to be recompiled, so all non-Go source code for the package should be
109 stored in the package directory, not in subdirectories.
110 The default C and C++ compilers may be changed by the CC and CXX
111 environment variables, respectively; those environment variables
112 may include command line options.
114 The cgo tool will always invoke the C compiler with the source file's
115 directory in the include path; i.e. -I${SRCDIR} is always implied. This
116 means that if a header file foo/bar.h exists both in the source
117 directory and also in the system include directory (or some other place
118 specified by a -I flag), then "#include <foo/bar.h>" will always find the
119 local version in preference to any other version.
121 The cgo tool is enabled by default for native builds on systems where
122 it is expected to work. It is disabled by default when cross-compiling
123 as well as when the CC environment variable is unset and the default
124 C compiler (typically gcc or clang) cannot be found on the system PATH.
125 You can override the default by setting the CGO_ENABLED
126 environment variable when running the go tool: set it to 1 to enable
127 the use of cgo, and to 0 to disable it. The go tool will set the
128 build constraint "cgo" if cgo is enabled. The special import "C"
129 implies the "cgo" build constraint, as though the file also said
130 "//go:build cgo". Therefore, if cgo is disabled, files that import
131 "C" will not be built by the go tool. (For more about build constraints
132 see https://golang.org/pkg/go/build/#hdr-Build_Constraints).
134 When cross-compiling, you must specify a C cross-compiler for cgo to
135 use. You can do this by setting the generic CC_FOR_TARGET or the
136 more specific CC_FOR_${GOOS}_${GOARCH} (for example, CC_FOR_linux_arm)
137 environment variable when building the toolchain using make.bash,
138 or you can set the CC environment variable any time you run the go tool.
140 The CXX_FOR_TARGET, CXX_FOR_${GOOS}_${GOARCH}, and CXX
141 environment variables work in a similar way for C++ code.
145 Within the Go file, C's struct field names that are keywords in Go
146 can be accessed by prefixing them with an underscore: if x points at a C
147 struct with a field named "type", x._type accesses the field.
148 C struct fields that cannot be expressed in Go, such as bit fields
149 or misaligned data, are omitted in the Go struct, replaced by
150 appropriate padding to reach the next field or the end of the struct.
152 The standard C numeric types are available under the names
153 C.char, C.schar (signed char), C.uchar (unsigned char),
154 C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int),
155 C.long, C.ulong (unsigned long), C.longlong (long long),
156 C.ulonglong (unsigned long long), C.float, C.double,
157 C.complexfloat (complex float), and C.complexdouble (complex double).
158 The C type void* is represented by Go's unsafe.Pointer.
159 The C types __int128_t and __uint128_t are represented by [16]byte.
161 A few special C types which would normally be represented by a pointer
162 type in Go are instead represented by a uintptr. See the Special
165 To access a struct, union, or enum type directly, prefix it with
166 struct_, union_, or enum_, as in C.struct_stat.
168 The size of any C type T is available as C.sizeof_T, as in
169 C.sizeof_struct_stat.
171 A C function may be declared in the Go file with a parameter type of
172 the special name _GoString_. This function may be called with an
173 ordinary Go string value. The string length, and a pointer to the
174 string contents, may be accessed by calling the C functions
176 size_t _GoStringLen(_GoString_ s);
177 const char *_GoStringPtr(_GoString_ s);
179 These functions are only available in the preamble, not in other C
180 files. The C code must not modify the contents of the pointer returned
181 by _GoStringPtr. Note that the string contents may not have a trailing
184 As Go doesn't have support for C's union type in the general case,
185 C's union types are represented as a Go byte array with the same length.
187 Go structs cannot embed fields with C types.
189 Go code cannot refer to zero-sized fields that occur at the end of
190 non-empty C structs. To get the address of such a field (which is the
191 only operation you can do with a zero-sized field) you must take the
192 address of the struct and add the size of the struct.
194 Cgo translates C types into equivalent unexported Go types.
195 Because the translations are unexported, a Go package should not
196 expose C types in its exported API: a C type used in one Go package
197 is different from the same C type used in another.
199 Any C function (even void functions) may be called in a multiple
200 assignment context to retrieve both the return value (if any) and the
201 C errno variable as an error (use _ to skip the result value if the
202 function returns void). For example:
205 _, err := C.voidFunc()
206 var n, err = C.sqrt(1)
208 Calling C function pointers is currently not supported, however you can
209 declare Go variables which hold C function pointers and pass them
210 back and forth between Go and C. C code may call function pointers
211 received from Go. For example:
215 // typedef int (*intFunc) ();
218 // bridge_int_func(intFunc f)
231 f := C.intFunc(C.fortytwo)
232 fmt.Println(int(C.bridge_int_func(f)))
236 In C, a function argument written as a fixed size array
237 actually requires a pointer to the first element of the array.
238 C compilers are aware of this calling convention and adjust
239 the call accordingly, but Go cannot. In Go, you must pass
240 the pointer to the first element explicitly: C.f(&C.x[0]).
242 Calling variadic C functions is not supported. It is possible to
243 circumvent this by using a C function wrapper. For example:
247 // #include <stdio.h>
248 // #include <stdlib.h>
250 // static void myprint(char* s) {
251 // printf("%s\n", s);
257 cs := C.CString("Hello from stdio")
259 C.free(unsafe.Pointer(cs))
262 A few special functions convert between Go and C types
263 by making copies of the data. In pseudo-Go definitions:
265 // Go string to C string
266 // The C string is allocated in the C heap using malloc.
267 // It is the caller's responsibility to arrange for it to be
268 // freed, such as by calling C.free (be sure to include stdlib.h
269 // if C.free is needed).
270 func C.CString(string) *C.char
272 // Go []byte slice to C array
273 // The C array is allocated in the C heap using malloc.
274 // It is the caller's responsibility to arrange for it to be
275 // freed, such as by calling C.free (be sure to include stdlib.h
276 // if C.free is needed).
277 func C.CBytes([]byte) unsafe.Pointer
279 // C string to Go string
280 func C.GoString(*C.char) string
282 // C data with explicit length to Go string
283 func C.GoStringN(*C.char, C.int) string
285 // C data with explicit length to Go []byte
286 func C.GoBytes(unsafe.Pointer, C.int) []byte
288 As a special case, C.malloc does not call the C library malloc directly
289 but instead calls a Go helper function that wraps the C library malloc
290 but guarantees never to return nil. If C's malloc indicates out of memory,
291 the helper function crashes the program, like when Go itself runs out
292 of memory. Because C.malloc cannot fail, it has no two-result form
297 Go functions can be exported for use by C code in the following way:
300 func MyFunction(arg1, arg2 int, arg3 string) int64 {...}
303 func MyFunction2(arg1, arg2 int, arg3 string) (int64, *C.char) {...}
305 They will be available in the C code as:
307 extern GoInt64 MyFunction(int arg1, int arg2, GoString arg3);
308 extern struct MyFunction2_return MyFunction2(int arg1, int arg2, GoString arg3);
310 found in the _cgo_export.h generated header, after any preambles
311 copied from the cgo input files. Functions with multiple
312 return values are mapped to functions returning a struct.
314 Not all Go types can be mapped to C types in a useful way.
315 Go struct types are not supported; use a C struct type.
316 Go array types are not supported; use a C pointer.
318 Go functions that take arguments of type string may be called with the
319 C type _GoString_, described above. The _GoString_ type will be
320 automatically defined in the preamble. Note that there is no way for C
321 code to create a value of this type; this is only useful for passing
322 string values from Go to C and back to Go.
324 Using //export in a file places a restriction on the preamble:
325 since it is copied into two different C output files, it must not
326 contain any definitions, only declarations. If a file contains both
327 definitions and declarations, then the two output files will produce
328 duplicate symbols and the linker will fail. To avoid this, definitions
329 must be placed in preambles in other files, or in C source files.
333 Go is a garbage collected language, and the garbage collector needs to
334 know the location of every pointer to Go memory. Because of this,
335 there are restrictions on passing pointers between Go and C.
337 In this section the term Go pointer means a pointer to memory
338 allocated by Go (such as by using the & operator or calling the
339 predefined new function) and the term C pointer means a pointer to
340 memory allocated by C (such as by a call to C.malloc). Whether a
341 pointer is a Go pointer or a C pointer is a dynamic property
342 determined by how the memory was allocated; it has nothing to do with
343 the type of the pointer.
345 Note that values of some Go types, other than the type's zero value,
346 always include Go pointers. This is true of string, slice, interface,
347 channel, map, and function types. A pointer type may hold a Go pointer
348 or a C pointer. Array and struct types may or may not include Go
349 pointers, depending on the element types. All the discussion below
350 about Go pointers applies not just to pointer types, but also to other
351 types that include Go pointers.
353 All Go pointers passed to C must point to pinned Go memory. Go pointers
354 passed as function arguments to C functions have the memory they point to
355 implicitly pinned for the duration of the call. Go memory reachable from
356 these function arguments must be pinned as long as the C code has access
357 to it. Whether Go memory is pinned is a dynamic property of that memory
358 region; it has nothing to do with the type of the pointer.
360 Go values created by calling new, by taking the address of a composite
361 literal, or by taking the address of a local variable may also have their
362 memory pinned using [runtime.Pinner]. This type may be used to manage
363 the duration of the memory's pinned status, potentially beyond the
364 duration of a C function call. Memory may be pinned more than once and
365 must be unpinned exactly the same number of times it has been pinned.
367 Go code may pass a Go pointer to C provided the memory to which it
368 points does not contain any Go pointers to memory that is unpinned. When
369 passing a pointer to a field in a struct, the Go memory in question is
370 the memory occupied by the field, not the entire struct. When passing a
371 pointer to an element in an array or slice, the Go memory in question is
372 the entire array or the entire backing array of the slice.
374 C code may keep a copy of a Go pointer only as long as the memory it
377 C code may not keep a copy of a Go pointer after the call returns,
378 unless the memory it points to is pinned with [runtime.Pinner] and the
379 Pinner is not unpinned while the Go pointer is stored in C memory.
380 This implies that C code may not keep a copy of a string, slice,
381 channel, and so forth, because they cannot be pinned with
384 The _GoString_ type also may not be pinned with [runtime.Pinner].
385 Because it includes a Go pointer, the memory it points to is only pinned
386 for the duration of the call; _GoString_ values may not be retained by C
389 A Go function called by C code may return a Go pointer to pinned memory
390 (which implies that it may not return a string, slice, channel, and so
391 forth). A Go function called by C code may take C pointers as arguments,
392 and it may store non-pointer data, C pointers, or Go pointers to pinned
393 memory through those pointers. It may not store a Go pointer to unpinned
394 memory in memory pointed to by a C pointer (which again, implies that it
395 may not store a string, slice, channel, and so forth). A Go function
396 called by C code may take a Go pointer but it must preserve the property
397 that the Go memory to which it points (and the Go memory to which that
398 memory points, and so on) is pinned.
400 These rules are checked dynamically at runtime. The checking is
401 controlled by the cgocheck setting of the GODEBUG environment
402 variable. The default setting is GODEBUG=cgocheck=1, which implements
403 reasonably cheap dynamic checks. These checks may be disabled
404 entirely using GODEBUG=cgocheck=0. Complete checking of pointer
405 handling, at some cost in run time, is available via GODEBUG=cgocheck=2.
407 It is possible to defeat this enforcement by using the unsafe package,
408 and of course there is nothing stopping the C code from doing anything
409 it likes. However, programs that break these rules are likely to fail
410 in unexpected and unpredictable ways.
412 The runtime/cgo.Handle type can be used to safely pass Go values
413 between Go and C. See the runtime/cgo package documentation for details.
415 Note: the current implementation has a bug. While Go code is permitted
416 to write nil or a C pointer (but not a Go pointer) to C memory, the
417 current implementation may sometimes cause a runtime error if the
418 contents of the C memory appear to be a Go pointer. Therefore, avoid
419 passing uninitialized C memory to Go code if the Go code is going to
420 store pointer values in it. Zero out the memory in C before passing it
423 # Optimizing calls of C code
425 When passing a Go pointer to a C function the compiler normally ensures
426 that the Go object lives on the heap. If the C function does not keep
427 a copy of the Go pointer, and never passes the Go pointer back to Go code,
428 then this is unnecessary. The #cgo noescape directive may be used to tell
429 the compiler that no Go pointers escape via the named C function.
430 If the noescape directive is used and the C function does not handle the
431 pointer safely, the program may crash or see memory corruption.
435 // #cgo noescape cFunctionName
437 When a Go function calls a C function, it prepares for the C function to
438 call back to a Go function. the #cgo nocallback directive may be used to
439 tell the compiler that these preparations are not necessary.
440 If the nocallback directive is used and the C function does call back into
441 Go code, the program will panic.
445 // #cgo nocallback cFunctionName
449 A few special C types which would normally be represented by a pointer
450 type in Go are instead represented by a uintptr. Those include:
452 1. The *Ref types on Darwin, rooted at CoreFoundation's CFTypeRef type.
454 2. The object types from Java's JNI interface:
472 3. The EGLDisplay and EGLConfig types from the EGL API.
474 These types are uintptr on the Go side because they would otherwise
475 confuse the Go garbage collector; they are sometimes not really
476 pointers but data structures encoded in a pointer type. All operations
477 on these types must happen in C. The proper constant to initialize an
478 empty such reference is 0, not nil.
480 These special cases were introduced in Go 1.10. For auto-updating code
481 from Go 1.9 and earlier, use the cftype or jni rewrites in the Go fix tool:
483 go tool fix -r cftype <pkg>
484 go tool fix -r jni <pkg>
486 It will replace nil with 0 in the appropriate places.
488 The EGLDisplay case was introduced in Go 1.12. Use the egl rewrite
489 to auto-update code from Go 1.11 and earlier:
491 go tool fix -r egl <pkg>
493 The EGLConfig case was introduced in Go 1.15. Use the eglconf rewrite
494 to auto-update code from Go 1.14 and earlier:
496 go tool fix -r eglconf <pkg>
502 go tool cgo [cgo options] [-- compiler options] gofiles...
504 Cgo transforms the specified input Go source files into several output
505 Go and C source files.
507 The compiler options are passed through uninterpreted when
508 invoking the C compiler to compile the C parts of the package.
510 The following options are available when running cgo directly:
513 Print cgo version and exit.
515 Debugging option. Print #defines.
517 Debugging option. Trace C compiler execution and output.
519 Write list of symbols imported by file. Write to
520 -dynout argument or to standard output. Used by go
521 build when building a cgo package.
523 Write dynamic linker as part of -dynimport output.
525 Write -dynimport output to file.
527 Set Go package for -dynimport output.
529 If there are any exported functions, write the
530 generated export declarations to file.
531 C code can #include this to see the declarations.
533 The import path for the Go package. Optional; used for
534 nicer comments in the generated files.
536 If set (which it is by default) import runtime/cgo in
539 If set (which it is by default) import syscall in
542 Generate output for the gccgo compiler rather than the
545 The -fgo-prefix option to be used with gccgo.
547 The -fgo-pkgpath option to be used with gccgo.
548 -gccgo_define_cgoincomplete
549 Define cgo.Incomplete locally rather than importing it from
550 the "runtime/cgo" package. Used for old gccgo versions.
552 Write out input file in Go syntax replacing C package
553 names with real values. Used to generate files in the
554 syscall package when bootstrapping a new target.
556 Put all generated files in directory.
562 Implementation details.
564 Cgo provides a way for Go programs to call C code linked into the same
565 address space. This comment explains the operation of cgo.
567 Cgo reads a set of Go source files and looks for statements saying
568 import "C". If the import has a doc comment, that comment is
569 taken as literal C code to be used as a preamble to any C code
570 generated by cgo. A typical preamble #includes necessary definitions:
572 // #include <stdio.h>
575 For more details about the usage of cgo, see the documentation
576 comment at the top of this file.
580 Cgo scans the Go source files that import "C" for uses of that
581 package, such as C.puts. It collects all such identifiers. The next
582 step is to determine each kind of name. In C.xxx the xxx might refer
583 to a type, a function, a constant, or a global variable. Cgo must
586 The obvious thing for cgo to do is to process the preamble, expanding
587 #includes and processing the corresponding C code. That would require
588 a full C parser and type checker that was also aware of any extensions
589 known to the system compiler (for example, all the GNU C extensions) as
590 well as the system-specific header locations and system-specific
591 pre-#defined macros. This is certainly possible to do, but it is an
592 enormous amount of work.
594 Cgo takes a different approach. It determines the meaning of C
595 identifiers not by parsing C code but by feeding carefully constructed
596 programs into the system C compiler and interpreting the generated
597 error messages, debug information, and object files. In practice,
598 parsing these is significantly less work and more robust than parsing
601 Cgo first invokes gcc -E -dM on the preamble, in order to find out
602 about simple #defines for constants and the like. These are recorded
605 Next, cgo needs to identify the kinds for each identifier. For the
606 identifiers C.foo, cgo generates this C program:
609 #line 1 "not-declared"
610 void __cgo_f_1_1(void) { __typeof__(foo) *__cgo_undefined__1; }
612 void __cgo_f_1_2(void) { foo *__cgo_undefined__2; }
613 #line 1 "not-int-const"
614 void __cgo_f_1_3(void) { enum { __cgo_undefined__3 = (foo)*1 }; }
615 #line 1 "not-num-const"
616 void __cgo_f_1_4(void) { static const double __cgo_undefined__4 = (foo); }
617 #line 1 "not-str-lit"
618 void __cgo_f_1_5(void) { static const char __cgo_undefined__5[] = (foo); }
620 This program will not compile, but cgo can use the presence or absence
621 of an error message on a given line to deduce the information it
622 needs. The program is syntactically valid regardless of whether each
623 name is a type or an ordinary identifier, so there will be no syntax
624 errors that might stop parsing early.
626 An error on not-declared:1 indicates that foo is undeclared.
627 An error on not-type:1 indicates that foo is not a type (if declared at all, it is an identifier).
628 An error on not-int-const:1 indicates that foo is not an integer constant.
629 An error on not-num-const:1 indicates that foo is not a number constant.
630 An error on not-str-lit:1 indicates that foo is not a string literal.
631 An error on not-signed-int-const:1 indicates that foo is not a signed integer constant.
633 The line number specifies the name involved. In the example, 1 is foo.
635 Next, cgo must learn the details of each type, variable, function, or
636 constant. It can do this by reading object files. If cgo has decided
637 that t1 is a type, v2 and v3 are variables or functions, and i4, i5
638 are integer constants, u6 is an unsigned integer constant, and f7 and f8
639 are float constants, and s9 and s10 are string constants, it generates:
642 __typeof__(t1) *__cgo__1;
643 __typeof__(v2) *__cgo__2;
644 __typeof__(v3) *__cgo__3;
645 __typeof__(i4) *__cgo__4;
646 enum { __cgo_enum__4 = i4 };
647 __typeof__(i5) *__cgo__5;
648 enum { __cgo_enum__5 = i5 };
649 __typeof__(u6) *__cgo__6;
650 enum { __cgo_enum__6 = u6 };
651 __typeof__(f7) *__cgo__7;
652 __typeof__(f8) *__cgo__8;
653 __typeof__(s9) *__cgo__9;
654 __typeof__(s10) *__cgo__10;
656 long long __cgodebug_ints[] = {
670 double __cgodebug_floats[] = {
684 const char __cgodebug_str__9[] = s9;
685 const unsigned long long __cgodebug_strlen__9 = sizeof(s9)-1;
686 const char __cgodebug_str__10[] = s10;
687 const unsigned long long __cgodebug_strlen__10 = sizeof(s10)-1;
689 and again invokes the system C compiler, to produce an object file
690 containing debug information. Cgo parses the DWARF debug information
691 for __cgo__N to learn the type of each identifier. (The types also
692 distinguish functions from global variables.) Cgo reads the constant
693 values from the __cgodebug_* from the object file's data segment.
695 At this point cgo knows the meaning of each C.xxx well enough to start
696 the translation process.
700 Given the input Go files x.go and y.go, cgo generates these source
703 x.cgo1.go # for gc (cmd/compile)
705 _cgo_gotypes.go # for gc
706 _cgo_import.go # for gc (if -dynout _cgo_import.go)
709 _cgo_defun.c # for gcc (if -gccgo)
710 _cgo_export.c # for gcc
711 _cgo_export.h # for gcc
712 _cgo_main.c # for gcc
713 _cgo_flags # for build tool (if -gccgo)
715 The file x.cgo1.go is a copy of x.go with the import "C" removed and
716 references to C.xxx replaced with names like _Cfunc_xxx or _Ctype_xxx.
717 The definitions of those identifiers, written as Go functions, types,
718 or variables, are provided in _cgo_gotypes.go.
720 Here is a _cgo_gotypes.go containing definitions for needed C types:
722 type _Ctype_char int8
723 type _Ctype_int int32
724 type _Ctype_void [0]byte
726 The _cgo_gotypes.go file also contains the definitions of the
727 functions. They all have similar bodies that invoke runtime·cgocall
728 to make a switch from the Go runtime world to the system C (GCC-based)
731 For example, here is the definition of _Cfunc_puts:
733 //go:cgo_import_static _cgo_be59f0f25121_Cfunc_puts
734 //go:linkname __cgofn__cgo_be59f0f25121_Cfunc_puts _cgo_be59f0f25121_Cfunc_puts
735 var __cgofn__cgo_be59f0f25121_Cfunc_puts byte
736 var _cgo_be59f0f25121_Cfunc_puts = unsafe.Pointer(&__cgofn__cgo_be59f0f25121_Cfunc_puts)
738 func _Cfunc_puts(p0 *_Ctype_char) (r1 _Ctype_int) {
739 _cgo_runtime_cgocall(_cgo_be59f0f25121_Cfunc_puts, uintptr(unsafe.Pointer(&p0)))
743 The hexadecimal number is a hash of cgo's input, chosen to be
744 deterministic yet unlikely to collide with other uses. The actual
745 function _cgo_be59f0f25121_Cfunc_puts is implemented in a C source
746 file compiled by gcc, the file x.cgo2.c:
749 _cgo_be59f0f25121_Cfunc_puts(void *v)
755 } __attribute__((__packed__, __gcc_struct__)) *a = v;
756 a->r = puts((void*)a->p0);
759 It extracts the arguments from the pointer to _Cfunc_puts's argument
760 frame, invokes the system C function (in this case, puts), stores the
761 result in the frame, and returns.
765 Once the _cgo_export.c and *.cgo2.c files have been compiled with gcc,
766 they need to be linked into the final binary, along with the libraries
767 they might depend on (in the case of puts, stdio). cmd/link has been
768 extended to understand basic ELF files, but it does not understand ELF
769 in the full complexity that modern C libraries embrace, so it cannot
770 in general generate direct references to the system libraries.
772 Instead, the build process generates an object file using dynamic
773 linkage to the desired libraries. The main function is provided by
776 int main() { return 0; }
777 void crosscall2(void(*fn)(void*), void *a, int c, uintptr_t ctxt) { }
778 uintptr_t _cgo_wait_runtime_init_done(void) { return 0; }
779 void _cgo_release_context(uintptr_t ctxt) { }
780 char* _cgo_topofstack(void) { return (char*)0; }
781 void _cgo_allocate(void *a, int c) { }
782 void _cgo_panic(void *a, int c) { }
783 void _cgo_reginit(void) { }
785 The extra functions here are stubs to satisfy the references in the C
786 code generated for gcc. The build process links this stub, along with
787 _cgo_export.c and *.cgo2.c, into a dynamic executable and then lets
788 cgo examine the executable. Cgo records the list of shared library
789 references and resolved names and writes them into a new file
790 _cgo_import.go, which looks like:
792 //go:cgo_dynamic_linker "/lib64/ld-linux-x86-64.so.2"
793 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6"
794 //go:cgo_import_dynamic __libc_start_main __libc_start_main#GLIBC_2.2.5 "libc.so.6"
795 //go:cgo_import_dynamic stdout stdout#GLIBC_2.2.5 "libc.so.6"
796 //go:cgo_import_dynamic fflush fflush#GLIBC_2.2.5 "libc.so.6"
797 //go:cgo_import_dynamic _ _ "libpthread.so.0"
798 //go:cgo_import_dynamic _ _ "libc.so.6"
800 In the end, the compiled Go package, which will eventually be
801 presented to cmd/link as part of a larger program, contains:
803 _go_.o # gc-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go
804 _all.o # gcc-compiled object for _cgo_export.c, *.cgo2.c
806 If there is an error generating the _cgo_import.go file, then, instead
807 of adding _cgo_import.go to the package, the go tool adds an empty
808 file named dynimportfail. The _cgo_import.go file is only needed when
809 using internal linking mode, which is not the default when linking
810 programs that use cgo (as described below). If the linker sees a file
811 named dynimportfail it reports an error if it has been told to use
812 internal linking mode. This approach is taken because generating
813 _cgo_import.go requires doing a full C link of the package, which can
814 fail for reasons that are irrelevant when using external linking mode.
816 The final program will be a dynamic executable, so that cmd/link can avoid
817 needing to process arbitrary .o files. It only needs to process the .o
818 files generated from C files that cgo writes, and those are much more
819 limited in the ELF or other features that they use.
821 In essence, the _cgo_import.o file includes the extra linking
822 directives that cmd/link is not sophisticated enough to derive from _all.o
823 on its own. Similarly, the _all.o uses dynamic references to real
824 system object code because cmd/link is not sophisticated enough to process
827 The main benefits of this system are that cmd/link remains relatively simple
828 (it does not need to implement a complete ELF and Mach-O linker) and
829 that gcc is not needed after the package is compiled. For example,
830 package net uses cgo for access to name resolution functions provided
831 by libc. Although gcc is needed to compile package net, gcc is not
832 needed to link programs that import package net.
836 When using cgo, Go must not assume that it owns all details of the
837 process. In particular it needs to coordinate with C in the use of
838 threads and thread-local storage. The runtime package declares a few
843 _cgo_init unsafe.Pointer
844 _cgo_thread_start unsafe.Pointer
847 Any package using cgo imports "runtime/cgo", which provides
848 initializations for these variables. It sets iscgo to true, _cgo_init
849 to a gcc-compiled function that can be called early during program
850 startup, and _cgo_thread_start to a gcc-compiled function that can be
851 used to create a new thread, in place of the runtime's usual direct
854 Internal and External Linking
856 The text above describes "internal" linking, in which cmd/link parses and
857 links host object files (ELF, Mach-O, PE, and so on) into the final
858 executable itself. Keeping cmd/link simple means we cannot possibly
859 implement the full semantics of the host linker, so the kinds of
860 objects that can be linked directly into the binary is limited (other
861 code can only be used as a dynamic library). On the other hand, when
862 using internal linking, cmd/link can generate Go binaries by itself.
864 In order to allow linking arbitrary object files without requiring
865 dynamic libraries, cgo supports an "external" linking mode too. In
866 external linking mode, cmd/link does not process any host object files.
867 Instead, it collects all the Go code and writes a single go.o object
868 file containing it. Then it invokes the host linker (usually gcc) to
869 combine the go.o object file and any supporting non-Go code into a
870 final executable. External linking avoids the dynamic library
871 requirement but introduces a requirement that the host linker be
872 present to create such a binary.
874 Most builds both compile source code and invoke the linker to create a
875 binary. When cgo is involved, the compile step already requires gcc, so
876 it is not problematic for the link step to require gcc too.
878 An important exception is builds using a pre-compiled copy of the
879 standard library. In particular, package net uses cgo on most systems,
880 and we want to preserve the ability to compile pure Go code that
881 imports net without requiring gcc to be present at link time. (In this
882 case, the dynamic library requirement is less significant, because the
883 only library involved is libc.so, which can usually be assumed
886 This conflict between functionality and the gcc requirement means we
887 must support both internal and external linking, depending on the
888 circumstances: if net is the only cgo-using package, then internal
889 linking is probably fine, but if other packages are involved, so that there
890 are dependencies on libraries beyond libc, external linking is likely
891 to work better. The compilation of a package records the relevant
892 information to support both linking modes, leaving the decision
893 to be made when linking the final binary.
897 In either linking mode, package-specific directives must be passed
898 through to cmd/link. These are communicated by writing //go: directives in a
899 Go source file compiled by gc. The directives are copied into the .o
900 object file and then processed by the linker.
904 //go:cgo_import_dynamic <local> [<remote> ["<library>"]]
906 In internal linking mode, allow an unresolved reference to
907 <local>, assuming it will be resolved by a dynamic library
908 symbol. The optional <remote> specifies the symbol's name and
909 possibly version in the dynamic library, and the optional "<library>"
910 names the specific library where the symbol should be found.
912 On AIX, the library pattern is slightly different. It must be
913 "lib.a/obj.o" with obj.o the member of this library exporting
916 In the <remote>, # or @ can be used to introduce a symbol version.
919 //go:cgo_import_dynamic puts
920 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5
921 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6"
923 A side effect of the cgo_import_dynamic directive with a
924 library is to make the final binary depend on that dynamic
925 library. To get the dependency without importing any specific
926 symbols, use _ for local and remote.
929 //go:cgo_import_dynamic _ _ "libc.so.6"
931 For compatibility with current versions of SWIG,
932 #pragma dynimport is an alias for //go:cgo_import_dynamic.
934 //go:cgo_dynamic_linker "<path>"
936 In internal linking mode, use "<path>" as the dynamic linker
937 in the final binary. This directive is only needed from one
938 package when constructing a binary; by convention it is
939 supplied by runtime/cgo.
942 //go:cgo_dynamic_linker "/lib/ld-linux.so.2"
944 //go:cgo_export_dynamic <local> <remote>
946 In internal linking mode, put the Go symbol
947 named <local> into the program's exported symbol table as
948 <remote>, so that C code can refer to it by that name. This
949 mechanism makes it possible for C code to call back into Go or
952 For compatibility with current versions of SWIG,
953 #pragma dynexport is an alias for //go:cgo_export_dynamic.
955 //go:cgo_import_static <local>
957 In external linking mode, allow unresolved references to
958 <local> in the go.o object file prepared for the host linker,
959 under the assumption that <local> will be supplied by the
960 other object files that will be linked with go.o.
963 //go:cgo_import_static puts_wrapper
965 //go:cgo_export_static <local> <remote>
967 In external linking mode, put the Go symbol
968 named <local> into the program's exported symbol table as
969 <remote>, so that C code can refer to it by that name. This
970 mechanism makes it possible for C code to call back into Go or
973 //go:cgo_ldflag "<arg>"
975 In external linking mode, invoke the host linker (usually gcc)
976 with "<arg>" as a command-line argument following the .o files.
977 Note that the arguments are for "gcc", not "ld".
980 //go:cgo_ldflag "-lpthread"
981 //go:cgo_ldflag "-L/usr/local/sqlite3/lib"
983 A package compiled with cgo will include directives for both
984 internal and external linking; the linker will select the appropriate
985 subset for the chosen linking mode.
989 As a simple example, consider a package that uses cgo to call C.sin.
990 The following code will be generated by cgo:
994 //go:cgo_ldflag "-lm"
996 type _Ctype_double float64
998 //go:cgo_import_static _cgo_gcc_Cfunc_sin
999 //go:linkname __cgo_gcc_Cfunc_sin _cgo_gcc_Cfunc_sin
1000 var __cgo_gcc_Cfunc_sin byte
1001 var _cgo_gcc_Cfunc_sin = unsafe.Pointer(&__cgo_gcc_Cfunc_sin)
1003 func _Cfunc_sin(p0 _Ctype_double) (r1 _Ctype_double) {
1004 _cgo_runtime_cgocall(_cgo_gcc_Cfunc_sin, uintptr(unsafe.Pointer(&p0)))
1008 // compiled by gcc, into foo.cgo2.o
1011 _cgo_gcc_Cfunc_sin(void *v)
1016 } __attribute__((__packed__)) *a = v;
1020 What happens at link time depends on whether the final binary is linked
1021 using the internal or external mode. If other packages are compiled in
1022 "external only" mode, then the final link will be an external one.
1023 Otherwise the link will be an internal one.
1025 The linking directives are used according to the kind of final link
1028 In internal mode, cmd/link itself processes all the host object files, in
1029 particular foo.cgo2.o. To do so, it uses the cgo_import_dynamic and
1030 cgo_dynamic_linker directives to learn that the otherwise undefined
1031 reference to sin in foo.cgo2.o should be rewritten to refer to the
1032 symbol sin with version GLIBC_2.2.5 from the dynamic library
1033 "libm.so.6", and the binary should request "/lib/ld-linux.so.2" as its
1034 runtime dynamic linker.
1036 In external mode, cmd/link does not process any host object files, in
1037 particular foo.cgo2.o. It links together the gc-generated object
1038 files, along with any other Go code, into a go.o file. While doing
1039 that, cmd/link will discover that there is no definition for
1040 _cgo_gcc_Cfunc_sin, referred to by the gc-compiled source file. This
1041 is okay, because cmd/link also processes the cgo_import_static directive and
1042 knows that _cgo_gcc_Cfunc_sin is expected to be supplied by a host
1043 object file, so cmd/link does not treat the missing symbol as an error when
1044 creating go.o. Indeed, the definition for _cgo_gcc_Cfunc_sin will be
1045 provided to the host linker by foo2.cgo.o, which in turn will need the
1046 symbol 'sin'. cmd/link also processes the cgo_ldflag directives, so that it
1047 knows that the eventual host link command must include the -lm
1048 argument, so that the host linker will be able to find 'sin' in the
1051 cmd/link Command Line Interface
1053 The go command and any other Go-aware build systems invoke cmd/link
1054 to link a collection of packages into a single binary. By default, cmd/link will
1055 present the same interface it does today:
1059 produces a file named a.out, even if cmd/link does so by invoking the host
1060 linker in external linking mode.
1062 By default, cmd/link will decide the linking mode as follows: if the only
1063 packages using cgo are those on a list of known standard library
1064 packages (net, os/user, runtime/cgo), cmd/link will use internal linking
1065 mode. Otherwise, there are non-standard cgo packages involved, and cmd/link
1066 will use external linking mode. The first rule means that a build of
1067 the godoc binary, which uses net but no other cgo, can run without
1068 needing gcc available. The second rule means that a build of a
1069 cgo-wrapped library like sqlite3 can generate a standalone executable
1070 instead of needing to refer to a dynamic library. The specific choice
1071 can be overridden using a command line flag: cmd/link -linkmode=internal or
1072 cmd/link -linkmode=external.
1074 In an external link, cmd/link will create a temporary directory, write any
1075 host object files found in package archives to that directory (renamed
1076 to avoid conflicts), write the go.o file to that directory, and invoke
1077 the host linker. The default value for the host linker is $CC, split
1078 into fields, or else "gcc". The specific host linker command line can
1079 be overridden using command line flags: cmd/link -extld=clang
1080 -extldflags='-ggdb -O3'. If any package in a build includes a .cc or
1081 other file compiled by the C++ compiler, the go tool will use the
1082 -extld option to set the host linker to the C++ compiler.
1084 These defaults mean that Go-aware build systems can ignore the linking
1085 changes and keep running plain 'cmd/link' and get reasonable results, but
1086 they can also control the linking details if desired.