\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001 Free Software Foundation, Inc.
+@c 2001, 2002 Free Software Foundation, Inc.
@syncodeindex ky cp
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
This file documents the @sc{gnu} linker LD version @value{VERSION}.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
-2001 Free Software Foundation, Inc.
+2001, 2002 Free Software Foundation, Inc.
@ignore
order to perform correct modifications of executables. This results
in larger executables.
+This option is currently only supported on ELF platforms.
+
@cindex partial link
@cindex relocatable output
@kindex -r
errors during the link process; it exits without writing an output file
when it issues any error whatsoever.
+@kindex -nostdlib
+@item -nostdlib
+Only search library directories explicitly specified on the
+command line. Library directories specified in linker scripts
+(including linker scripts specified on the command line) are ignored.
+
@ifclear SingleFormat
@kindex --oformat
@item --oformat @var{output-format}
current section. It is followed by an expression in parentheses. Any
otherwise unspecified regions of memory within the section (for example,
gaps left due to the required alignment of input sections) are filled
-with the four least significant bytes of the expression, repeated as
+with the value of the expression, repeated as
necessary. A @code{FILL} statement covers memory locations after the
point at which it occurs in the section definition; by including more
than one @code{FILL} statement, you can have different fill patterns in
@end smallexample
The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
-section attribute (@pxref{Output Section Fill}), but it only affects the
+section attribute, but it only affects the
part of the section following the @code{FILL} command, rather than the
entire section. If both are used, the @code{FILL} command takes
-precedence.
+precedence. @xref{Output Section Fill}, for details on the fill
+expression.
@node Output Section Keywords
@subsection Output section keywords
@samp{=@var{fillexp}}. @var{fillexp} is an expression
(@pxref{Expressions}). Any otherwise unspecified regions of memory
within the output section (for example, gaps left due to the required
-alignment of input sections) will be filled with the four least
-significant bytes of the value, repeated as necessary.
+alignment of input sections) will be filled with the value, repeated as
+necessary. If the fill expression is a simple hex number, ie. a string
+of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
+an arbitrarily long sequence of hex digits can be used to specify the
+fill pattern; Leading zeros become part of the pattern too. For all
+other cases, including extra parentheses or a unary @code{+}, the fill
+pattern is the four least significant bytes of the value of the
+expression. In all cases, the number is big-endian.
You can also change the fill value with a @code{FILL} command in the
-output section commands; see @ref{Output Section Data}.
+output section commands; (@pxref{Output Section Data}).
Here is a simple example:
@smallexample
version node defined is @samp{VERS_1.1}; it has no other dependencies.
The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
a number of symbols to local scope so that they are not visible outside
-of the shared library.
+of the shared library; this is done using wildcard patterns, so that any
+symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
+is matched. The wildcard patterns available are the same as those used
+in the shell when matching filenames (also known as ``globbing'').
Next, the version script defines node @samp{VERS_1.2}. This node
depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
could just as well have appeared in between @samp{1.1} and @samp{1.2}.
However, this would be a confusing way to write a version script.
+Node name can be omited, provided it is the only version node
+in the version script. Such version script doesn't assign any versions to
+symbols, only selects which symbols will be globally visible out and which
+won't.
+
+@smallexample
+@{ global: foo; bar; local: *; @}
+@end smallexample
+
When you link an application against a shared library that has versioned
symbols, the application itself knows which version of each symbol it
requires, and it also knows which version nodes it needs from each
scripts. It is most often seen when setting the address of an output
section.
+@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
+@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
+This is equivalent to either
+@smallexample
+(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
+@end smallexample
+or
+@smallexample
+(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
+@end smallexample
+@noindent
+depending on whether the latter uses fewer @var{commonpagesize} sized pages
+for the data segment (area between the result of this expression and
+@code{DATA_SEGMENT_END}) than the former or not.
+If the latter form is used, it means @var{commonpagesize} bytes of runtime
+memory will be saved at the expense of up to @var{commonpagesize} wasted
+bytes in the on-disk file.
+
+This expression can only be used directly in @code{SECTIONS} commands, not in
+any output section descriptions and only once in the linker script.
+@var{commonpagesize} should be less or equal to @var{maxpagesize} and should
+be the system page size the object wants to be optimized for (while still
+working on system page sizes up to @var{maxpagesize}).
+
+@noindent
+Example:
+@smallexample
+ . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
+@end smallexample
+
+@item DATA_SEGMENT_END(@var{exp})
+@kindex DATA_SEGMENT_END(@var{exp})
+This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
+evaluation purposes.
+
+@smallexample
+ . = DATA_SEGMENT_END(.);
+@end smallexample
+
@item DEFINED(@var{symbol})
@kindex DEFINED(@var{symbol})
@cindex symbol defaults