gcc/go/doc/c-type-interoperability.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _c-type-interoperability:
   7
   8 C Type Interoperability
   9 ***********************
  10
  11 Basic types map directly: an ``int`` in Go is an ``int`` in C,
  12 etc.  Go ``byte`` is equivalent to C ``unsigned char``.
  13 Pointers in Go are pointers in C.  A Go ``struct`` is the same as C
  14 ``struct`` with the same field names and types.
  15
  16 .. index:: string in C
  17
  18 The Go ``string`` type is currently defined as a two-element
  19 structure:
  20
  21 .. code-block:: c++
  22
  23   struct __go_string {
  24     const unsigned char *__data;
  25     int __length;
  26   };
  27
  28 You can't pass arrays between C and Go.  However, a pointer to an
  29 array in Go is equivalent to a C pointer to the equivalent of the
  30 element type.  For example, Go ``*[10]int`` is equivalent to C
  31 ``int*``, assuming that the C pointer does point to 10 elements.
  32
  33 .. index:: slice in C
  34
  35 A slice in Go is a structure.  The current definition is:
  36
  37 .. code-block:: c++
  38
  39   struct __go_slice {
  40     void *__values;
  41     int __count;
  42     int __capacity;
  43   };
  44
  45 The type of a Go function with no receiver is equivalent to a C
  46 function whose parameter types are equivalent.  When a Go function
  47 returns more than one value, the C function returns a struct.  For
  48 example, these functions have equivalent types:
  49
  50 .. code-block:: c++
  51
  52   func GoFunction(int) (int, float)
  53   struct { int i; float f; } CFunction(int)
  54
  55 A pointer to a Go function is equivalent to a pointer to a C function
  56 when the functions have equivalent types.
  57
  58 Go ``interface``, ``channel``, and ``map`` types have no
  59 corresponding C type (``interface`` is a two-element struct and
  60 ``channel`` and ``map`` are pointers to structs in C, but the
  61 structs are deliberately undocumented).  C ``enum`` types
  62 correspond to some integer type, but precisely which one is difficult
  63 to predict in general; use a cast.  C ``union`` types have no
  64 corresponding Go type.  C ``struct`` types containing bitfields
  65 have no corresponding Go type.  C++ ``class`` types have no
  66 corresponding Go type.
  67
  68 Memory allocation is completely different between C and Go, as Go uses
  69 garbage collection.  The exact guidelines in this area are
  70 undetermined, but it is likely that it will be permitted to pass a
  71 pointer to allocated memory from C to Go.  The responsibility of
  72 eventually freeing the pointer will remain with C side, and of course
  73 if the C side frees the pointer while the Go side still has a copy the
  74 program will fail.  When passing a pointer from Go to C, the Go
  75 function must retain a visible copy of it in some Go variable.
  76 Otherwise the Go garbage collector may delete the pointer while the C
  77 function is still using it.