* ld.texinfo: Clarify the CONSTRUCTORS command.

1 files changed, 54 insertions, 12 deletions

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index b6ff46b..bdb7644 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -340,6 +340,17 @@ the @code{GNUTARGET} environment variable) are more flexible, but
 written to call the old linker.
 @end ifclear
 
+@kindex --force-exe-suffix
+@item  --force-exe-suffix
+Make sure that an output file has a .exe suffix.
+
+If a successfully built fully linked output file does not have a
+@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
+the output file to one of the same name with a @code{.exe} suffix. This
+option is useful when using unmodified Unix makefiles on a Microsoft
+Windows host, since some versions of Windows won't run an image unless
+it ends in a @code{.exe} suffix.
+
 @kindex -g
 @item -g
 Ignored.  Provided for compatibility with other tools.
@@ -2481,18 +2492,49 @@ command-line options.
 @cindex C++ constructors, arranging in link
 @cindex constructors, arranging in link
 @item CONSTRUCTORS
-This command ties up C++ style constructor and destructor records.  The
-details of the constructor representation vary from one object format to
-another, but usually lists of constructors and destructors appear as
-special sections.  The @code{CONSTRUCTORS} command specifies where the
-linker is to place the data from these sections, relative to the rest of
-the linked output.  Constructor data is marked by the symbol
-@w{@code{__CTOR_LIST__}} at the start, and @w{@code{__CTOR_LIST_END}} at
-the end; destructor data is bracketed similarly, between
-@w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_LIST_END}}.  (The compiler
-must arrange to actually run this code; @sc{gnu} C++ calls constructors from
-a subroutine @code{__main}, which it inserts automatically into the
-startup code for @code{main}, and destructors from @code{_exit}.)
+When linking using the @code{a.out} object file format, the linker uses
+an unusual set construct to support C++ global constructors and
+destructors.  When linking object file formats which do not support
+arbitrary sections, such as @code{ECOFF} and @code{XCOFF}, the linker
+will automatically recognize C++ global constructors and destructors by
+name.  For these object file formats, the @code{CONSTRUCTORS} command
+tells the linker where this information should be placed.  The
+@code{CONSTRUCTORS} command is ignored for other object file formats.
+
+The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
+constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end.  The
+first word in the list is the number of entries, followed by the address
+of each constructor or destructor, followed by a zero word.  The
+compiler must arrange to actually run the code.  For these object file
+formats @sc{gnu} C++ calls constructors from a subroutine @code{__main};
+a call to @code{__main} is automatically inserted into the startup code
+for @code{main}.  @sc{gnu} C++ runs destructors either by using
+@code{atexit}, or directly from the function @code{exit}.
+
+For object file formats such as @code{COFF} or @code{ELF} which support
+multiple sections, @sc{gnu} C++ will normally arrange to put the
+addresses of global constructors and destructors into the @code{.ctors}
+and @code{.dtors} sections.  Placing the following sequence into your
+linker script will build the sort of table which the @sc{gnu} C++
+runtime code expects to see.
+
+@smallexample
+      __CTOR_LIST__ = .;
+      LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
+      *(.ctors)
+      LONG(0)
+      __CTOR_END__ = .;
+      __DTOR_LIST__ = .;
+      LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
+      *(.dtors)
+      LONG(0)
+      __DTOR_END__ = .;
+@end smallexample
+
+Normally the compiler and linker will handle these issues automatically,
+and you will not need to concern yourself with them.  However, you may
+need to consider this if you are using C++ and writing your own linker
+scripts.
 
 @need 1000
 @kindex FLOAT