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. 4 5 /* 6 7 Cgo enables the creation of Go packages that call C code. 8 9 Using cgo with the go command 10 11 To use cgo write normal Go code that imports a pseudo-package "C". 12 The Go code can then refer to types such as C.size_t, variables such 13 as C.stdout, or functions such as C.putchar. 14 15 If the import of "C" is immediately preceded by a comment, that 16 comment, called the preamble, is used as a header when compiling 17 the C parts of the package. For example: 18 19 // #include <stdio.h> 20 // #include <errno.h> 21 import "C" 22 23 The preamble may contain any C code, including function and variable 24 declarations and definitions. These may then be referred to from Go 25 code as though they were defined in the package "C". All names 26 declared in the preamble may be used, even if they start with a 27 lower-case letter. Exception: static variables in the preamble may 28 not be referenced from Go code; static functions are permitted. 29 30 See $GOROOT/misc/cgo/stdio and $GOROOT/misc/cgo/gmp for examples. See 31 "C? Go? Cgo!" for an introduction to using cgo: 32 https://golang.org/doc/articles/c_go_cgo.html. 33 34 CFLAGS, CPPFLAGS, CXXFLAGS, FFLAGS and LDFLAGS may be defined with pseudo 35 #cgo directives within these comments to tweak the behavior of the C, C++ 36 or Fortran compiler. Values defined in multiple directives are concatenated 37 together. The directive can include a list of build constraints limiting its 38 effect to systems satisfying one of the constraints 39 (see https://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax). 40 For example: 41 42 // #cgo CFLAGS: -DPNG_DEBUG=1 43 // #cgo amd64 386 CFLAGS: -DX86=1 44 // #cgo LDFLAGS: -lpng 45 // #include <png.h> 46 import "C" 47 48 Alternatively, CPPFLAGS and LDFLAGS may be obtained via the pkg-config tool 49 using a '#cgo pkg-config:' directive followed by the package names. 50 For example: 51 52 // #cgo pkg-config: png cairo 53 // #include <png.h> 54 import "C" 55 56 The default pkg-config tool may be changed by setting the PKG_CONFIG environment variable. 57 58 For security reasons, only a limited set of flags are allowed, notably -D, -I, and -l. 59 To allow additional flags, set CGO_CFLAGS_ALLOW to a regular expression 60 matching the new flags. To disallow flags that would otherwise be allowed, 61 set CGO_CFLAGS_DISALLOW to a regular expression matching arguments 62 that must be disallowed. In both cases the regular expression must match 63 a full argument: to allow -mfoo=bar, use CGO_CFLAGS_ALLOW='-mfoo.*', 64 not just CGO_CFLAGS_ALLOW='-mfoo'. Similarly named variables control 65 the allowed CPPFLAGS, CXXFLAGS, FFLAGS, and LDFLAGS. 66 67 Also for security reasons, only a limited set of characters are 68 permitted, notably alphanumeric characters and a few symbols, such as 69 '.', that will not be interpreted in unexpected ways. Attempts to use 70 forbidden characters will get a "malformed #cgo argument" error. 71 72 When building, the CGO_CFLAGS, CGO_CPPFLAGS, CGO_CXXFLAGS, CGO_FFLAGS and 73 CGO_LDFLAGS environment variables are added to the flags derived from 74 these directives. Package-specific flags should be set using the 75 directives, not the environment variables, so that builds work in 76 unmodified environments. Flags obtained from environment variables 77 are not subject to the security limitations described above. 78 79 All the cgo CPPFLAGS and CFLAGS directives in a package are concatenated and 80 used to compile C files in that package. All the CPPFLAGS and CXXFLAGS 81 directives in a package are concatenated and used to compile C++ files in that 82 package. All the CPPFLAGS and FFLAGS directives in a package are concatenated 83 and used to compile Fortran files in that package. All the LDFLAGS directives 84 in any package in the program are concatenated and used at link time. All the 85 pkg-config directives are concatenated and sent to pkg-config simultaneously 86 to add to each appropriate set of command-line flags. 87 88 When the cgo directives are parsed, any occurrence of the string ${SRCDIR} 89 will be replaced by the absolute path to the directory containing the source 90 file. This allows pre-compiled static libraries to be included in the package 91 directory and linked properly. 92 For example if package foo is in the directory /go/src/foo: 93 94 // #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo 95 96 Will be expanded to: 97 98 // #cgo LDFLAGS: -L/go/src/foo/libs -lfoo 99 100 When the Go tool sees that one or more Go files use the special import 101 "C", it will look for other non-Go files in the directory and compile 102 them as part of the Go package. Any .c, .s, or .S files will be 103 compiled with the C compiler. Any .cc, .cpp, or .cxx files will be 104 compiled with the C++ compiler. Any .f, .F, .for or .f90 files will be 105 compiled with the fortran compiler. Any .h, .hh, .hpp, or .hxx files will 106 not be compiled separately, but, if these header files are changed, 107 the package (including its non-Go source files) will be recompiled. 108 Note that changes to files in other directories do not cause the package 109 to be recompiled, so all non-Go source code for the package should be 110 stored in the package directory, not in subdirectories. 111 The default C and C++ compilers may be changed by the CC and CXX 112 environment variables, respectively; those environment variables 113 may include command line options. 114 115 The cgo tool is enabled by default for native builds on systems where 116 it is expected to work. It is disabled by default when 117 cross-compiling. You can control this by setting the CGO_ENABLED 118 environment variable when running the go tool: set it to 1 to enable 119 the use of cgo, and to 0 to disable it. The go tool will set the 120 build constraint "cgo" if cgo is enabled. The special import "C" 121 implies the "cgo" build constraint, as though the file also said 122 "// +build cgo". Therefore, if cgo is disabled, files that import 123 "C" will not be built by the go tool. (For more about build constraints 124 see https://golang.org/pkg/go/build/#hdr-Build_Constraints). 125 126 When cross-compiling, you must specify a C cross-compiler for cgo to 127 use. You can do this by setting the generic CC_FOR_TARGET or the 128 more specific CC_FOR_${GOOS}_${GOARCH} (for example, CC_FOR_linux_arm) 129 environment variable when building the toolchain using make.bash, 130 or you can set the CC environment variable any time you run the go tool. 131 132 The CXX_FOR_TARGET, CXX_FOR_${GOOS}_${GOARCH}, and CXX 133 environment variables work in a similar way for C++ code. 134 135 Go references to C 136 137 Within the Go file, C's struct field names that are keywords in Go 138 can be accessed by prefixing them with an underscore: if x points at a C 139 struct with a field named "type", x._type accesses the field. 140 C struct fields that cannot be expressed in Go, such as bit fields 141 or misaligned data, are omitted in the Go struct, replaced by 142 appropriate padding to reach the next field or the end of the struct. 143 144 The standard C numeric types are available under the names 145 C.char, C.schar (signed char), C.uchar (unsigned char), 146 C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int), 147 C.long, C.ulong (unsigned long), C.longlong (long long), 148 C.ulonglong (unsigned long long), C.float, C.double, 149 C.complexfloat (complex float), and C.complexdouble (complex double). 150 The C type void* is represented by Go's unsafe.Pointer. 151 The C types __int128_t and __uint128_t are represented by [16]byte. 152 153 A few special C types which would normally be represented by a pointer 154 type in Go are instead represented by a uintptr. See the Special 155 cases section below. 156 157 To access a struct, union, or enum type directly, prefix it with 158 struct_, union_, or enum_, as in C.struct_stat. 159 160 The size of any C type T is available as C.sizeof_T, as in 161 C.sizeof_struct_stat. 162 163 A C function may be declared in the Go file with a parameter type of 164 the special name _GoString_. This function may be called with an 165 ordinary Go string value. The string length, and a pointer to the 166 string contents, may be accessed by calling the C functions 167 168 size_t _GoStringLen(_GoString_ s); 169 const char *_GoStringPtr(_GoString_ s); 170 171 These functions are only available in the preamble, not in other C 172 files. The C code must not modify the contents of the pointer returned 173 by _GoStringPtr. Note that the string contents may not have a trailing 174 NUL byte. 175 176 As Go doesn't have support for C's union type in the general case, 177 C's union types are represented as a Go byte array with the same length. 178 179 Go structs cannot embed fields with C types. 180 181 Go code cannot refer to zero-sized fields that occur at the end of 182 non-empty C structs. To get the address of such a field (which is the 183 only operation you can do with a zero-sized field) you must take the 184 address of the struct and add the size of the struct. 185 186 Cgo translates C types into equivalent unexported Go types. 187 Because the translations are unexported, a Go package should not 188 expose C types in its exported API: a C type used in one Go package 189 is different from the same C type used in another. 190 191 Any C function (even void functions) may be called in a multiple 192 assignment context to retrieve both the return value (if any) and the 193 C errno variable as an error (use _ to skip the result value if the 194 function returns void). For example: 195 196 n, err = C.sqrt(-1) 197 _, err := C.voidFunc() 198 var n, err = C.sqrt(1) 199 200 Calling C function pointers is currently not supported, however you can 201 declare Go variables which hold C function pointers and pass them 202 back and forth between Go and C. C code may call function pointers 203 received from Go. For example: 204 205 package main 206 207 // typedef int (*intFunc) (); 208 // 209 // int 210 // bridge_int_func(intFunc f) 211 // { 212 // return f(); 213 // } 214 // 215 // int fortytwo() 216 // { 217 // return 42; 218 // } 219 import "C" 220 import "fmt" 221 222 func main() { 223 f := C.intFunc(C.fortytwo) 224 fmt.Println(int(C.bridge_int_func(f))) 225 // Output: 42 226 } 227 228 In C, a function argument written as a fixed size array 229 actually requires a pointer to the first element of the array. 230 C compilers are aware of this calling convention and adjust 231 the call accordingly, but Go cannot. In Go, you must pass 232 the pointer to the first element explicitly: C.f(&C.x[0]). 233 234 Calling variadic C functions is not supported. It is possible to 235 circumvent this by using a C function wrapper. For example: 236 237 package main 238 239 // #include <stdio.h> 240 // #include <stdlib.h> 241 // 242 // static void myprint(char* s) { 243 // printf("%s\n", s); 244 // } 245 import "C" 246 import "unsafe" 247 248 func main() { 249 cs := C.CString("Hello from stdio") 250 C.myprint(cs) 251 C.free(unsafe.Pointer(cs)) 252 } 253 254 A few special functions convert between Go and C types 255 by making copies of the data. In pseudo-Go definitions: 256 257 // Go string to C string 258 // The C string is allocated in the C heap using malloc. 259 // It is the caller's responsibility to arrange for it to be 260 // freed, such as by calling C.free (be sure to include stdlib.h 261 // if C.free is needed). 262 func C.CString(string) *C.char 263 264 // Go []byte slice to C array 265 // The C array is allocated in the C heap using malloc. 266 // It is the caller's responsibility to arrange for it to be 267 // freed, such as by calling C.free (be sure to include stdlib.h 268 // if C.free is needed). 269 func C.CBytes([]byte) unsafe.Pointer 270 271 // C string to Go string 272 func C.GoString(*C.char) string 273 274 // C data with explicit length to Go string 275 func C.GoStringN(*C.char, C.int) string 276 277 // C data with explicit length to Go []byte 278 func C.GoBytes(unsafe.Pointer, C.int) []byte 279 280 As a special case, C.malloc does not call the C library malloc directly 281 but instead calls a Go helper function that wraps the C library malloc 282 but guarantees never to return nil. If C's malloc indicates out of memory, 283 the helper function crashes the program, like when Go itself runs out 284 of memory. Because C.malloc cannot fail, it has no two-result form 285 that returns errno. 286 287 C references to Go 288 289 Go functions can be exported for use by C code in the following way: 290 291 //export MyFunction 292 func MyFunction(arg1, arg2 int, arg3 string) int64 {...} 293 294 //export MyFunction2 295 func MyFunction2(arg1, arg2 int, arg3 string) (int64, *C.char) {...} 296 297 They will be available in the C code as: 298 299 extern int64 MyFunction(int arg1, int arg2, GoString arg3); 300 extern struct MyFunction2_return MyFunction2(int arg1, int arg2, GoString arg3); 301 302 found in the _cgo_export.h generated header, after any preambles 303 copied from the cgo input files. Functions with multiple 304 return values are mapped to functions returning a struct. 305 306 Not all Go types can be mapped to C types in a useful way. 307 Go struct types are not supported; use a C struct type. 308 Go array types are not supported; use a C pointer. 309 310 Go functions that take arguments of type string may be called with the 311 C type _GoString_, described above. The _GoString_ type will be 312 automatically defined in the preamble. Note that there is no way for C 313 code to create a value of this type; this is only useful for passing 314 string values from Go to C and back to Go. 315 316 Using //export in a file places a restriction on the preamble: 317 since it is copied into two different C output files, it must not 318 contain any definitions, only declarations. If a file contains both 319 definitions and declarations, then the two output files will produce 320 duplicate symbols and the linker will fail. To avoid this, definitions 321 must be placed in preambles in other files, or in C source files. 322 323 Passing pointers 324 325 Go is a garbage collected language, and the garbage collector needs to 326 know the location of every pointer to Go memory. Because of this, 327 there are restrictions on passing pointers between Go and C. 328 329 In this section the term Go pointer means a pointer to memory 330 allocated by Go (such as by using the & operator or calling the 331 predefined new function) and the term C pointer means a pointer to 332 memory allocated by C (such as by a call to C.malloc). Whether a 333 pointer is a Go pointer or a C pointer is a dynamic property 334 determined by how the memory was allocated; it has nothing to do with 335 the type of the pointer. 336 337 Note that values of some Go types, other than the type's zero value, 338 always include Go pointers. This is true of string, slice, interface, 339 channel, map, and function types. A pointer type may hold a Go pointer 340 or a C pointer. Array and struct types may or may not include Go 341 pointers, depending on the element types. All the discussion below 342 about Go pointers applies not just to pointer types, but also to other 343 types that include Go pointers. 344 345 Go code may pass a Go pointer to C provided the Go memory to which it 346 points does not contain any Go pointers. The C code must preserve 347 this property: it must not store any Go pointers in Go memory, even 348 temporarily. When passing a pointer to a field in a struct, the Go 349 memory in question is the memory occupied by the field, not the entire 350 struct. When passing a pointer to an element in an array or slice, 351 the Go memory in question is the entire array or the entire backing 352 array of the slice. 353 354 C code may not keep a copy of a Go pointer after the call returns. 355 This includes the _GoString_ type, which, as noted above, includes a 356 Go pointer; _GoString_ values may not be retained by C code. 357 358 A Go function called by C code may not return a Go pointer (which 359 implies that it may not return a string, slice, channel, and so 360 forth). A Go function called by C code may take C pointers as 361 arguments, and it may store non-pointer or C pointer data through 362 those pointers, but it may not store a Go pointer in memory pointed to 363 by a C pointer. A Go function called by C code may take a Go pointer 364 as an argument, but it must preserve the property that the Go memory 365 to which it points does not contain any Go pointers. 366 367 Go code may not store a Go pointer in C memory. C code may store Go 368 pointers in C memory, subject to the rule above: it must stop storing 369 the Go pointer when the C function returns. 370 371 These rules are checked dynamically at runtime. The checking is 372 controlled by the cgocheck setting of the GODEBUG environment 373 variable. The default setting is GODEBUG=cgocheck=1, which implements 374 reasonably cheap dynamic checks. These checks may be disabled 375 entirely using GODEBUG=cgocheck=0. Complete checking of pointer 376 handling, at some cost in run time, is available via GODEBUG=cgocheck=2. 377 378 It is possible to defeat this enforcement by using the unsafe package, 379 and of course there is nothing stopping the C code from doing anything 380 it likes. However, programs that break these rules are likely to fail 381 in unexpected and unpredictable ways. 382 383 Note: the current implementation has a bug. While Go code is permitted 384 to write nil or a C pointer (but not a Go pointer) to C memory, the 385 current implementation may sometimes cause a runtime error if the 386 contents of the C memory appear to be a Go pointer. Therefore, avoid 387 passing uninitialized C memory to Go code if the Go code is going to 388 store pointer values in it. Zero out the memory in C before passing it 389 to Go. 390 391 Special cases 392 393 A few special C types which would normally be represented by a pointer 394 type in Go are instead represented by a uintptr. Those include: 395 396 1. The *Ref types on Darwin, rooted at CoreFoundation's CFTypeRef type. 397 398 2. The object types from Java's JNI interface: 399 400 jobject 401 jclass 402 jthrowable 403 jstring 404 jarray 405 jbooleanArray 406 jbyteArray 407 jcharArray 408 jshortArray 409 jintArray 410 jlongArray 411 jfloatArray 412 jdoubleArray 413 jobjectArray 414 jweak 415 416 These types are uintptr on the Go side because they would otherwise 417 confuse the Go garbage collector; they are sometimes not really 418 pointers but data structures encoded in a pointer type. All operations 419 on these types must happen in C. The proper constant to initialize an 420 empty such reference is 0, not nil. 421 422 These special cases were introduced in Go 1.10. For auto-updating code 423 from Go 1.9 and earlier, use the cftype or jni rewrites in the Go fix tool: 424 425 go tool fix -r cftype <pkg> 426 go tool fix -r jni <pkg> 427 428 It will replace nil with 0 in the appropriate places. 429 430 Using cgo directly 431 432 Usage: 433 go tool cgo [cgo options] [-- compiler options] gofiles... 434 435 Cgo transforms the specified input Go source files into several output 436 Go and C source files. 437 438 The compiler options are passed through uninterpreted when 439 invoking the C compiler to compile the C parts of the package. 440 441 The following options are available when running cgo directly: 442 443 -V 444 Print cgo version and exit. 445 -debug-define 446 Debugging option. Print #defines. 447 -debug-gcc 448 Debugging option. Trace C compiler execution and output. 449 -dynimport file 450 Write list of symbols imported by file. Write to 451 -dynout argument or to standard output. Used by go 452 build when building a cgo package. 453 -dynlinker 454 Write dynamic linker as part of -dynimport output. 455 -dynout file 456 Write -dynimport output to file. 457 -dynpackage package 458 Set Go package for -dynimport output. 459 -exportheader file 460 If there are any exported functions, write the 461 generated export declarations to file. 462 C code can #include this to see the declarations. 463 -importpath string 464 The import path for the Go package. Optional; used for 465 nicer comments in the generated files. 466 -import_runtime_cgo 467 If set (which it is by default) import runtime/cgo in 468 generated output. 469 -import_syscall 470 If set (which it is by default) import syscall in 471 generated output. 472 -gccgo 473 Generate output for the gccgo compiler rather than the 474 gc compiler. 475 -gccgoprefix prefix 476 The -fgo-prefix option to be used with gccgo. 477 -gccgopkgpath path 478 The -fgo-pkgpath option to be used with gccgo. 479 -godefs 480 Write out input file in Go syntax replacing C package 481 names with real values. Used to generate files in the 482 syscall package when bootstrapping a new target. 483 -objdir directory 484 Put all generated files in directory. 485 -srcdir directory 486 */ 487 package main 488 489 /* 490 Implementation details. 491 492 Cgo provides a way for Go programs to call C code linked into the same 493 address space. This comment explains the operation of cgo. 494 495 Cgo reads a set of Go source files and looks for statements saying 496 import "C". If the import has a doc comment, that comment is 497 taken as literal C code to be used as a preamble to any C code 498 generated by cgo. A typical preamble #includes necessary definitions: 499 500 // #include <stdio.h> 501 import "C" 502 503 For more details about the usage of cgo, see the documentation 504 comment at the top of this file. 505 506 Understanding C 507 508 Cgo scans the Go source files that import "C" for uses of that 509 package, such as C.puts. It collects all such identifiers. The next 510 step is to determine each kind of name. In C.xxx the xxx might refer 511 to a type, a function, a constant, or a global variable. Cgo must 512 decide which. 513 514 The obvious thing for cgo to do is to process the preamble, expanding 515 #includes and processing the corresponding C code. That would require 516 a full C parser and type checker that was also aware of any extensions 517 known to the system compiler (for example, all the GNU C extensions) as 518 well as the system-specific header locations and system-specific 519 pre-#defined macros. This is certainly possible to do, but it is an 520 enormous amount of work. 521 522 Cgo takes a different approach. It determines the meaning of C 523 identifiers not by parsing C code but by feeding carefully constructed 524 programs into the system C compiler and interpreting the generated 525 error messages, debug information, and object files. In practice, 526 parsing these is significantly less work and more robust than parsing 527 C source. 528 529 Cgo first invokes gcc -E -dM on the preamble, in order to find out 530 about simple #defines for constants and the like. These are recorded 531 for later use. 532 533 Next, cgo needs to identify the kinds for each identifier. For the 534 identifiers C.foo, cgo generates this C program: 535 536 <preamble> 537 #line 1 "not-declared" 538 void __cgo_f_1_1(void) { __typeof__(foo) *__cgo_undefined__1; } 539 #line 1 "not-type" 540 void __cgo_f_1_2(void) { foo *__cgo_undefined__2; } 541 #line 1 "not-int-const" 542 void __cgo_f_1_3(void) { enum { __cgo_undefined__3 = (foo)*1 }; } 543 #line 1 "not-num-const" 544 void __cgo_f_1_4(void) { static const double __cgo_undefined__4 = (foo); } 545 #line 1 "not-str-lit" 546 void __cgo_f_1_5(void) { static const char __cgo_undefined__5[] = (foo); } 547 548 This program will not compile, but cgo can use the presence or absence 549 of an error message on a given line to deduce the information it 550 needs. The program is syntactically valid regardless of whether each 551 name is a type or an ordinary identifier, so there will be no syntax 552 errors that might stop parsing early. 553 554 An error on not-declared:1 indicates that foo is undeclared. 555 An error on not-type:1 indicates that foo is not a type (if declared at all, it is an identifier). 556 An error on not-int-const:1 indicates that foo is not an integer constant. 557 An error on not-num-const:1 indicates that foo is not a number constant. 558 An error on not-str-lit:1 indicates that foo is not a string literal. 559 An error on not-signed-int-const:1 indicates that foo is not a signed integer constant. 560 561 The line number specifies the name involved. In the example, 1 is foo. 562 563 Next, cgo must learn the details of each type, variable, function, or 564 constant. It can do this by reading object files. If cgo has decided 565 that t1 is a type, v2 and v3 are variables or functions, and i4, i5 566 are integer constants, u6 is an unsigned integer constant, and f7 and f8 567 are float constants, and s9 and s10 are string constants, it generates: 568 569 <preamble> 570 __typeof__(t1) *__cgo__1; 571 __typeof__(v2) *__cgo__2; 572 __typeof__(v3) *__cgo__3; 573 __typeof__(i4) *__cgo__4; 574 enum { __cgo_enum__4 = i4 }; 575 __typeof__(i5) *__cgo__5; 576 enum { __cgo_enum__5 = i5 }; 577 __typeof__(u6) *__cgo__6; 578 enum { __cgo_enum__6 = u6 }; 579 __typeof__(f7) *__cgo__7; 580 __typeof__(f8) *__cgo__8; 581 __typeof__(s9) *__cgo__9; 582 __typeof__(s10) *__cgo__10; 583 584 long long __cgodebug_ints[] = { 585 0, // t1 586 0, // v2 587 0, // v3 588 i4, 589 i5, 590 u6, 591 0, // f7 592 0, // f8 593 0, // s9 594 0, // s10 595 1 596 }; 597 598 double __cgodebug_floats[] = { 599 0, // t1 600 0, // v2 601 0, // v3 602 0, // i4 603 0, // i5 604 0, // u6 605 f7, 606 f8, 607 0, // s9 608 0, // s10 609 1 610 }; 611 612 const char __cgodebug_str__9[] = s9; 613 const unsigned long long __cgodebug_strlen__9 = sizeof(s9)-1; 614 const char __cgodebug_str__10[] = s10; 615 const unsigned long long __cgodebug_strlen__10 = sizeof(s10)-1; 616 617 and again invokes the system C compiler, to produce an object file 618 containing debug information. Cgo parses the DWARF debug information 619 for __cgo__N to learn the type of each identifier. (The types also 620 distinguish functions from global variables.) Cgo reads the constant 621 values from the __cgodebug_* from the object file's data segment. 622 623 At this point cgo knows the meaning of each C.xxx well enough to start 624 the translation process. 625 626 Translating Go 627 628 Given the input Go files x.go and y.go, cgo generates these source 629 files: 630 631 x.cgo1.go # for gc (cmd/compile) 632 y.cgo1.go # for gc 633 _cgo_gotypes.go # for gc 634 _cgo_import.go # for gc (if -dynout _cgo_import.go) 635 x.cgo2.c # for gcc 636 y.cgo2.c # for gcc 637 _cgo_defun.c # for gcc (if -gccgo) 638 _cgo_export.c # for gcc 639 _cgo_export.h # for gcc 640 _cgo_main.c # for gcc 641 _cgo_flags # for alternative build tools 642 643 The file x.cgo1.go is a copy of x.go with the import "C" removed and 644 references to C.xxx replaced with names like _Cfunc_xxx or _Ctype_xxx. 645 The definitions of those identifiers, written as Go functions, types, 646 or variables, are provided in _cgo_gotypes.go. 647 648 Here is a _cgo_gotypes.go containing definitions for needed C types: 649 650 type _Ctype_char int8 651 type _Ctype_int int32 652 type _Ctype_void [0]byte 653 654 The _cgo_gotypes.go file also contains the definitions of the 655 functions. They all have similar bodies that invoke runtime·cgocall 656 to make a switch from the Go runtime world to the system C (GCC-based) 657 world. 658 659 For example, here is the definition of _Cfunc_puts: 660 661 //go:cgo_import_static _cgo_be59f0f25121_Cfunc_puts 662 //go:linkname __cgofn__cgo_be59f0f25121_Cfunc_puts _cgo_be59f0f25121_Cfunc_puts 663 var __cgofn__cgo_be59f0f25121_Cfunc_puts byte 664 var _cgo_be59f0f25121_Cfunc_puts = unsafe.Pointer(&__cgofn__cgo_be59f0f25121_Cfunc_puts) 665 666 func _Cfunc_puts(p0 *_Ctype_char) (r1 _Ctype_int) { 667 _cgo_runtime_cgocall(_cgo_be59f0f25121_Cfunc_puts, uintptr(unsafe.Pointer(&p0))) 668 return 669 } 670 671 The hexadecimal number is a hash of cgo's input, chosen to be 672 deterministic yet unlikely to collide with other uses. The actual 673 function _cgo_be59f0f25121_Cfunc_puts is implemented in a C source 674 file compiled by gcc, the file x.cgo2.c: 675 676 void 677 _cgo_be59f0f25121_Cfunc_puts(void *v) 678 { 679 struct { 680 char* p0; 681 int r; 682 char __pad12[4]; 683 } __attribute__((__packed__, __gcc_struct__)) *a = v; 684 a->r = puts((void*)a->p0); 685 } 686 687 It extracts the arguments from the pointer to _Cfunc_puts's argument 688 frame, invokes the system C function (in this case, puts), stores the 689 result in the frame, and returns. 690 691 Linking 692 693 Once the _cgo_export.c and *.cgo2.c files have been compiled with gcc, 694 they need to be linked into the final binary, along with the libraries 695 they might depend on (in the case of puts, stdio). cmd/link has been 696 extended to understand basic ELF files, but it does not understand ELF 697 in the full complexity that modern C libraries embrace, so it cannot 698 in general generate direct references to the system libraries. 699 700 Instead, the build process generates an object file using dynamic 701 linkage to the desired libraries. The main function is provided by 702 _cgo_main.c: 703 704 int main() { return 0; } 705 void crosscall2(void(*fn)(void*, int, uintptr_t), void *a, int c, uintptr_t ctxt) { } 706 uintptr_t _cgo_wait_runtime_init_done() { return 0; } 707 void _cgo_release_context(uintptr_t ctxt) { } 708 char* _cgo_topofstack(void) { return (char*)0; } 709 void _cgo_allocate(void *a, int c) { } 710 void _cgo_panic(void *a, int c) { } 711 void _cgo_reginit(void) { } 712 713 The extra functions here are stubs to satisfy the references in the C 714 code generated for gcc. The build process links this stub, along with 715 _cgo_export.c and *.cgo2.c, into a dynamic executable and then lets 716 cgo examine the executable. Cgo records the list of shared library 717 references and resolved names and writes them into a new file 718 _cgo_import.go, which looks like: 719 720 //go:cgo_dynamic_linker "/lib64/ld-linux-x86-64.so.2" 721 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6" 722 //go:cgo_import_dynamic __libc_start_main __libc_start_main#GLIBC_2.2.5 "libc.so.6" 723 //go:cgo_import_dynamic stdout stdout#GLIBC_2.2.5 "libc.so.6" 724 //go:cgo_import_dynamic fflush fflush#GLIBC_2.2.5 "libc.so.6" 725 //go:cgo_import_dynamic _ _ "libpthread.so.0" 726 //go:cgo_import_dynamic _ _ "libc.so.6" 727 728 In the end, the compiled Go package, which will eventually be 729 presented to cmd/link as part of a larger program, contains: 730 731 _go_.o # gc-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go 732 _all.o # gcc-compiled object for _cgo_export.c, *.cgo2.c 733 734 The final program will be a dynamic executable, so that cmd/link can avoid 735 needing to process arbitrary .o files. It only needs to process the .o 736 files generated from C files that cgo writes, and those are much more 737 limited in the ELF or other features that they use. 738 739 In essence, the _cgo_import.o file includes the extra linking 740 directives that cmd/link is not sophisticated enough to derive from _all.o 741 on its own. Similarly, the _all.o uses dynamic references to real 742 system object code because cmd/link is not sophisticated enough to process 743 the real code. 744 745 The main benefits of this system are that cmd/link remains relatively simple 746 (it does not need to implement a complete ELF and Mach-O linker) and 747 that gcc is not needed after the package is compiled. For example, 748 package net uses cgo for access to name resolution functions provided 749 by libc. Although gcc is needed to compile package net, gcc is not 750 needed to link programs that import package net. 751 752 Runtime 753 754 When using cgo, Go must not assume that it owns all details of the 755 process. In particular it needs to coordinate with C in the use of 756 threads and thread-local storage. The runtime package declares a few 757 variables: 758 759 var ( 760 iscgo bool 761 _cgo_init unsafe.Pointer 762 _cgo_thread_start unsafe.Pointer 763 ) 764 765 Any package using cgo imports "runtime/cgo", which provides 766 initializations for these variables. It sets iscgo to true, _cgo_init 767 to a gcc-compiled function that can be called early during program 768 startup, and _cgo_thread_start to a gcc-compiled function that can be 769 used to create a new thread, in place of the runtime's usual direct 770 system calls. 771 772 Internal and External Linking 773 774 The text above describes "internal" linking, in which cmd/link parses and 775 links host object files (ELF, Mach-O, PE, and so on) into the final 776 executable itself. Keeping cmd/link simple means we cannot possibly 777 implement the full semantics of the host linker, so the kinds of 778 objects that can be linked directly into the binary is limited (other 779 code can only be used as a dynamic library). On the other hand, when 780 using internal linking, cmd/link can generate Go binaries by itself. 781 782 In order to allow linking arbitrary object files without requiring 783 dynamic libraries, cgo supports an "external" linking mode too. In 784 external linking mode, cmd/link does not process any host object files. 785 Instead, it collects all the Go code and writes a single go.o object 786 file containing it. Then it invokes the host linker (usually gcc) to 787 combine the go.o object file and any supporting non-Go code into a 788 final executable. External linking avoids the dynamic library 789 requirement but introduces a requirement that the host linker be 790 present to create such a binary. 791 792 Most builds both compile source code and invoke the linker to create a 793 binary. When cgo is involved, the compile step already requires gcc, so 794 it is not problematic for the link step to require gcc too. 795 796 An important exception is builds using a pre-compiled copy of the 797 standard library. In particular, package net uses cgo on most systems, 798 and we want to preserve the ability to compile pure Go code that 799 imports net without requiring gcc to be present at link time. (In this 800 case, the dynamic library requirement is less significant, because the 801 only library involved is libc.so, which can usually be assumed 802 present.) 803 804 This conflict between functionality and the gcc requirement means we 805 must support both internal and external linking, depending on the 806 circumstances: if net is the only cgo-using package, then internal 807 linking is probably fine, but if other packages are involved, so that there 808 are dependencies on libraries beyond libc, external linking is likely 809 to work better. The compilation of a package records the relevant 810 information to support both linking modes, leaving the decision 811 to be made when linking the final binary. 812 813 Linking Directives 814 815 In either linking mode, package-specific directives must be passed 816 through to cmd/link. These are communicated by writing //go: directives in a 817 Go source file compiled by gc. The directives are copied into the .o 818 object file and then processed by the linker. 819 820 The directives are: 821 822 //go:cgo_import_dynamic <local> [<remote> ["<library>"]] 823 824 In internal linking mode, allow an unresolved reference to 825 <local>, assuming it will be resolved by a dynamic library 826 symbol. The optional <remote> specifies the symbol's name and 827 possibly version in the dynamic library, and the optional "<library>" 828 names the specific library where the symbol should be found. 829 830 In the <remote>, # or @ can be used to introduce a symbol version. 831 832 Examples: 833 //go:cgo_import_dynamic puts 834 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 835 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6" 836 837 A side effect of the cgo_import_dynamic directive with a 838 library is to make the final binary depend on that dynamic 839 library. To get the dependency without importing any specific 840 symbols, use _ for local and remote. 841 842 Example: 843 //go:cgo_import_dynamic _ _ "libc.so.6" 844 845 For compatibility with current versions of SWIG, 846 #pragma dynimport is an alias for //go:cgo_import_dynamic. 847 848 //go:cgo_dynamic_linker "<path>" 849 850 In internal linking mode, use "<path>" as the dynamic linker 851 in the final binary. This directive is only needed from one 852 package when constructing a binary; by convention it is 853 supplied by runtime/cgo. 854 855 Example: 856 //go:cgo_dynamic_linker "/lib/ld-linux.so.2" 857 858 //go:cgo_export_dynamic <local> <remote> 859 860 In internal linking mode, put the Go symbol 861 named <local> into the program's exported symbol table as 862 <remote>, so that C code can refer to it by that name. This 863 mechanism makes it possible for C code to call back into Go or 864 to share Go's data. 865 866 For compatibility with current versions of SWIG, 867 #pragma dynexport is an alias for //go:cgo_export_dynamic. 868 869 //go:cgo_import_static <local> 870 871 In external linking mode, allow unresolved references to 872 <local> in the go.o object file prepared for the host linker, 873 under the assumption that <local> will be supplied by the 874 other object files that will be linked with go.o. 875 876 Example: 877 //go:cgo_import_static puts_wrapper 878 879 //go:cgo_export_static <local> <remote> 880 881 In external linking mode, put the Go symbol 882 named <local> into the program's exported symbol table as 883 <remote>, so that C code can refer to it by that name. This 884 mechanism makes it possible for C code to call back into Go or 885 to share Go's data. 886 887 //go:cgo_ldflag "<arg>" 888 889 In external linking mode, invoke the host linker (usually gcc) 890 with "<arg>" as a command-line argument following the .o files. 891 Note that the arguments are for "gcc", not "ld". 892 893 Example: 894 //go:cgo_ldflag "-lpthread" 895 //go:cgo_ldflag "-L/usr/local/sqlite3/lib" 896 897 A package compiled with cgo will include directives for both 898 internal and external linking; the linker will select the appropriate 899 subset for the chosen linking mode. 900 901 Example 902 903 As a simple example, consider a package that uses cgo to call C.sin. 904 The following code will be generated by cgo: 905 906 // compiled by gc 907 908 //go:cgo_ldflag "-lm" 909 910 type _Ctype_double float64 911 912 //go:cgo_import_static _cgo_gcc_Cfunc_sin 913 //go:linkname __cgo_gcc_Cfunc_sin _cgo_gcc_Cfunc_sin 914 var __cgo_gcc_Cfunc_sin byte 915 var _cgo_gcc_Cfunc_sin = unsafe.Pointer(&__cgo_gcc_Cfunc_sin) 916 917 func _Cfunc_sin(p0 _Ctype_double) (r1 _Ctype_double) { 918 _cgo_runtime_cgocall(_cgo_gcc_Cfunc_sin, uintptr(unsafe.Pointer(&p0))) 919 return 920 } 921 922 // compiled by gcc, into foo.cgo2.o 923 924 void 925 _cgo_gcc_Cfunc_sin(void *v) 926 { 927 struct { 928 double p0; 929 double r; 930 } __attribute__((__packed__)) *a = v; 931 a->r = sin(a->p0); 932 } 933 934 What happens at link time depends on whether the final binary is linked 935 using the internal or external mode. If other packages are compiled in 936 "external only" mode, then the final link will be an external one. 937 Otherwise the link will be an internal one. 938 939 The linking directives are used according to the kind of final link 940 used. 941 942 In internal mode, cmd/link itself processes all the host object files, in 943 particular foo.cgo2.o. To do so, it uses the cgo_import_dynamic and 944 cgo_dynamic_linker directives to learn that the otherwise undefined 945 reference to sin in foo.cgo2.o should be rewritten to refer to the 946 symbol sin with version GLIBC_2.2.5 from the dynamic library 947 "libm.so.6", and the binary should request "/lib/ld-linux.so.2" as its 948 runtime dynamic linker. 949 950 In external mode, cmd/link does not process any host object files, in 951 particular foo.cgo2.o. It links together the gc-generated object 952 files, along with any other Go code, into a go.o file. While doing 953 that, cmd/link will discover that there is no definition for 954 _cgo_gcc_Cfunc_sin, referred to by the gc-compiled source file. This 955 is okay, because cmd/link also processes the cgo_import_static directive and 956 knows that _cgo_gcc_Cfunc_sin is expected to be supplied by a host 957 object file, so cmd/link does not treat the missing symbol as an error when 958 creating go.o. Indeed, the definition for _cgo_gcc_Cfunc_sin will be 959 provided to the host linker by foo2.cgo.o, which in turn will need the 960 symbol 'sin'. cmd/link also processes the cgo_ldflag directives, so that it 961 knows that the eventual host link command must include the -lm 962 argument, so that the host linker will be able to find 'sin' in the 963 math library. 964 965 cmd/link Command Line Interface 966 967 The go command and any other Go-aware build systems invoke cmd/link 968 to link a collection of packages into a single binary. By default, cmd/link will 969 present the same interface it does today: 970 971 cmd/link main.a 972 973 produces a file named a.out, even if cmd/link does so by invoking the host 974 linker in external linking mode. 975 976 By default, cmd/link will decide the linking mode as follows: if the only 977 packages using cgo are those on a whitelist of standard library 978 packages (net, os/user, runtime/cgo), cmd/link will use internal linking 979 mode. Otherwise, there are non-standard cgo packages involved, and cmd/link 980 will use external linking mode. The first rule means that a build of 981 the godoc binary, which uses net but no other cgo, can run without 982 needing gcc available. The second rule means that a build of a 983 cgo-wrapped library like sqlite3 can generate a standalone executable 984 instead of needing to refer to a dynamic library. The specific choice 985 can be overridden using a command line flag: cmd/link -linkmode=internal or 986 cmd/link -linkmode=external. 987 988 In an external link, cmd/link will create a temporary directory, write any 989 host object files found in package archives to that directory (renamed 990 to avoid conflicts), write the go.o file to that directory, and invoke 991 the host linker. The default value for the host linker is $CC, split 992 into fields, or else "gcc". The specific host linker command line can 993 be overridden using command line flags: cmd/link -extld=clang 994 -extldflags='-ggdb -O3'. If any package in a build includes a .cc or 995 other file compiled by the C++ compiler, the go tool will use the 996 -extld option to set the host linker to the C++ compiler. 997 998 These defaults mean that Go-aware build systems can ignore the linking 999 changes and keep running plain 'cmd/link' and get reasonable results, but 1000 they can also control the linking details if desired. 1001 1002 */ 1003