@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
@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}
environment variable. The @sc{gnu} linker will ignore the @code{-F}
option when not creating an ELF shared object.
+@cindex finalization function
+@kindex -fini
+@item -fini @var{name}
+When creating an ELF executable or shared object, call NAME when the
+executable or shared object is unloaded, by setting DT_FINI to the
+address of the function. By default, the linker uses @code{_fini} as
+the function to call.
+
@kindex -g
@item -g
Ignored. Provided for compatibility with other tools.
@item -i
Perform an incremental link (same as option @samp{-r}).
+@cindex initialization function
+@kindex -init
+@item -init @var{name}
+When creating an ELF executable or shared object, call NAME when the
+executable or shared object is loaded, by setting DT_INIT to the address
+of the function. By default, the linker uses @code{_init} as the
+function to call.
+
@cindex archive files, from cmd line
@kindex -l@var{archive}
@kindex --library=@var{archive}
@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
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.
@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
*(.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
@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
@node Output Section LMA
@subsubsection Output section LMA
+@kindex AT>@var{lma_region}
@kindex AT(@var{lma})
@cindex load address
@cindex section load 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
@samp{.text} section from @file{file3}. The notation @samp{= 0x1234}
specifies what data to write in the gaps (@pxref{Output Section Fill}).
+@cindex dot inside sections
+Note: @code{.} actually refers to the byte offset from the start of the
+current containing object. Normally this is the @code{SECTIONS}
+statement, whoes start address is 0, hence @code{.} can be used as an
+absolute address. If @code{.} is used inside a section description
+however, it refers to the byte offset from the start of that section,
+not an absolute address. Thus in a script like this:
+
+@smallexample
+SECTIONS
+@{
+ . = 0x100
+ .text: @{
+ *(.text)
+ . = 0x200
+ @}
+ . = 0x500
+ .data: @{
+ *(.data)
+ . += 0x600
+ @}
+@}
+@end smallexample
+
+The @samp{.text} section will be assigned a starting address of 0x100
+and a size of exactly 0x200 bytes, even if there is not enough data in
+the @samp{.text} input sections to fill this area. (If there is too
+much data, an error will be produced because this would be an attempt to
+move @code{.} backwards). The @samp{.data} section will start at 0x500
+and it will have an extra 0x600 bytes worth of space after the end of
+the values from the @samp{.data} input sections and before the end of
+the @samp{.data} output section itself.
+
@need 2000
@node Operators
@subsection Operators