2000-02-27 Mark Elbrecht <snowball3@bigfoot.com>

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

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 115f7a2e6ecf19429ba1db812446b453902685a1..8ecdef2ba04daefa1fa45ca3d9a0d7f49e463f7f 100644 (file)
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -18,7 +18,7 @@ END-INFO-DIR-ENTRY
 @ifinfo
 This file documents the @sc{gnu} linker LD version @value{VERSION}.
 
-Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
+Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -228,6 +228,21 @@ requires them.  For example, @samp{--oformat srec} and
 @samp{--oformat=srec} are equivalent.  Unique abbreviations of the names
 of multiple-letter options are accepted.
 
+Note - if the linker is being invoked indirectly, via a compiler driver
+(eg @samp{gcc}) then all the linker command line options should be
+prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
+compiler driver) like this:
+
+@smallexample
+  gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+@end smallexample
+
+This is important, because otherwise the compiler driver program may
+silently drop the linker options, resulting in a bad link.
+
+Here is a table of the generic command line switches accepted by the GNU
+linker:
+
 @table @code
 @kindex -a@var{keyword}
 @item -a@var{keyword}
@@ -544,8 +559,8 @@ which caused the archive member to be brought in.
 @kindex --nmagic
 @item -n
 @itemx --nmagic
-Set the text segment to be read only, and mark the output as
-@code{NMAGIC} if possible.
+Turn off page alignment of sections, and mark the output as
+@code{NMAGIC} if possible. 
 
 @kindex -N
 @kindex --omagic
@@ -1382,7 +1397,7 @@ option is given.  Note that the symbols @code{DllMain@@12},
 exported.
 
 @kindex --exclude-symbols
-@item --exclude-symbols @var{symbol,symbol,...}
+@item --exclude-symbols @var{symbol},@var{symbol},...
 Specifies a list of symbols which should not be automatically
 exported.  The symbol names may be delimited by commas or colons.
 
@@ -2112,7 +2127,7 @@ The full description of an output section looks like this:
     @var{output-section-command}
     @var{output-section-command}
     @dots{}
-  @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+  @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
 @end group
 @end smallexample
 
@@ -2235,13 +2250,15 @@ include all input @samp{.text} sections, you would write:
 *(.text)
 @end smallexample
 @noindent
-Here the @samp{*} is a wildcard which matches any file name.  To exclude a file
-from matching the file name wildcard, EXCLUDE_FILE may be used to match all files
-except the one specified by EXCLUDE_FILE.  For example:
+Here the @samp{*} is a wildcard which matches any file name.  To exclude a list
+of files from matching the file name wildcard, EXCLUDE_FILE may be used to
+match all files except the ones specified in the EXCLUDE_FILE list.  For
+example:
 @smallexample
-(*(EXCLUDE_FILE (*crtend.o) .ctors))
+(*(EXCLUDE_FILE (*crtend.o, *otherfile.o) .ctors))
 @end smallexample
-will cause all .ctors sections from all files except crtend.o to be included.
+will cause all .ctors sections from all files except crtend.o and otherfile.o
+to be included.
 
 There are two ways to include more than one section:
 @smallexample
@@ -2615,7 +2632,7 @@ like this:
     @var{output-section-command}
     @var{output-section-command}
     @dots{}
-  @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+  @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
 @end group
 @end smallexample
 We've already described @var{section}, @var{address}, and
@@ -2669,6 +2686,7 @@ SECTIONS @{
 
 @node Output Section LMA
 @subsubsection Output section LMA
+@kindex AT>@var{lma_region}
 @kindex AT(@var{lma})
 @cindex load address
 @cindex section load address
@@ -2679,7 +2697,9 @@ Address}).
 
 The linker will normally set the LMA equal to the VMA.  You can change
 that by using the @code{AT} keyword.  The expression @var{lma} that
-follows the @code{AT} keyword specifies the load address of the section.
+follows the @code{AT} keyword specifies the load address of the
+section.  Alternatively, with @samp{AT>@var{lma_region}} expression,
+you may specify a memory region for the section's load address. @xref{MEMORY}.
 
 @cindex ROM initialized data
 @cindex initialized data in ROM