Source file src/cmd/cgo/doc.go
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 Cgo enables the creation of Go packages that call C code. 7 8 # Using cgo with the go command 9 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. 13 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: 17 18 // #include <stdio.h> 19 // #include <errno.h> 20 import "C" 21 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. 28 29 See $GOROOT/misc/cgo/stdio 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. 32 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). 39 For example: 40 41 // #cgo CFLAGS: -DPNG_DEBUG=1 42 // #cgo amd64 386 CFLAGS: -DX86=1 43 // #cgo LDFLAGS: -lpng 44 // #include <png.h> 45 import "C" 46 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. 49 For example: 50 51 // #cgo pkg-config: png cairo 52 // #include <png.h> 53 import "C" 54 55 The default pkg-config tool may be changed by setting the PKG_CONFIG environment variable. 56 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. 65 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. 70 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. 77 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. 86 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: 92 93 // #cgo LDFLAGS: -L${SRCDIR}/libs -lfoo 94 95 Will be expanded to: 96 97 // #cgo LDFLAGS: -L/go/src/foo/libs -lfoo 98 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. 113 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. 120 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). 133 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. 139 140 The CXX_FOR_TARGET, CXX_FOR_${GOOS}_${GOARCH}, and CXX 141 environment variables work in a similar way for C++ code. 142 143 # Go references to C 144 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. 151 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. 160 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 163 cases section below. 164 165 To access a struct, union, or enum type directly, prefix it with 166 struct_, union_, or enum_, as in C.struct_stat. 167 168 The size of any C type T is available as C.sizeof_T, as in 169 C.sizeof_struct_stat. 170 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 175 176 size_t _GoStringLen(_GoString_ s); 177 const char *_GoStringPtr(_GoString_ s); 178 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 182 NUL byte. 183 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. 186 187 Go structs cannot embed fields with C types. 188 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. 193 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. 198 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: 203 204 n, err = C.sqrt(-1) 205 _, err := C.voidFunc() 206 var n, err = C.sqrt(1) 207 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: 212 213 package main 214 215 // typedef int (*intFunc) (); 216 // 217 // int 218 // bridge_int_func(intFunc f) 219 // { 220 // return f(); 221 // } 222 // 223 // int fortytwo() 224 // { 225 // return 42; 226 // } 227 import "C" 228 import "fmt" 229 230 func main() { 231 f := C.intFunc(C.fortytwo) 232 fmt.Println(int(C.bridge_int_func(f))) 233 // Output: 42 234 } 235 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]). 241 242 Calling variadic C functions is not supported. It is possible to 243 circumvent this by using a C function wrapper. For example: 244 245 package main 246 247 // #include <stdio.h> 248 // #include <stdlib.h> 249 // 250 // static void myprint(char* s) { 251 // printf("%s\n", s); 252 // } 253 import "C" 254 import "unsafe" 255 256 func main() { 257 cs := C.CString("Hello from stdio") 258 C.myprint(cs) 259 C.free(unsafe.Pointer(cs)) 260 } 261 262 A few special functions convert between Go and C types 263 by making copies of the data. In pseudo-Go definitions: 264 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 271 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 278 279 // C string to Go string 280 func C.GoString(*C.char) string 281 282 // C data with explicit length to Go string 283 func C.GoStringN(*C.char, C.int) string 284 285 // C data with explicit length to Go []byte 286 func C.GoBytes(unsafe.Pointer, C.int) []byte 287 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 293 that returns errno. 294 295 # C references to Go 296 297 Go functions can be exported for use by C code in the following way: 298 299 //export MyFunction 300 func MyFunction(arg1, arg2 int, arg3 string) int64 {...} 301 302 //export MyFunction2 303 func MyFunction2(arg1, arg2 int, arg3 string) (int64, *C.char) {...} 304 305 They will be available in the C code as: 306 307 extern GoInt64 MyFunction(int arg1, int arg2, GoString arg3); 308 extern struct MyFunction2_return MyFunction2(int arg1, int arg2, GoString arg3); 309 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. 313 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. 317 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. 323 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. 330 331 # Passing pointers 332 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. 336 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. 344 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. 352 353 Go code may pass a Go pointer to C provided the Go memory to which it 354 points does not contain any Go pointers. The C code must preserve 355 this property: it must not store any Go pointers in Go memory, even 356 temporarily. When passing a pointer to a field in a struct, the Go 357 memory in question is the memory occupied by the field, not the entire 358 struct. When passing a pointer to an element in an array or slice, 359 the Go memory in question is the entire array or the entire backing 360 array of the slice. 361 362 C code may not keep a copy of a Go pointer after the call returns. 363 This includes the _GoString_ type, which, as noted above, includes a 364 Go pointer; _GoString_ values may not be retained by C code. 365 366 A Go function called by C code may not return a Go pointer (which 367 implies that it may not return a string, slice, channel, and so 368 forth). A Go function called by C code may take C pointers as 369 arguments, and it may store non-pointer or C pointer data through 370 those pointers, but it may not store a Go pointer in memory pointed to 371 by a C pointer. A Go function called by C code may take a Go pointer 372 as an argument, but it must preserve the property that the Go memory 373 to which it points does not contain any Go pointers. 374 375 Go code may not store a Go pointer in C memory. C code may store Go 376 pointers in C memory, subject to the rule above: it must stop storing 377 the Go pointer when the C function returns. 378 379 These rules are checked dynamically at runtime. The checking is 380 controlled by the cgocheck setting of the GODEBUG environment 381 variable. The default setting is GODEBUG=cgocheck=1, which implements 382 reasonably cheap dynamic checks. These checks may be disabled 383 entirely using GODEBUG=cgocheck=0. Complete checking of pointer 384 handling, at some cost in run time, is available via GODEBUG=cgocheck=2. 385 386 It is possible to defeat this enforcement by using the unsafe package, 387 and of course there is nothing stopping the C code from doing anything 388 it likes. However, programs that break these rules are likely to fail 389 in unexpected and unpredictable ways. 390 391 The runtime/cgo.Handle type can be used to safely pass Go values 392 between Go and C. See the runtime/cgo package documentation for details. 393 394 Note: the current implementation has a bug. While Go code is permitted 395 to write nil or a C pointer (but not a Go pointer) to C memory, the 396 current implementation may sometimes cause a runtime error if the 397 contents of the C memory appear to be a Go pointer. Therefore, avoid 398 passing uninitialized C memory to Go code if the Go code is going to 399 store pointer values in it. Zero out the memory in C before passing it 400 to Go. 401 402 # Special cases 403 404 A few special C types which would normally be represented by a pointer 405 type in Go are instead represented by a uintptr. Those include: 406 407 1. The *Ref types on Darwin, rooted at CoreFoundation's CFTypeRef type. 408 409 2. The object types from Java's JNI interface: 410 411 jobject 412 jclass 413 jthrowable 414 jstring 415 jarray 416 jbooleanArray 417 jbyteArray 418 jcharArray 419 jshortArray 420 jintArray 421 jlongArray 422 jfloatArray 423 jdoubleArray 424 jobjectArray 425 jweak 426 427 3. The EGLDisplay and EGLConfig types from the EGL API. 428 429 These types are uintptr on the Go side because they would otherwise 430 confuse the Go garbage collector; they are sometimes not really 431 pointers but data structures encoded in a pointer type. All operations 432 on these types must happen in C. The proper constant to initialize an 433 empty such reference is 0, not nil. 434 435 These special cases were introduced in Go 1.10. For auto-updating code 436 from Go 1.9 and earlier, use the cftype or jni rewrites in the Go fix tool: 437 438 go tool fix -r cftype <pkg> 439 go tool fix -r jni <pkg> 440 441 It will replace nil with 0 in the appropriate places. 442 443 The EGLDisplay case was introduced in Go 1.12. Use the egl rewrite 444 to auto-update code from Go 1.11 and earlier: 445 446 go tool fix -r egl <pkg> 447 448 The EGLConfig case was introduced in Go 1.15. Use the eglconf rewrite 449 to auto-update code from Go 1.14 and earlier: 450 451 go tool fix -r eglconf <pkg> 452 453 # Using cgo directly 454 455 Usage: 456 457 go tool cgo [cgo options] [-- compiler options] gofiles... 458 459 Cgo transforms the specified input Go source files into several output 460 Go and C source files. 461 462 The compiler options are passed through uninterpreted when 463 invoking the C compiler to compile the C parts of the package. 464 465 The following options are available when running cgo directly: 466 467 -V 468 Print cgo version and exit. 469 -debug-define 470 Debugging option. Print #defines. 471 -debug-gcc 472 Debugging option. Trace C compiler execution and output. 473 -dynimport file 474 Write list of symbols imported by file. Write to 475 -dynout argument or to standard output. Used by go 476 build when building a cgo package. 477 -dynlinker 478 Write dynamic linker as part of -dynimport output. 479 -dynout file 480 Write -dynimport output to file. 481 -dynpackage package 482 Set Go package for -dynimport output. 483 -exportheader file 484 If there are any exported functions, write the 485 generated export declarations to file. 486 C code can #include this to see the declarations. 487 -importpath string 488 The import path for the Go package. Optional; used for 489 nicer comments in the generated files. 490 -import_runtime_cgo 491 If set (which it is by default) import runtime/cgo in 492 generated output. 493 -import_syscall 494 If set (which it is by default) import syscall in 495 generated output. 496 -gccgo 497 Generate output for the gccgo compiler rather than the 498 gc compiler. 499 -gccgoprefix prefix 500 The -fgo-prefix option to be used with gccgo. 501 -gccgopkgpath path 502 The -fgo-pkgpath option to be used with gccgo. 503 -gccgo_define_cgoincomplete 504 Define cgo.Incomplete locally rather than importing it from 505 the "runtime/cgo" package. Used for old gccgo versions. 506 -godefs 507 Write out input file in Go syntax replacing C package 508 names with real values. Used to generate files in the 509 syscall package when bootstrapping a new target. 510 -objdir directory 511 Put all generated files in directory. 512 -srcdir directory 513 */ 514 package main 515 516 /* 517 Implementation details. 518 519 Cgo provides a way for Go programs to call C code linked into the same 520 address space. This comment explains the operation of cgo. 521 522 Cgo reads a set of Go source files and looks for statements saying 523 import "C". If the import has a doc comment, that comment is 524 taken as literal C code to be used as a preamble to any C code 525 generated by cgo. A typical preamble #includes necessary definitions: 526 527 // #include <stdio.h> 528 import "C" 529 530 For more details about the usage of cgo, see the documentation 531 comment at the top of this file. 532 533 Understanding C 534 535 Cgo scans the Go source files that import "C" for uses of that 536 package, such as C.puts. It collects all such identifiers. The next 537 step is to determine each kind of name. In C.xxx the xxx might refer 538 to a type, a function, a constant, or a global variable. Cgo must 539 decide which. 540 541 The obvious thing for cgo to do is to process the preamble, expanding 542 #includes and processing the corresponding C code. That would require 543 a full C parser and type checker that was also aware of any extensions 544 known to the system compiler (for example, all the GNU C extensions) as 545 well as the system-specific header locations and system-specific 546 pre-#defined macros. This is certainly possible to do, but it is an 547 enormous amount of work. 548 549 Cgo takes a different approach. It determines the meaning of C 550 identifiers not by parsing C code but by feeding carefully constructed 551 programs into the system C compiler and interpreting the generated 552 error messages, debug information, and object files. In practice, 553 parsing these is significantly less work and more robust than parsing 554 C source. 555 556 Cgo first invokes gcc -E -dM on the preamble, in order to find out 557 about simple #defines for constants and the like. These are recorded 558 for later use. 559 560 Next, cgo needs to identify the kinds for each identifier. For the 561 identifiers C.foo, cgo generates this C program: 562 563 <preamble> 564 #line 1 "not-declared" 565 void __cgo_f_1_1(void) { __typeof__(foo) *__cgo_undefined__1; } 566 #line 1 "not-type" 567 void __cgo_f_1_2(void) { foo *__cgo_undefined__2; } 568 #line 1 "not-int-const" 569 void __cgo_f_1_3(void) { enum { __cgo_undefined__3 = (foo)*1 }; } 570 #line 1 "not-num-const" 571 void __cgo_f_1_4(void) { static const double __cgo_undefined__4 = (foo); } 572 #line 1 "not-str-lit" 573 void __cgo_f_1_5(void) { static const char __cgo_undefined__5[] = (foo); } 574 575 This program will not compile, but cgo can use the presence or absence 576 of an error message on a given line to deduce the information it 577 needs. The program is syntactically valid regardless of whether each 578 name is a type or an ordinary identifier, so there will be no syntax 579 errors that might stop parsing early. 580 581 An error on not-declared:1 indicates that foo is undeclared. 582 An error on not-type:1 indicates that foo is not a type (if declared at all, it is an identifier). 583 An error on not-int-const:1 indicates that foo is not an integer constant. 584 An error on not-num-const:1 indicates that foo is not a number constant. 585 An error on not-str-lit:1 indicates that foo is not a string literal. 586 An error on not-signed-int-const:1 indicates that foo is not a signed integer constant. 587 588 The line number specifies the name involved. In the example, 1 is foo. 589 590 Next, cgo must learn the details of each type, variable, function, or 591 constant. It can do this by reading object files. If cgo has decided 592 that t1 is a type, v2 and v3 are variables or functions, and i4, i5 593 are integer constants, u6 is an unsigned integer constant, and f7 and f8 594 are float constants, and s9 and s10 are string constants, it generates: 595 596 <preamble> 597 __typeof__(t1) *__cgo__1; 598 __typeof__(v2) *__cgo__2; 599 __typeof__(v3) *__cgo__3; 600 __typeof__(i4) *__cgo__4; 601 enum { __cgo_enum__4 = i4 }; 602 __typeof__(i5) *__cgo__5; 603 enum { __cgo_enum__5 = i5 }; 604 __typeof__(u6) *__cgo__6; 605 enum { __cgo_enum__6 = u6 }; 606 __typeof__(f7) *__cgo__7; 607 __typeof__(f8) *__cgo__8; 608 __typeof__(s9) *__cgo__9; 609 __typeof__(s10) *__cgo__10; 610 611 long long __cgodebug_ints[] = { 612 0, // t1 613 0, // v2 614 0, // v3 615 i4, 616 i5, 617 u6, 618 0, // f7 619 0, // f8 620 0, // s9 621 0, // s10 622 1 623 }; 624 625 double __cgodebug_floats[] = { 626 0, // t1 627 0, // v2 628 0, // v3 629 0, // i4 630 0, // i5 631 0, // u6 632 f7, 633 f8, 634 0, // s9 635 0, // s10 636 1 637 }; 638 639 const char __cgodebug_str__9[] = s9; 640 const unsigned long long __cgodebug_strlen__9 = sizeof(s9)-1; 641 const char __cgodebug_str__10[] = s10; 642 const unsigned long long __cgodebug_strlen__10 = sizeof(s10)-1; 643 644 and again invokes the system C compiler, to produce an object file 645 containing debug information. Cgo parses the DWARF debug information 646 for __cgo__N to learn the type of each identifier. (The types also 647 distinguish functions from global variables.) Cgo reads the constant 648 values from the __cgodebug_* from the object file's data segment. 649 650 At this point cgo knows the meaning of each C.xxx well enough to start 651 the translation process. 652 653 Translating Go 654 655 Given the input Go files x.go and y.go, cgo generates these source 656 files: 657 658 x.cgo1.go # for gc (cmd/compile) 659 y.cgo1.go # for gc 660 _cgo_gotypes.go # for gc 661 _cgo_import.go # for gc (if -dynout _cgo_import.go) 662 x.cgo2.c # for gcc 663 y.cgo2.c # for gcc 664 _cgo_defun.c # for gcc (if -gccgo) 665 _cgo_export.c # for gcc 666 _cgo_export.h # for gcc 667 _cgo_main.c # for gcc 668 _cgo_flags # for alternative build tools 669 670 The file x.cgo1.go is a copy of x.go with the import "C" removed and 671 references to C.xxx replaced with names like _Cfunc_xxx or _Ctype_xxx. 672 The definitions of those identifiers, written as Go functions, types, 673 or variables, are provided in _cgo_gotypes.go. 674 675 Here is a _cgo_gotypes.go containing definitions for needed C types: 676 677 type _Ctype_char int8 678 type _Ctype_int int32 679 type _Ctype_void [0]byte 680 681 The _cgo_gotypes.go file also contains the definitions of the 682 functions. They all have similar bodies that invoke runtime·cgocall 683 to make a switch from the Go runtime world to the system C (GCC-based) 684 world. 685 686 For example, here is the definition of _Cfunc_puts: 687 688 //go:cgo_import_static _cgo_be59f0f25121_Cfunc_puts 689 //go:linkname __cgofn__cgo_be59f0f25121_Cfunc_puts _cgo_be59f0f25121_Cfunc_puts 690 var __cgofn__cgo_be59f0f25121_Cfunc_puts byte 691 var _cgo_be59f0f25121_Cfunc_puts = unsafe.Pointer(&__cgofn__cgo_be59f0f25121_Cfunc_puts) 692 693 func _Cfunc_puts(p0 *_Ctype_char) (r1 _Ctype_int) { 694 _cgo_runtime_cgocall(_cgo_be59f0f25121_Cfunc_puts, uintptr(unsafe.Pointer(&p0))) 695 return 696 } 697 698 The hexadecimal number is a hash of cgo's input, chosen to be 699 deterministic yet unlikely to collide with other uses. The actual 700 function _cgo_be59f0f25121_Cfunc_puts is implemented in a C source 701 file compiled by gcc, the file x.cgo2.c: 702 703 void 704 _cgo_be59f0f25121_Cfunc_puts(void *v) 705 { 706 struct { 707 char* p0; 708 int r; 709 char __pad12[4]; 710 } __attribute__((__packed__, __gcc_struct__)) *a = v; 711 a->r = puts((void*)a->p0); 712 } 713 714 It extracts the arguments from the pointer to _Cfunc_puts's argument 715 frame, invokes the system C function (in this case, puts), stores the 716 result in the frame, and returns. 717 718 Linking 719 720 Once the _cgo_export.c and *.cgo2.c files have been compiled with gcc, 721 they need to be linked into the final binary, along with the libraries 722 they might depend on (in the case of puts, stdio). cmd/link has been 723 extended to understand basic ELF files, but it does not understand ELF 724 in the full complexity that modern C libraries embrace, so it cannot 725 in general generate direct references to the system libraries. 726 727 Instead, the build process generates an object file using dynamic 728 linkage to the desired libraries. The main function is provided by 729 _cgo_main.c: 730 731 int main() { return 0; } 732 void crosscall2(void(*fn)(void*), void *a, int c, uintptr_t ctxt) { } 733 uintptr_t _cgo_wait_runtime_init_done(void) { return 0; } 734 void _cgo_release_context(uintptr_t ctxt) { } 735 char* _cgo_topofstack(void) { return (char*)0; } 736 void _cgo_allocate(void *a, int c) { } 737 void _cgo_panic(void *a, int c) { } 738 void _cgo_reginit(void) { } 739 740 The extra functions here are stubs to satisfy the references in the C 741 code generated for gcc. The build process links this stub, along with 742 _cgo_export.c and *.cgo2.c, into a dynamic executable and then lets 743 cgo examine the executable. Cgo records the list of shared library 744 references and resolved names and writes them into a new file 745 _cgo_import.go, which looks like: 746 747 //go:cgo_dynamic_linker "/lib64/ld-linux-x86-64.so.2" 748 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6" 749 //go:cgo_import_dynamic __libc_start_main __libc_start_main#GLIBC_2.2.5 "libc.so.6" 750 //go:cgo_import_dynamic stdout stdout#GLIBC_2.2.5 "libc.so.6" 751 //go:cgo_import_dynamic fflush fflush#GLIBC_2.2.5 "libc.so.6" 752 //go:cgo_import_dynamic _ _ "libpthread.so.0" 753 //go:cgo_import_dynamic _ _ "libc.so.6" 754 755 In the end, the compiled Go package, which will eventually be 756 presented to cmd/link as part of a larger program, contains: 757 758 _go_.o # gc-compiled object for _cgo_gotypes.go, _cgo_import.go, *.cgo1.go 759 _all.o # gcc-compiled object for _cgo_export.c, *.cgo2.c 760 761 If there is an error generating the _cgo_import.go file, then, instead 762 of adding _cgo_import.go to the package, the go tool adds an empty 763 file named dynimportfail. The _cgo_import.go file is only needed when 764 using internal linking mode, which is not the default when linking 765 programs that use cgo (as described below). If the linker sees a file 766 named dynimportfail it reports an error if it has been told to use 767 internal linking mode. This approach is taken because generating 768 _cgo_import.go requires doing a full C link of the package, which can 769 fail for reasons that are irrelevant when using external linking mode. 770 771 The final program will be a dynamic executable, so that cmd/link can avoid 772 needing to process arbitrary .o files. It only needs to process the .o 773 files generated from C files that cgo writes, and those are much more 774 limited in the ELF or other features that they use. 775 776 In essence, the _cgo_import.o file includes the extra linking 777 directives that cmd/link is not sophisticated enough to derive from _all.o 778 on its own. Similarly, the _all.o uses dynamic references to real 779 system object code because cmd/link is not sophisticated enough to process 780 the real code. 781 782 The main benefits of this system are that cmd/link remains relatively simple 783 (it does not need to implement a complete ELF and Mach-O linker) and 784 that gcc is not needed after the package is compiled. For example, 785 package net uses cgo for access to name resolution functions provided 786 by libc. Although gcc is needed to compile package net, gcc is not 787 needed to link programs that import package net. 788 789 Runtime 790 791 When using cgo, Go must not assume that it owns all details of the 792 process. In particular it needs to coordinate with C in the use of 793 threads and thread-local storage. The runtime package declares a few 794 variables: 795 796 var ( 797 iscgo bool 798 _cgo_init unsafe.Pointer 799 _cgo_thread_start unsafe.Pointer 800 ) 801 802 Any package using cgo imports "runtime/cgo", which provides 803 initializations for these variables. It sets iscgo to true, _cgo_init 804 to a gcc-compiled function that can be called early during program 805 startup, and _cgo_thread_start to a gcc-compiled function that can be 806 used to create a new thread, in place of the runtime's usual direct 807 system calls. 808 809 Internal and External Linking 810 811 The text above describes "internal" linking, in which cmd/link parses and 812 links host object files (ELF, Mach-O, PE, and so on) into the final 813 executable itself. Keeping cmd/link simple means we cannot possibly 814 implement the full semantics of the host linker, so the kinds of 815 objects that can be linked directly into the binary is limited (other 816 code can only be used as a dynamic library). On the other hand, when 817 using internal linking, cmd/link can generate Go binaries by itself. 818 819 In order to allow linking arbitrary object files without requiring 820 dynamic libraries, cgo supports an "external" linking mode too. In 821 external linking mode, cmd/link does not process any host object files. 822 Instead, it collects all the Go code and writes a single go.o object 823 file containing it. Then it invokes the host linker (usually gcc) to 824 combine the go.o object file and any supporting non-Go code into a 825 final executable. External linking avoids the dynamic library 826 requirement but introduces a requirement that the host linker be 827 present to create such a binary. 828 829 Most builds both compile source code and invoke the linker to create a 830 binary. When cgo is involved, the compile step already requires gcc, so 831 it is not problematic for the link step to require gcc too. 832 833 An important exception is builds using a pre-compiled copy of the 834 standard library. In particular, package net uses cgo on most systems, 835 and we want to preserve the ability to compile pure Go code that 836 imports net without requiring gcc to be present at link time. (In this 837 case, the dynamic library requirement is less significant, because the 838 only library involved is libc.so, which can usually be assumed 839 present.) 840 841 This conflict between functionality and the gcc requirement means we 842 must support both internal and external linking, depending on the 843 circumstances: if net is the only cgo-using package, then internal 844 linking is probably fine, but if other packages are involved, so that there 845 are dependencies on libraries beyond libc, external linking is likely 846 to work better. The compilation of a package records the relevant 847 information to support both linking modes, leaving the decision 848 to be made when linking the final binary. 849 850 Linking Directives 851 852 In either linking mode, package-specific directives must be passed 853 through to cmd/link. These are communicated by writing //go: directives in a 854 Go source file compiled by gc. The directives are copied into the .o 855 object file and then processed by the linker. 856 857 The directives are: 858 859 //go:cgo_import_dynamic <local> [<remote> ["<library>"]] 860 861 In internal linking mode, allow an unresolved reference to 862 <local>, assuming it will be resolved by a dynamic library 863 symbol. The optional <remote> specifies the symbol's name and 864 possibly version in the dynamic library, and the optional "<library>" 865 names the specific library where the symbol should be found. 866 867 On AIX, the library pattern is slightly different. It must be 868 "lib.a/obj.o" with obj.o the member of this library exporting 869 this symbol. 870 871 In the <remote>, # or @ can be used to introduce a symbol version. 872 873 Examples: 874 //go:cgo_import_dynamic puts 875 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 876 //go:cgo_import_dynamic puts puts#GLIBC_2.2.5 "libc.so.6" 877 878 A side effect of the cgo_import_dynamic directive with a 879 library is to make the final binary depend on that dynamic 880 library. To get the dependency without importing any specific 881 symbols, use _ for local and remote. 882 883 Example: 884 //go:cgo_import_dynamic _ _ "libc.so.6" 885 886 For compatibility with current versions of SWIG, 887 #pragma dynimport is an alias for //go:cgo_import_dynamic. 888 889 //go:cgo_dynamic_linker "<path>" 890 891 In internal linking mode, use "<path>" as the dynamic linker 892 in the final binary. This directive is only needed from one 893 package when constructing a binary; by convention it is 894 supplied by runtime/cgo. 895 896 Example: 897 //go:cgo_dynamic_linker "/lib/ld-linux.so.2" 898 899 //go:cgo_export_dynamic <local> <remote> 900 901 In internal linking mode, put the Go symbol 902 named <local> into the program's exported symbol table as 903 <remote>, so that C code can refer to it by that name. This 904 mechanism makes it possible for C code to call back into Go or 905 to share Go's data. 906 907 For compatibility with current versions of SWIG, 908 #pragma dynexport is an alias for //go:cgo_export_dynamic. 909 910 //go:cgo_import_static <local> 911 912 In external linking mode, allow unresolved references to 913 <local> in the go.o object file prepared for the host linker, 914 under the assumption that <local> will be supplied by the 915 other object files that will be linked with go.o. 916 917 Example: 918 //go:cgo_import_static puts_wrapper 919 920 //go:cgo_export_static <local> <remote> 921 922 In external linking mode, put the Go symbol 923 named <local> into the program's exported symbol table as 924 <remote>, so that C code can refer to it by that name. This 925 mechanism makes it possible for C code to call back into Go or 926 to share Go's data. 927 928 //go:cgo_ldflag "<arg>" 929 930 In external linking mode, invoke the host linker (usually gcc) 931 with "<arg>" as a command-line argument following the .o files. 932 Note that the arguments are for "gcc", not "ld". 933 934 Example: 935 //go:cgo_ldflag "-lpthread" 936 //go:cgo_ldflag "-L/usr/local/sqlite3/lib" 937 938 A package compiled with cgo will include directives for both 939 internal and external linking; the linker will select the appropriate 940 subset for the chosen linking mode. 941 942 Example 943 944 As a simple example, consider a package that uses cgo to call C.sin. 945 The following code will be generated by cgo: 946 947 // compiled by gc 948 949 //go:cgo_ldflag "-lm" 950 951 type _Ctype_double float64 952 953 //go:cgo_import_static _cgo_gcc_Cfunc_sin 954 //go:linkname __cgo_gcc_Cfunc_sin _cgo_gcc_Cfunc_sin 955 var __cgo_gcc_Cfunc_sin byte 956 var _cgo_gcc_Cfunc_sin = unsafe.Pointer(&__cgo_gcc_Cfunc_sin) 957 958 func _Cfunc_sin(p0 _Ctype_double) (r1 _Ctype_double) { 959 _cgo_runtime_cgocall(_cgo_gcc_Cfunc_sin, uintptr(unsafe.Pointer(&p0))) 960 return 961 } 962 963 // compiled by gcc, into foo.cgo2.o 964 965 void 966 _cgo_gcc_Cfunc_sin(void *v) 967 { 968 struct { 969 double p0; 970 double r; 971 } __attribute__((__packed__)) *a = v; 972 a->r = sin(a->p0); 973 } 974 975 What happens at link time depends on whether the final binary is linked 976 using the internal or external mode. If other packages are compiled in 977 "external only" mode, then the final link will be an external one. 978 Otherwise the link will be an internal one. 979 980 The linking directives are used according to the kind of final link 981 used. 982 983 In internal mode, cmd/link itself processes all the host object files, in 984 particular foo.cgo2.o. To do so, it uses the cgo_import_dynamic and 985 cgo_dynamic_linker directives to learn that the otherwise undefined 986 reference to sin in foo.cgo2.o should be rewritten to refer to the 987 symbol sin with version GLIBC_2.2.5 from the dynamic library 988 "libm.so.6", and the binary should request "/lib/ld-linux.so.2" as its 989 runtime dynamic linker. 990 991 In external mode, cmd/link does not process any host object files, in 992 particular foo.cgo2.o. It links together the gc-generated object 993 files, along with any other Go code, into a go.o file. While doing 994 that, cmd/link will discover that there is no definition for 995 _cgo_gcc_Cfunc_sin, referred to by the gc-compiled source file. This 996 is okay, because cmd/link also processes the cgo_import_static directive and 997 knows that _cgo_gcc_Cfunc_sin is expected to be supplied by a host 998 object file, so cmd/link does not treat the missing symbol as an error when 999 creating go.o. Indeed, the definition for _cgo_gcc_Cfunc_sin will be 1000 provided to the host linker by foo2.cgo.o, which in turn will need the 1001 symbol 'sin'. cmd/link also processes the cgo_ldflag directives, so that it 1002 knows that the eventual host link command must include the -lm 1003 argument, so that the host linker will be able to find 'sin' in the 1004 math library. 1005 1006 cmd/link Command Line Interface 1007 1008 The go command and any other Go-aware build systems invoke cmd/link 1009 to link a collection of packages into a single binary. By default, cmd/link will 1010 present the same interface it does today: 1011 1012 cmd/link main.a 1013 1014 produces a file named a.out, even if cmd/link does so by invoking the host 1015 linker in external linking mode. 1016 1017 By default, cmd/link will decide the linking mode as follows: if the only 1018 packages using cgo are those on a list of known standard library 1019 packages (net, os/user, runtime/cgo), cmd/link will use internal linking 1020 mode. Otherwise, there are non-standard cgo packages involved, and cmd/link 1021 will use external linking mode. The first rule means that a build of 1022 the godoc binary, which uses net but no other cgo, can run without 1023 needing gcc available. The second rule means that a build of a 1024 cgo-wrapped library like sqlite3 can generate a standalone executable 1025 instead of needing to refer to a dynamic library. The specific choice 1026 can be overridden using a command line flag: cmd/link -linkmode=internal or 1027 cmd/link -linkmode=external. 1028 1029 In an external link, cmd/link will create a temporary directory, write any 1030 host object files found in package archives to that directory (renamed 1031 to avoid conflicts), write the go.o file to that directory, and invoke 1032 the host linker. The default value for the host linker is $CC, split 1033 into fields, or else "gcc". The specific host linker command line can 1034 be overridden using command line flags: cmd/link -extld=clang 1035 -extldflags='-ggdb -O3'. If any package in a build includes a .cc or 1036 other file compiled by the C++ compiler, the go tool will use the 1037 -extld option to set the host linker to the C++ compiler. 1038 1039 These defaults mean that Go-aware build systems can ignore the linking 1040 changes and keep running plain 'cmd/link' and get reasonable results, but 1041 they can also control the linking details if desired. 1042 1043 */ 1044