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