* Makefile.am (CGENFILES): Add rtx-funcs.scm.

[deliverable/binutils-gdb.git] / ld / ld.texinfo

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index b23d7c93b7c51eb5e4fa92931bb1acde3df129fb..19427d2b846e767c686b66713df40651415775f0 100644 (file)
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -3,6 +3,7 @@
 @syncodeindex ky cp
 @include configdoc.texi
 @c (configdoc.texi is generated by the Makefile)
+@include ldver.texi
 
 @c @smallbook
 
@@ -15,7 +16,7 @@ END-INFO-DIR-ENTRY
 @end ifinfo
 
 @ifinfo
-This file documents the @sc{gnu} linker LD.
+This file documents the @sc{gnu} linker LD version @value{VERSION}.
 
 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
 
@@ -48,7 +49,7 @@ notice identical to this one except for the removal of this paragraph
 @subtitle The GNU linker
 @sp 1
 @subtitle @code{ld} version 2
-@subtitle April 1998
+@subtitle Version @value{VERSION}
 @author Steve Chamberlain
 @author Ian Lance Taylor
 @author Cygnus Solutions
@@ -85,7 +86,7 @@ into another language, under the above conditions for modified versions.
 @ifinfo
 @node Top
 @top Using ld
-This file documents the @sc{gnu} linker ld.
+This file documents the @sc{gnu} linker ld version @value{VERSION}.
 
 @menu
 * Overview::                    Overview
@@ -553,6 +554,13 @@ Use @var{output} as the name for the program produced by @code{ld}; if this
 option is not specified, the name @file{a.out} is used by default.  The
 script command @code{OUTPUT} can also specify the output file name.
 
+@kindex -O @var{level}
+@cindex generating optimized output
+@item -O @var{level}
+If @var{level} is a numeric values greater than zero @code{ld} optimizes
+the output.  This might take significantly longer and therefore probably
+should only be enabled for the final binary.
+
 @cindex partial link
 @cindex relocatable output
 @kindex -r
@@ -626,12 +634,11 @@ options.  Multiple @samp{-T} options accumulate.
 @cindex undefined symbol
 @item -u @var{symbol}
 @itemx --undefined=@var{symbol}
-Force @var{symbol} to be entered in the output file as an undefined symbol.
-Doing this may, for example, trigger linking of additional modules from
-standard libraries.  @samp{-u} may be repeated with different option
-arguments to enter additional undefined symbols.
-@c Nice idea, but no such command: This option is equivalent
-@c to the @code{EXTERN} linker command.
+Force @var{symbol} to be entered in the output file as an undefined
+symbol.  Doing this may, for example, trigger linking of additional
+modules from standard libraries.  @samp{-u} may be repeated with
+different option arguments to enter additional undefined symbols.  This
+option is equivalent to the @code{EXTERN} linker script command.
 
 @kindex -v
 @kindex -V
@@ -1663,6 +1670,21 @@ command is also used to set the format for the output file.  @xref{BFD}.
 There are a few other linker scripts commands.
 
 @table @code
+@item ASSERT(@var{exp}, @var{message})
+@kindex ASSERT
+@cindex assertion in linker script
+Ensure that @var{exp} is non-zero.  If it is zero, then exit the linker
+with an error code, and print @var{message}.
+
+@item EXTERN(@var{symbol} @var{symbol} @dots{})
+@kindex EXTERN
+@cindex undefined symbol in linker script
+Force @var{symbol} to be entered in the output file as an undefined
+symbol.  Doing this may, for example, trigger linking of additional
+modules from standard libraries.  You may list several @var{symbol}s for
+each @code{EXTERN}, and you may use @code{EXTERN} multiple times.  This
+command has the same effect as the @samp{-u} command-line option.
+
 @item FORCE_COMMON_ALLOCATION
 @kindex FORCE_COMMON_ALLOCATION
 @cindex common allocation in linker script
@@ -2315,10 +2337,20 @@ runtime code expects to see.
       __DTOR_END__ = .;
 @end smallexample
 
+If you are using the @sc{gnu} C++ support for initialization priority,
+which provides some control over the order in which global constructors
+are run, you must sort the constructors at link time to ensure that they
+are executed in the correct order.  When using the @code{CONSTRUCTORS}
+command, use @samp{SORT(CONSTRUCTORS)} instead.  When using the
+@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and
+@samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and
+@samp{*(.dtors)}.
+
 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.
+
 @end table
 
 @node Output Section Discarding