@c (configdoc.texi is generated by the Makefile)
@c @smallbook
-@c @cropmarks
@ifinfo
@format
[ -T @var{commandfile} ]
[ -Ttext @var{org} ] [ -Tdata @var{org} ]
[ -Tbss @var{org} ] [ -t ] [ -u @var{symbol}] [-V] [-v] [ --version ]
- [ -warn-common ] [ -y@var{symbol} ] [ -X ] [-x ]
+ [ -warn-common ] [ -y @var{symbol} ] [ -X ] [-x ]
@end smallexample
This plethora of command-line options may seem intimidating, but in
@cindex input format
@item -b @var{input-format}
@cindex input format
-Specify the binary format for input object files that follow this option
-on the command line. You don't usually need to specify this, as
-@code{ld} is configured to expect as a default input format the most
-usual format on each machine. @var{input-format} is a text string, the
-name of a particular format supported by the BFD libraries.
-(You can list the available binary formats with @samp{objdump -i}.)
-@w{@samp{-format @var{input-format}}} has the same effect, as does the
-script command @code{TARGET}. @xref{BFD}.
+@code{ld} may be configured to support more than one kind of object
+file. If your @code{ld} is configured this way, you can use the
+@samp{-b} option to specify the binary format for input object files
+that follow this option on the command line. Even when @code{ld} is
+configured to support alternative object formats, you don't usually need
+to specify this, as @code{ld} should be configured to expect as a
+default input format the most usual format on each machine.
+@var{input-format} is a text string, the name of a particular format
+supported by the BFD libraries. (You can list the available binary
+formats with @samp{objdump -i}.) @w{@samp{-format @var{input-format}}}
+has the same effect, as does the script command @code{TARGET}.
+@xref{BFD}.
You may want to use this option if you are linking files with an unusual
binary format. You can also use @samp{-b} to switch formats explicitly (when
@itemx -m @var{emulation}
Emulate the @var{emulation} linker. You can list the available
emulations with the @samp{-V} option. The
-default is the system for which you configured @code{ld}.
+default depends on how your @code{ld} was configured.
@kindex -N
@cindex read/write from cmd line
@ifclear SingleFormat
@kindex -oformat
@item -oformat @var{output-format}
-Specify the binary format for the output object file. You don't usually
-need to specify this, as @code{ld} is configured to produce as a default
-output format the most usual format on each machine.
-@var{output-format} is a text string, the name of a particular format
-supported by the BFD libraries. (You can list the available binary
-formats with @samp{objdump -i}.) The script command
-@code{OUTPUT_FORMAT} can also specify the output format, but this option
-overrides it. @xref{BFD}.
+@code{ld} may be configured to support more than one kind of object
+file. If your @code{ld} is configured this way, you can use the
+@samp{-oformat} option to specify the binary format for the output
+object file. Even when @code{ld} is configured to support alternative
+object formats, you don't usually need to specify this, as @code{ld}
+should be configured to produce as a default output format the most
+usual format on each machine. @var{output-format} is a text string, the
+name of a particular format supported by the BFD libraries. (You can
+list the available binary formats with @samp{objdump -i}.) The script
+command @code{OUTPUT_FORMAT} can also specify the output format, but
+this option overrides it. @xref{BFD}.
@end ifclear
@item -R @var{filename}
@kindex -relax
@cindex synthesizing linker
@cindex relaxing addressing modes
-An option with machine dependent effects. Currently this option is only
-supported on the H8/300.
+An option with machine dependent effects.
+@ifset GENERIC
+Currently this option is only supported on the H8/300 and the Intel 960.
+@end ifset
@ifset H8300
@xref{H8/300,,@code{ld} and the H8/300}.
@end ifset
+@ifset I960
+@xref{i960,, @code{ld} and the Intel 960 family}.
+@end ifset
-On some platforms, use option performs global optimizations that
+On some platforms, the @samp{-relax} option performs global optimizations that
become possible when the linker resolves addressing in the program, such
as relaxing address modes and synthesizing new instructions in the
output object file.
+@ifset GENERIC
On platforms where this is not supported, @samp{-relax} is accepted, but
ignored.
+@end ifset
@item -r
@cindex partial link
For anything other than C++ programs, this option is equivalent to
@samp{-r}: it generates relocatable output---i.e., an output file that can in
turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
-@emph{will} resolve references to constructors, unlike @samp{-r}.
+@emph{does} resolve references to constructors, unlike @samp{-r}.
It does not work to use @samp{-Ur} on files that were themselves linked
-with @samp{-Ur}; once the constructor table has been built, it can not
+with @samp{-Ur}; once the constructor table has been built, it cannot
be added to. Use @samp{-Ur} only for the last partial link, and
@samp{-r} for the others.
@item -V
@kindex -V
@cindex version
-Display the version number for @code{ld} and list the supported emulations.
-Display which input files can and can not be opened.
+Display the version number for @code{ld} and list the linker emulations
+supported. Display which input files can and cannot be opened.
@item -v
@kindex -v
If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
not just those beginning with @samp{L}.
-@item -y@var{symbol}
-@kindex -y@var{symbol}
+@item -y @var{symbol}
+@kindex -y @var{symbol}
@cindex symbol tracing
Print the name of each linked file in which @var{symbol} appears. This
option may be given any number of times. On many systems it is necessary
@cindex names
@cindex quoted symbol names
@kindex "
-Unless quoted, symbol names start with a letter, underscore, point or
-hyphen and may include any letters, underscores, digits, points,
-and minus signs. Unquoted symbol names must not conflict with any
+Unless quoted, symbol names start with a letter, underscore, or point
+and may include any letters, underscores, digits, points,
+and hyphens. Unquoted symbol names must not conflict with any
keywords. You can specify a symbol which contains odd characters or has
the same name as a keyword, by surrounding the symbol name in double quotes:
@example
"with a space" = "also with a space" + 10;
@end example
+Since symbols can contain many non-alphabetic characters, it is safest
+to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
+whereas @samp{A - B} is an expression involving subtraction.
+
@node Location Counter
@subsection The Location Counter
@kindex .
command-line options.
@table @code
-@item FLOAT
+@kindex CONSTRUCTORS
+@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; 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}.)
+
@kindex FLOAT
-@itemx NOFLOAT
@kindex NOFLOAT
+@item FLOAT
+@itemx NOFLOAT
These keywords were used in some older linkers to request a particular
math subroutine library. @code{ld} doesn't use the keywords, assuming
instead that any necessary subroutines are in libraries specified using
scripts that were written for the older linkers, the keywords
@code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
-@item FORCE_COMMON_ALLOCATION
@kindex FORCE_COMMON_ALLOCATION
@cindex common allocation
+@item FORCE_COMMON_ALLOCATION
This command has the same effect as the @samp{-d} command-line option:
to make @code{ld} assign space to common symbols even if a relocatable
output file is specified (@samp{-r}).
-@item INPUT ( @var{file}, @var{file}, @dots{} )
@kindex INPUT ( @var{files} )
-@itemx INPUT ( @var{file} @var{file} @dots{} )
@cindex binary input files
+@item INPUT ( @var{file}, @var{file}, @dots{} )
+@itemx INPUT ( @var{file} @var{file} @dots{} )
Use this command to include binary input files in the link, without
including them in a particular section definition.
Specify the full name for each @var{file}, including @samp{.a} if
@item OUTPUT_FORMAT ( @var{bfdname} )
@kindex OUTPUT_FORMAT ( @var{bfdname} )
@cindex format, output file
-Specify a particular output format, with one of the names used by the
-BFD back-end routines (@pxref{BFD}). The effect is identical to the
-effect of the @samp{-oformat} command-line option.
-This selection will only affect
+When @code{ld} is configured to support multiple object code formats,
+you can use this command to specify a particular output format.
+@var{bfdname} is one of the names used by the BFD back-end routines
+(@pxref{BFD}). The effect is identical to the effect of the
+@samp{-oformat} command-line option. This selection affects only
the output file; the related command @code{TARGET} affects primarily
input files.
@end ifclear
@item TARGET ( @var{format} )
@cindex input file format
@kindex TARGET ( @var{format} )
-Change the input-file object code format (like the command-line option
-@samp{-b} or its synonym @samp{-format}). The argument @var{format} is
-one of the strings used by BFD to name binary formats. If @code{TARGET}
-is specified but @code{OUTPUT_FORMAT} is not, the last @code{TARGET}
-argument is also used as the default format for the @code{ld} output
-file. @xref{BFD}.
+When @code{ld} is configured to support multiple object code formats,
+you can use this command to change the input-file object code format
+(like the command-line option @samp{-b} or its synonym @samp{-format}).
+The argument @var{format} is one of the strings used by BFD to name
+binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT}
+is not, the last @code{TARGET} argument is also used as the default
+format for the @code{ld} output file. @xref{BFD}.
@kindex GNUTARGET
If you don't use the @code{TARGET} command, @code{ld} uses the value of
the 960 architecture family allows combination of target architectures; each
use will add another pair of name variants to search for when @w{@samp{-l}}
specifies a library.
+
+@cindex @code{-relax} on i960
+@cindex relaxing on i960
+@code{ld} supports the @samp{-relax} option for the i960 family. If you
+specify @samp{-relax}, @code{ld} finds all @code{balx} and @code{calx}
+instructions whose targets are within 24 bits, and turns them into
+24-bit program-counter relative @code{bal} and @code{cal}
+instructions, respectively. @code{ld} also turns @code{cal}
+instructions into @code{bal} instructions when it determines that the
+target subroutine is a leaf routine (that is, the target subroutine does
+not itself call any subroutines).
+
@ifclear GENERIC
@lowersections
@end ifclear
projects / binutils-gdb.git / commitdiff