gccint: Initialization

1 
1 18.20.5 How Initialization Functions Are Handled
1 ------------------------------------------------
1 
1 The compiled code for certain languages includes "constructors" (also
1 called "initialization routines")--functions to initialize data in the
1 program when the program is started.  These functions need to be called
1 before the program is "started"--that is to say, before 'main' is
1 called.
1 
1  Compiling some languages generates "destructors" (also called
1 "termination routines") that should be called when the program
1 terminates.
1 
1  To make the initialization and termination functions work, the compiler
1 must output something in the assembler code to cause those functions to
1 be called at the appropriate time.  When you port the compiler to a new
1 system, you need to specify how to do this.
1 
1  There are two major ways that GCC currently supports the execution of
1 initialization and termination functions.  Each way has two variants.
1 Much of the structure is common to all four variations.
1 
1  The linker must build two lists of these functions--a list of
1 initialization functions, called '__CTOR_LIST__', and a list of
1 termination functions, called '__DTOR_LIST__'.
1 
1  Each list always begins with an ignored function pointer (which may
1 hold 0, -1, or a count of the function pointers after it, depending on
1 the environment).  This is followed by a series of zero or more function
1 pointers to constructors (or destructors), followed by a function
1 pointer containing zero.
1 
1  Depending on the operating system and its executable file format,
1 either 'crtstuff.c' or 'libgcc2.c' traverses these lists at startup time
1 and exit time.  Constructors are called in reverse order of the list;
1 destructors in forward order.
1 
1  The best way to handle static constructors works only for object file
1 formats which provide arbitrarily-named sections.  A section is set
1 aside for a list of constructors, and another for a list of destructors.
1 Traditionally these are called '.ctors' and '.dtors'.  Each object file
1 that defines an initialization function also puts a word in the
1 constructor section to point to that function.  The linker accumulates
1 all these words into one contiguous '.ctors' section.  Termination
1 functions are handled similarly.
1 
1  This method will be chosen as the default by 'target-def.h' if
1 'TARGET_ASM_NAMED_SECTION' is defined.  A target that does not support
1 arbitrary sections, but does support special designated constructor and
1 destructor sections may define 'CTORS_SECTION_ASM_OP' and
1 'DTORS_SECTION_ASM_OP' to achieve the same effect.
1 
1  When arbitrary sections are available, there are two variants,
1 depending upon how the code in 'crtstuff.c' is called.  On systems that
1 support a ".init" section which is executed at program startup, parts of
1 'crtstuff.c' are compiled into that section.  The program is linked by
1 the 'gcc' driver like this:
1 
1      ld -o OUTPUT_FILE crti.o crtbegin.o ... -lgcc crtend.o crtn.o
1 
1  The prologue of a function ('__init') appears in the '.init' section of
1 'crti.o'; the epilogue appears in 'crtn.o'.  Likewise for the function
1 '__fini' in the ".fini" section.  Normally these files are provided by
1 the operating system or by the GNU C library, but are provided by GCC
1 for a few targets.
1 
1  The objects 'crtbegin.o' and 'crtend.o' are (for most targets) compiled
1 from 'crtstuff.c'.  They contain, among other things, code fragments
1 within the '.init' and '.fini' sections that branch to routines in the
1 '.text' section.  The linker will pull all parts of a section together,
1 which results in a complete '__init' function that invokes the routines
1 we need at startup.
1 
1  To use this variant, you must define the 'INIT_SECTION_ASM_OP' macro
1 properly.
1 
1  If no init section is available, when GCC compiles any function called
1 'main' (or more accurately, any function designated as a program entry
1 point by the language front end calling 'expand_main_function'), it
1 inserts a procedure call to '__main' as the first executable code after
1 the function prologue.  The '__main' function is defined in 'libgcc2.c'
1 and runs the global constructors.
1 
1  In file formats that don't support arbitrary sections, there are again
1 two variants.  In the simplest variant, the GNU linker (GNU 'ld') and an
1 'a.out' format must be used.  In this case, 'TARGET_ASM_CONSTRUCTOR' is
1 defined to produce a '.stabs' entry of type 'N_SETT', referencing the
1 name '__CTOR_LIST__', and with the address of the void function
1 containing the initialization code as its value.  The GNU linker
1 recognizes this as a request to add the value to a "set"; the values are
1 accumulated, and are eventually placed in the executable as a vector in
1 the format described above, with a leading (ignored) count and a
1 trailing zero element.  'TARGET_ASM_DESTRUCTOR' is handled similarly.
1 Since no init section is available, the absence of 'INIT_SECTION_ASM_OP'
1 causes the compilation of 'main' to call '__main' as above, starting the
1 initialization process.
1 
1  The last variant uses neither arbitrary sections nor the GNU linker.
1 This is preferable when you want to do dynamic linking and when using
1 file formats which the GNU linker does not support, such as 'ECOFF'.  In
1 this case, 'TARGET_HAVE_CTORS_DTORS' is false, initialization and
1 termination functions are recognized simply by their names.  This
1 requires an extra program in the linkage step, called 'collect2'.  This
1 program pretends to be the linker, for use with GCC; it does its job by
1 running the ordinary linker, but also arranges to include the vectors of
1 initialization and termination functions.  These functions are called
1 via '__main' as described above.  In order to use this method,
1 'use_collect2' must be defined in the target in 'config.gcc'.
1 
1  The following section describes the specific macros that control and
1 customize the handling of initialization and termination functions.
1