Run Format

Source file src/cmd/cgo/doc.go

Documentation: cmd/cgo

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

View as plain text