home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 7 / FreshFishVol7.bin / bbs / gnu / gcc-2.5.8-bin.lha / GNU / info / gcc.info-22 (.txt) < prev    next >
GNU Info File  |  1994-09-02  |  43KB  |  760 lines
  1. This is Info file gcc.info, produced by Makeinfo-1.54 from the input
  2. file gcc.texi.
  3.    This file documents the use and the internals of the GNU compiler.
  4.    Published by the Free Software Foundation 675 Massachusetts Avenue
  5. Cambridge, MA 02139 USA
  6.    Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided also
  12. that the sections entitled "GNU General Public License" and "Protect
  13. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  14. original, and provided that the entire resulting derived work is
  15. distributed under the terms of a permission notice identical to this
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that the sections entitled "GNU General Public
  19. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  20. permission notice, may be included in translations approved by the Free
  21. Software Foundation instead of in the original English.
  22. File: gcc.info,  Node: Initialization,  Next: Macros for Initialization,  Prev: Label Output,  Up: Assembler Format
  23. How Initialization Functions Are Handled
  24. ----------------------------------------
  25.    The compiled code for certain languages includes "constructors"
  26. (also called "initialization routines")--functions to initialize data
  27. in the program when the program is started.  These functions need to be
  28. called before the program is "started"--that is to say, before `main'
  29. is called.
  30.    Compiling some languages generates "destructors" (also called
  31. "termination routines") that should be called when the program
  32. terminates.
  33.    To make the initialization and termination functions work, the
  34. compiler must output something in the assembler code to cause those
  35. functions to be called at the appropriate time.  When you port the
  36. compiler to a new system, you need to specify how to do this.
  37.    There are two major ways that GCC currently supports the execution of
  38. initialization and termination functions.  Each way has two variants.
  39. Much of the structure is common to all four variations.
  40.    The linker must build two lists of these functions--a list of
  41. initialization functions, called `__CTOR_LIST__', and a list of
  42. termination functions, called `__DTOR_LIST__'.
  43.    Each list always begins with an ignored function pointer (which may
  44. hold 0, -1, or a count of the function pointers after it, depending on
  45. the environment).  This is followed by a series of zero or more function
  46. pointers to constructors (or destructors), followed by a function
  47. pointer containing zero.
  48.    Depending on the operating system and its executable file format,
  49. either `crtstuff.c' or `libgcc2.c' traverses these lists at startup
  50. time and exit time.  Constructors are called in forward order of the
  51. list; destructors in reverse order.
  52.    The best way to handle static constructors works only for object file
  53. formats which provide arbitrarily-named sections.  A section is set
  54. aside for a list of constructors, and another for a list of destructors.
  55. Traditionally these are called `.ctors' and `.dtors'.  Each object file
  56. that defines an initialization function also puts a word in the
  57. constructor section to point to that function.  The linker accumulates
  58. all these words into one contiguous `.ctors' section.  Termination
  59. functions are handled similarly.
  60.    To use this method, you need appropriate definitions of the macros
  61. `ASM_OUTPUT_CONSTRUCTOR' and `ASM_OUTPUT_DESTRUCTOR'.  Usually you can
  62. get them by including `svr4.h'.
  63.    When arbitrary sections are available, there are two variants,
  64. depending upon how the code in `crtstuff.c' is called.  On systems that
  65. support an "init" section which is executed at program startup, parts
  66. of `crtstuff.c' are compiled into that section.  The program is linked
  67. by the `gcc' driver like this:
  68.      ld -o OUTPUT_FILE crtbegin.o ... crtend.o -lgcc
  69.    The head of a function (`__do_global_ctors') appears in the init
  70. section of `crtbegin.o'; the remainder of the function appears in the
  71. init section of `crtend.o'.  The linker will pull these two parts of
  72. the section together, making a whole function.  If any of the user's
  73. object files linked into the middle of it contribute code, then that
  74. code will be executed as part of the body of `__do_global_ctors'.
  75.    To use this variant, you must define the `INIT_SECTION_ASM_OP' macro
  76. properly.
  77.    If no init section is available, do not define
  78. `INIT_SECTION_ASM_OP'.  Then `__do_global_ctors' is built into the text
  79. section like all other functions, and resides in `libgcc.a'.  When GCC
  80. compiles any function called `main', it inserts a procedure call to
  81. `__main' as the first executable code after the function prologue.  The
  82. `__main' function, also defined in `libgcc2.c', simply calls
  83. `__do_global_ctors'.
  84.    In file formats that don't support arbitrary sections, there are
  85. again two variants.  In the simplest variant, the GNU linker (GNU `ld')
  86. and an `a.out' format must be used.  In this case,
  87. `ASM_OUTPUT_CONSTRUCTOR' is defined to produce a `.stabs' entry of type
  88. `N_SETT', referencing the name `__CTOR_LIST__', and with the address of
  89. the void function containing the initialization code as its value.  The
  90. GNU linker recognizes this as a request to add the value to a "set";
  91. the values are accumulated, and are eventually placed in the executable
  92. as a vector in the format described above, with a leading (ignored)
  93. count and a trailing zero element.  `ASM_OUTPUT_DESTRUCTOR' is handled
  94. similarly.  Since no init section is available, the absence of
  95. `INIT_SECTION_ASM_OP' causes the compilation of `main' to call `__main'
  96. as above, starting the initialization process.
  97.    The last variant uses neither arbitrary sections nor the GNU linker.
  98. This is preferable when you want to do dynamic linking and when using
  99. file formats which the GNU linker does not support, such as `ECOFF'.  In
  100. this case, `ASM_OUTPUT_CONSTRUCTOR' does not produce an `N_SETT'
  101. symbol; initialization and termination functions are recognized simply
  102. by their names.  This requires an extra program in the linkage step,
  103. called `collect2'.  This program pretends to be the linker, for use
  104. with GNU CC; it does its job by running the ordinary linker, but also
  105. arranges to include the vectors of initialization and termination
  106. functions.  These functions are called via `__main' as described above.
  107.    Choosing among these configuration options has been simplified by a
  108. set of operating-system-dependent files in the `config' subdirectory.
  109. These files define all of the relevant parameters.  Usually it is
  110. sufficient to include one into your specific machine-dependent
  111. configuration file.  These files are:
  112. `aoutos.h'
  113.      For operating systems using the `a.out' format.
  114. `next.h'
  115.      For operating systems using the `MachO' format.
  116. `svr3.h'
  117.      For System V Release 3 and similar systems using `COFF' format.
  118. `svr4.h'
  119.      For System V Release 4 and similar systems using `ELF' format.
  120. `vms.h'
  121.      For the VMS operating system.
  122.    The following section describes the specific macros that control and
  123. customize the handling of initialization and termination functions.
  124. File: gcc.info,  Node: Macros for Initialization,  Next: Instruction Output,  Prev: Initialization,  Up: Assembler Format
  125. Macros Controlling Initialization Routines
  126. ------------------------------------------
  127.    Here are the macros that control how the compiler handles
  128. initialization and termination functions:
  129. `INIT_SECTION_ASM_OP'
  130.      If defined, a C string constant for the assembler operation to
  131.      identify the following data as initialization code.  If not
  132.      defined, GNU CC will assume such a section does not exist.  When
  133.      you are using special sections for initialization and termination
  134.      functions, this macro also controls how `crtstuff.c' and
  135.      `libgcc2.c' arrange to run the initialization functions.
  136. `ASM_OUTPUT_CONSTRUCTOR (STREAM, NAME)'
  137.      Define