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