gcc/doc/gccint/target-macros/defining-the-output-assembler-language/how-initialization-functions-are-handled.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 .. index:: initialization routines, termination routines, constructors, output of, destructors, output of
   7
   8 .. _initialization:
   9
  10 How Initialization Functions Are Handled
  11 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  12
  13 The compiled code for certain languages includes :dfn:`constructors`
  14 (also called :dfn:`initialization routines`)---functions to initialize
  15 data in the program when the program is started.  These functions need
  16 to be called before the program is 'started'---that is to say, before
  17 ``main`` is called.
  18
  19 Compiling some languages generates :dfn:`destructors` (also called
  20 :dfn:`termination routines`) that should be called when the program
  21 terminates.
  22
  23 To make the initialization and termination functions work, the compiler
  24 must output something in the assembler code to cause those functions to
  25 be called at the appropriate time.  When you port the compiler to a new
  26 system, you need to specify how to do this.
  27
  28 There are two major ways that GCC currently supports the execution of
  29 initialization and termination functions.  Each way has two variants.
  30 Much of the structure is common to all four variations.
  31
  32 .. index:: __CTOR_LIST__, __DTOR_LIST__
  33
  34 The linker must build two lists of these functions---a list of
  35 initialization functions, called ``__CTOR_LIST__``, and a list of
  36 termination functions, called ``__DTOR_LIST__``.
  37
  38 Each list always begins with an ignored function pointer (which may hold
  39 0, -1, or a count of the function pointers after it, depending on
  40 the environment).  This is followed by a series of zero or more function
  41 pointers to constructors (or destructors), followed by a function
  42 pointer containing zero.
  43
  44 Depending on the operating system and its executable file format, either
  45 :samp:`crtstuff.c` or :samp:`libgcc2.c` traverses these lists at startup
  46 time and exit time.  Constructors are called in reverse order of the
  47 list; destructors in forward order.
  48
  49 The best way to handle static constructors works only for object file
  50 formats which provide arbitrarily-named sections.  A section is set
  51 aside for a list of constructors, and another for a list of destructors.
  52 Traditionally these are called :samp:`.ctors` and :samp:`.dtors`.  Each
  53 object file that defines an initialization function also puts a word in
  54 the constructor section to point to that function.  The linker
  55 accumulates all these words into one contiguous :samp:`.ctors` section.
  56 Termination functions are handled similarly.
  57
  58 This method will be chosen as the default by :samp:`target-def.h` if
  59 ``TARGET_ASM_NAMED_SECTION`` is defined.  A target that does not
  60 support arbitrary sections, but does support special designated
  61 constructor and destructor sections may define ``CTORS_SECTION_ASM_OP``
  62 and ``DTORS_SECTION_ASM_OP`` to achieve the same effect.
  63
  64 When arbitrary sections are available, there are two variants, depending
  65 upon how the code in :samp:`crtstuff.c` is called.  On systems that
  66 support a :dfn:`.init` section which is executed at program startup,
  67 parts of :samp:`crtstuff.c` are compiled into that section.  The
  68 program is linked by the :command:`gcc` driver like this:
  69
  70 .. code-block:: c++
  71
  72   ld -o output_file crti.o crtbegin.o ... -lgcc crtend.o crtn.o
  73
  74 The prologue of a function (``__init``) appears in the ``.init``
  75 section of :samp:`crti.o`; the epilogue appears in :samp:`crtn.o`.  Likewise
  76 for the function ``__fini`` in the :dfn:`.fini` section.  Normally these
  77 files are provided by the operating system or by the GNU C library, but
  78 are provided by GCC for a few targets.
  79
  80 The objects :samp:`crtbegin.o` and :samp:`crtend.o` are (for most targets)
  81 compiled from :samp:`crtstuff.c`.  They contain, among other things, code
  82 fragments within the ``.init`` and ``.fini`` sections that branch
  83 to routines in the ``.text`` section.  The linker will pull all parts
  84 of a section together, which results in a complete ``__init`` function
  85 that invokes the routines we need at startup.
  86
  87 To use this variant, you must define the ``INIT_SECTION_ASM_OP``
  88 macro properly.
  89
  90 If no init section is available, when GCC compiles any function called
  91 ``main`` (or more accurately, any function designated as a program
  92 entry point by the language front end calling ``expand_main_function``),
  93 it inserts a procedure call to ``__main`` as the first executable code
  94 after the function prologue.  The ``__main`` function is defined
  95 in :samp:`libgcc2.c` and runs the global constructors.
  96
  97 In file formats that don't support arbitrary sections, there are again
  98 two variants.  In the simplest variant, the GNU linker (GNU ``ld``)
  99 and an 'a.out' format must be used.  In this case,
 100 ``TARGET_ASM_CONSTRUCTOR`` is defined to produce a ``.stabs``
 101 entry of type :samp:`N_SETT`, referencing the name ``__CTOR_LIST__``,
 102 and with the address of the void function containing the initialization
 103 code as its value.  The GNU linker recognizes this as a request to add
 104 the value to a :dfn:`set`; the values are accumulated, and are eventually
 105 placed in the executable as a vector in the format described above, with
 106 a leading (ignored) count and a trailing zero element.
 107 ``TARGET_ASM_DESTRUCTOR`` is handled similarly.  Since no init
 108 section is available, the absence of ``INIT_SECTION_ASM_OP`` causes
 109 the compilation of ``main`` to call ``__main`` as above, starting
 110 the initialization process.
 111
 112 The last variant uses neither arbitrary sections nor the GNU linker.
 113 This is preferable when you want to do dynamic linking and when using
 114 file formats which the GNU linker does not support, such as 'ECOFF'.  In
 115 this case, ``TARGET_HAVE_CTORS_DTORS`` is false, initialization and
 116 termination functions are recognized simply by their names.  This requires
 117 an extra program in the linkage step, called :command:`collect2`.  This program
 118 pretends to be the linker, for use with GCC; it does its job by running
 119 the ordinary linker, but also arranges to include the vectors of
 120 initialization and termination functions.  These functions are called
 121 via ``__main`` as described above.  In order to use this method,
 122 ``use_collect2`` must be defined in the target in :samp:`config.gcc`.