Document semicolon usage.
This commit is contained in:
David Edelsohn
parent
7248b4e2d2
commit
67afbceace
764
ld/ld.texinfo
764
ld/ld.texinfo
@ -160,40 +160,8 @@ you have many choices to control its behavior.
|
||||
|
||||
@cindex command line
|
||||
@cindex options
|
||||
Here is a summary of the options you can use on the @code{ld} command
|
||||
line:
|
||||
|
||||
@c FIXME! -relax only avail h8/300, i960. Conditionals screwed in examples.
|
||||
@smallexample
|
||||
ld [ -o @var{output} ] @var{objfile}@dots{}
|
||||
[ -A@var{architecture} ] [ -b @var{input-format} ]
|
||||
[ -Bstatic ] [ -Bdynamic ] [ -Bsymbolic ]
|
||||
[ -c @var{MRI-commandfile} ] [ -d | -dc | -dp ]
|
||||
[ -defsym @var{symbol}=@var{expression} ]
|
||||
[ -dynamic-linker @var{file} ] [ -embedded-relocs ] [ -E ]
|
||||
[ -export-dynamic ] [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
|
||||
[ -format @var{input-format} ] [ -g ] [ -G @var{size} ]
|
||||
[ -help ] [ -i ] [ -l@var{archive} ] [ -L@var{searchdir} ]
|
||||
[ -M ] [ -Map @var{mapfile} ] [ -m @var{emulation} ]
|
||||
[ -N | -n ] [ -noinhibit-exec ] [ -no-keep-memory ]
|
||||
[ -oformat @var{output-format} ] [ -R @var{filename} ]
|
||||
[ -relax ] [ -retain-symbols-file @var{filename} ]
|
||||
[ -r | -Ur ] [ -rpath @var{dir} ] [-rpath-link @var{dir} ]
|
||||
[ -S ] [ -s ] [ -soname @var{name} ] [ -shared ]
|
||||
[ -sort-common ] [ -stats ] [ -T @var{commandfile} ]
|
||||
[ -Ttext @var{org} ] [ -Tdata @var{org} ]
|
||||
[ -Tbss @var{org} ] [ -t ] [ -traditional-format ]
|
||||
[ -u @var{symbol}] [-V] [-v] [ -verbose] [ -version ]
|
||||
[ -warn-common ] [ -warn-constructors] [ -warn-multiple-gp ]
|
||||
[ -warn-once ] [ -y @var{symbol} ] [ -X ] [-x ]
|
||||
[ -( [ archives ] -) ]
|
||||
[ --start-group [ archives ] --end-group ]
|
||||
[ -split-by-reloc @var{count} ] [ -split-by-file ]
|
||||
[ --whole-archive ] [ --no-whole-archive ] [ --wrap @var{symbol} ]
|
||||
@end smallexample
|
||||
|
||||
This plethora of command-line options may seem intimidating, but in
|
||||
actual practice few of them are used in any particular context.
|
||||
The linker supports a plethora of command-line options, but in actual
|
||||
practice few of them are used in any particular context.
|
||||
@cindex standard Unix system
|
||||
For instance, a frequent use of @code{ld} is to link standard Unix
|
||||
object files on a standard, supported Unix system. On such a system, to
|
||||
@ -209,28 +177,17 @@ the library @code{libc.a}, which will come from the standard search
|
||||
directories. (See the discussion of the @samp{-l} option below.)
|
||||
|
||||
The command-line options to @code{ld} may be specified in any order, and
|
||||
may be repeated at will. Repeating most options with a
|
||||
different argument will either have no further effect, or override prior
|
||||
may be repeated at will. Repeating most options with a different
|
||||
argument will either have no further effect, or override prior
|
||||
occurrences (those further to the left on the command line) of that
|
||||
option.
|
||||
|
||||
@ifclear SingleFormat
|
||||
The exceptions---which may meaningfully be used more than once---are
|
||||
@samp{-A}, @samp{-b} (or its synonym @samp{-format}), @samp{-defsym},
|
||||
@samp{-L}, @samp{-l}, @samp{-R}, @samp{-u}, and @samp{-(} (or its
|
||||
synonym @samp{--start-group}).
|
||||
@end ifclear
|
||||
@ifset SingleFormat
|
||||
The exceptions---which may meaningfully be used more than once---are
|
||||
@samp{-A}, @samp{-defsym}, @samp{-L}, @samp{-l}, @samp{-R}, @samp{-u},
|
||||
and @samp{-(} (or its synonym @samp{--start-group}).
|
||||
@end ifset
|
||||
option. Options which may be meaningfully specified more than once are
|
||||
noted in the descriptions below.
|
||||
|
||||
@cindex object files
|
||||
The list of object files to be linked together, shown as @var{objfile}@dots{},
|
||||
may follow, precede, or be mixed in with command-line options, except that
|
||||
an @var{objfile} argument may not be placed between an option and
|
||||
its argument.
|
||||
Non-option arguments are objects files which are to be linked together.
|
||||
They may follow, precede, or be mixed in with command-line options,
|
||||
except that an object file argument may not be placed between an option
|
||||
and its argument.
|
||||
|
||||
Usually the linker is invoked with at least one object file, but you can
|
||||
specify other forms of binary input files using @samp{-l}, @samp{-R},
|
||||
@ -261,10 +218,20 @@ requires them. For example, @samp{--oformat srec} and
|
||||
of multiple-letter options are accepted.
|
||||
|
||||
@table @code
|
||||
@kindex -a@var{keyword}
|
||||
@item -a@var{keyword}
|
||||
This option is supported for HP/UX compatibility. The @var{keyword}
|
||||
argument must be one of the strings @samp{archive}, @samp{shared}, or
|
||||
@samp{default}. @samp{-aarchive} is functionally equivalent to
|
||||
@samp{-Bstatic}, and the other two keywords are functionally equivalent
|
||||
to @samp{-Bdynamic}. This option may be used any number of times.
|
||||
|
||||
@ifset I960
|
||||
@cindex architectures
|
||||
@kindex -A@var{arch}
|
||||
@item -A@var{architecture}
|
||||
@kindex --architecture=@var{arch}
|
||||
@itemx --architecture=@var{architecture}
|
||||
In the current release of @code{ld}, this option is useful only for the
|
||||
Intel 960 family of architectures. In that @code{ld} configuration, the
|
||||
@var{architecture} argument identifies the particular architecture in
|
||||
@ -279,9 +246,11 @@ other architecture families.
|
||||
@ifclear SingleFormat
|
||||
@cindex binary input format
|
||||
@kindex -b @var{format}
|
||||
@kindex --format=@var{format}
|
||||
@cindex input format
|
||||
@cindex input format
|
||||
@item -b @var{input-format}
|
||||
@itemx --format=@var{input-format}
|
||||
@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
|
||||
@ -291,8 +260,7 @@ 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}.
|
||||
formats with @samp{objdump -i}.)
|
||||
@xref{BFD}.
|
||||
|
||||
You may want to use this option if you are linking files with an unusual
|
||||
@ -311,28 +279,11 @@ format from a script, using the command @code{TARGET}; see @ref{Option
|
||||
Commands}.
|
||||
@end ifclear
|
||||
|
||||
@kindex -Bstatic
|
||||
@item -Bstatic
|
||||
Do not link against shared libraries. This is only meaningful on
|
||||
platforms for which shared libraries are supported.
|
||||
|
||||
@kindex -Bdynamic
|
||||
@item -Bdynamic
|
||||
Link against dynamic libraries. This is only meaningful on platforms
|
||||
for which shared libraries are supported. This option is normally the
|
||||
default on such platforms.
|
||||
|
||||
@kindex -Bsymbolic
|
||||
@item -Bsymbolic
|
||||
When creating a shared library, bind references to global symbols to the
|
||||
definition within the shared library, if any. Normally, it is possible
|
||||
for a program linked against a shared library to override the definition
|
||||
within the shared library. This option is only meaningful on ELF
|
||||
platforms which support shared libraries.
|
||||
|
||||
@kindex -c @var{MRI-cmdfile}
|
||||
@kindex --mri-script=@var{MRI-cmdfile}
|
||||
@cindex compatibility, MRI
|
||||
@item -c @var{MRI-commandfile}
|
||||
@itemx --mri-script=@var{MRI-commandfile}
|
||||
For compatibility with linkers produced by MRI, @code{ld} accepts script
|
||||
files written in an alternate, restricted command language, described in
|
||||
@ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
|
||||
@ -355,43 +306,11 @@ specified (with @samp{-r}). The script command
|
||||
@code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Option
|
||||
Commands}.
|
||||
|
||||
@cindex symbols, from command line
|
||||
@kindex -defsym @var{symbol}=@var{exp}
|
||||
@item -defsym @var{symbol}=@var{expression}
|
||||
Create a global symbol in the output file, containing the absolute
|
||||
address given by @var{expression}. You may use this option as many
|
||||
times as necessary to define multiple symbols in the command line. A
|
||||
limited form of arithmetic is supported for the @var{expression} in this
|
||||
context: you may give a hexadecimal constant or the name of an existing
|
||||
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
|
||||
constants or symbols. If you need more elaborate expressions, consider
|
||||
using the linker command language from a script (@pxref{Assignment, ,
|
||||
Assignment: Symbol Definitions}). @emph{Note:} there should be no
|
||||
white space between @var{symbol}, the equals sign (``@key{=}''), and
|
||||
@var{expression}.
|
||||
|
||||
@ifset GENERIC
|
||||
@cindex dynamic linker, from command line
|
||||
@kindex -dynamic-linker @var{file}
|
||||
@item -dynamic-linker @var{file}
|
||||
Set the name of the dynamic linker. This is only meaningful when
|
||||
generating dynamically linked ELF executables. The default dynamic
|
||||
linker is normally correct; don't use this unless you know what you are
|
||||
doing.
|
||||
@end ifset
|
||||
|
||||
@cindex MIPS embedded PIC code
|
||||
@kindex -embedded-relocs
|
||||
@item -embedded-relocs
|
||||
This option is only meaningful when linking MIPS embedded PIC code,
|
||||
generated by the -membedded-pic option to the @sc{gnu} compiler and
|
||||
assembler. It causes the linker to create a table which may be used at
|
||||
runtime to relocate any data which was statically initialized to pointer
|
||||
values. See the code in testsuite/ld-empic for details.
|
||||
|
||||
@cindex entry point, from command line
|
||||
@kindex -e @var{entry}
|
||||
@kindex --entry=@var{entry}
|
||||
@item -e @var{entry}
|
||||
@itemx --entry=@var{entry}
|
||||
Use @var{entry} as the explicit symbol for beginning execution of your
|
||||
program, rather than the default entry point. @xref{Entry Point}, for a
|
||||
discussion of defaults and other ways of specifying the
|
||||
@ -402,10 +321,10 @@ entry point.
|
||||
@kindex -export-dynamic
|
||||
@item -E
|
||||
@itemx -export-dynamic
|
||||
When creating an ELF file, add all symbols to the dynamic symbol table.
|
||||
Normally, the dynamic symbol table contains only symbols which are used
|
||||
by a dynamic object. This option is needed for some uses of
|
||||
@code{dlopen}.
|
||||
When creating a dynamically linked executable, add all symbols to the
|
||||
dynamic symbol table. Normally, the dynamic symbol table contains only
|
||||
symbols which are used by a dynamic object. This option is needed for
|
||||
some uses of @code{dlopen}.
|
||||
|
||||
@ifclear SingleFormat
|
||||
@kindex -F
|
||||
@ -419,10 +338,6 @@ option or the @code{TARGET} command in linker scripts for output files,
|
||||
the @code{GNUTARGET} environment variable) are more flexible, but
|
||||
@code{ld} accepts the @samp{-F} option for compatibility with scripts
|
||||
written to call the old linker.
|
||||
|
||||
@kindex -format
|
||||
@item -format @var{input-format}
|
||||
Synonym for @samp{-b @var{input-format}}.
|
||||
@end ifclear
|
||||
|
||||
@kindex -g
|
||||
@ -430,17 +345,25 @@ Synonym for @samp{-b @var{input-format}}.
|
||||
Ignored. Provided for compatibility with other tools.
|
||||
|
||||
@kindex -G
|
||||
@kindex --gpsize
|
||||
@cindex object size
|
||||
@item -G@var{value}
|
||||
@itemx -G @var{value}
|
||||
@itemx --gpsize=@var{value}
|
||||
Set the maximum size of objects to be optimized using the GP register to
|
||||
@var{size} under MIPS ECOFF. Ignored for other object file formats.
|
||||
@var{size}. This is only meaningful for object file formats such as
|
||||
MIPS ECOFF which supports putting large and small objects into different
|
||||
sections. This is ignored for other object file formats.
|
||||
|
||||
@cindex help
|
||||
@cindex usage
|
||||
@kindex -help
|
||||
@item -help
|
||||
Print a summary of the command-line options on the standard output and exit.
|
||||
@cindex runtime library name
|
||||
@kindex -h@var{name}
|
||||
@kindex -soname=@var{name}
|
||||
@item -h@var{name}
|
||||
@itemx -soname=@var{name}
|
||||
When creating an ELF shared object, set the internal DT_SONAME field to
|
||||
the specified name. When an executable is linked with a shared object
|
||||
which has a DT_SONAME field, then when the executable is run the dynamic
|
||||
linker will attempt to load the shared object specified by the DT_SONAME
|
||||
field rather than the using the file name given to the linker.
|
||||
|
||||
@kindex -i
|
||||
@cindex incremental link
|
||||
@ -449,16 +372,20 @@ Perform an incremental link (same as option @samp{-r}).
|
||||
|
||||
@cindex archive files, from cmd line
|
||||
@kindex -l@var{archive}
|
||||
@item -l@var{ar}
|
||||
Add archive file @var{archive} to the list of files to link. This
|
||||
@kindex --library=@var{archive}
|
||||
@item -l@var{archive}
|
||||
@itemx --library=@var{archive}
|
||||
Add archive file @var{archive} to the list of files to link. This
|
||||
option may be used any number of times. @code{ld} will search its
|
||||
path-list for occurrences of @code{lib@var{ar}.a} for every @var{archive}
|
||||
specified.
|
||||
path-list for occurrences of @code{lib@var{archive}.a} for every
|
||||
@var{archive} specified. File extensions other than @code{.a} may be
|
||||
used on certain systems.
|
||||
|
||||
@cindex search directory, from cmd line
|
||||
@kindex -L@var{dir}
|
||||
@kindex --library-path=@var{dir}
|
||||
@item -L@var{searchdir}
|
||||
@itemx -L @var{searchdir}
|
||||
@itemx --library-path=@var{searchdir}
|
||||
Add path @var{searchdir} to the list of paths that @code{ld} will search
|
||||
for archive libraries and @code{ld} control scripts. You may use this
|
||||
option any number of times. The directories are searched in the order
|
||||
@ -477,13 +404,282 @@ The paths can also be specified in a link script with the
|
||||
@code{SEARCH_DIR} command. Directories specified this way are searched
|
||||
at the point in which the linker script appears in the command line.
|
||||
|
||||
@cindex emulation
|
||||
@kindex -m @var{emulation}
|
||||
@item -m@var{emulation}
|
||||
Emulate the @var{emulation} linker. You can list the available
|
||||
emulations with the @samp{--verbose} or @samp{-V} options. The default
|
||||
depends on how your @code{ld} was configured.
|
||||
|
||||
@cindex link map
|
||||
@kindex -M
|
||||
@item -M
|
||||
@kindex --print-map
|
||||
@item -M
|
||||
@itemx --print-map
|
||||
Print (to the standard output) a link map---diagnostic information about
|
||||
where symbols are mapped by @code{ld}, and information on global common
|
||||
storage allocation.
|
||||
|
||||
@kindex -n
|
||||
@cindex read-only text
|
||||
@cindex NMAGIC
|
||||
@kindex --nmagic
|
||||
@item -n
|
||||
@itemx --nmagic
|
||||
Set the text segment to be read only, and mark the output as
|
||||
@code{NMAGIC} if possible.
|
||||
|
||||
@kindex -N
|
||||
@kindex --omagic
|
||||
@cindex read/write from cmd line
|
||||
@cindex OMAGIC
|
||||
@item -N
|
||||
@itemx --omagic
|
||||
Set the text and data sections to be readable and writable. Also, do
|
||||
not page-align the data segment. If the output format supports Unix
|
||||
style magic numbers, mark the output as @code{OMAGIC}.
|
||||
|
||||
@kindex -o @var{output}
|
||||
@kindex --output=@var{output}
|
||||
@cindex naming the output file
|
||||
@item -o @var{output}
|
||||
@itemx --output=@var{output}
|
||||
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.
|
||||
|
||||
@cindex partial link
|
||||
@cindex relocatable output
|
||||
@kindex -r
|
||||
@kindex --relocateable
|
||||
@item -r
|
||||
@itemx --relocateable
|
||||
Generate relocatable output---i.e., generate an output file that can in
|
||||
turn serve as input to @code{ld}. This is often called @dfn{partial
|
||||
linking}. As a side effect, in environments that support standard Unix
|
||||
magic numbers, this option also sets the output file's magic number to
|
||||
@code{OMAGIC}.
|
||||
@c ; see @code{-N}.
|
||||
If this option is not specified, an absolute file is produced. When
|
||||
linking C++ programs, this option @emph{will not} resolve references to
|
||||
constructors; to do that, use @samp{-Ur}.
|
||||
|
||||
This option does the same thing as @samp{-i}.
|
||||
|
||||
@kindex -R @var{file}
|
||||
@kindex --just-symbols=@var{file}
|
||||
@cindex symbol-only input
|
||||
@item -R @var{filename}
|
||||
@itemx --just-symbols=@var{filename}
|
||||
Read symbol names and their addresses from @var{filename}, but do not
|
||||
relocate it or include it in the output. This allows your output file
|
||||
to refer symbolically to absolute locations of memory defined in other
|
||||
programs. You may use this option more than once.
|
||||
|
||||
For compatibility with other ELF linkers, if the @code{-R} option is
|
||||
followed by a directory name, rather than a file name, it is treated as
|
||||
the @code{-rpath} option.
|
||||
|
||||
@kindex -s
|
||||
@kindex --strip-all
|
||||
@cindex strip all symbols
|
||||
@item -s
|
||||
@itemx --strip-all
|
||||
Omit all symbol information from the output file.
|
||||
|
||||
@kindex -S
|
||||
@kindex --strip-debug
|
||||
@cindex strip debugger symbols
|
||||
@item -S
|
||||
@itemx --strip-debug
|
||||
Omit debugger symbol information (but not all symbols) from the output file.
|
||||
|
||||
@kindex -t
|
||||
@kindex --trace
|
||||
@cindex input files, displaying
|
||||
@item -t
|
||||
@itemx --trace
|
||||
Print the names of the input files as @code{ld} processes them.
|
||||
|
||||
@kindex -T @var{script}
|
||||
@kindex --script=@var{script}
|
||||
@cindex script files
|
||||
@item -T @var{commandfile}
|
||||
@itemx --script=@var{commandfile}
|
||||
Read link commands from the file @var{commandfile}. These commands
|
||||
replace @code{ld}'s default link script (rather than adding
|
||||
to it), so @var{commandfile} must specify everything necessary to describe
|
||||
the target format. @xref{Commands}. If @var{commandfile} does not
|
||||
exist, @code{ld} looks for it in the directories specified by any
|
||||
preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
|
||||
|
||||
@kindex -u @var{symbol}
|
||||
@kindex --undefined=@var{symbol}
|
||||
@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.
|
||||
|
||||
@kindex -v
|
||||
@kindex -V
|
||||
@kindex --version
|
||||
@cindex version
|
||||
@item -v
|
||||
@itemx --version
|
||||
@itemx -V
|
||||
Display the version number for @code{ld}. The @code{-V} option also
|
||||
lists the supported emulations.
|
||||
|
||||
@kindex -x
|
||||
@kindex --discard-all
|
||||
@cindex deleting local symbols
|
||||
@item -x
|
||||
@itemx --discard-all
|
||||
Delete all local symbols.
|
||||
|
||||
@kindex -X
|
||||
@kindex --discard-locals
|
||||
@cindex local symbols, deleting
|
||||
@cindex L, deleting symbols beginning
|
||||
@item -X
|
||||
@itemx --discard-locals
|
||||
Delete all temporary local symbols. For most targets, this is all local
|
||||
symbols whose names begin with @samp{L}.
|
||||
|
||||
@kindex -y @var{symbol}
|
||||
@kindex --trace-symbol=@var{symbol}
|
||||
@cindex symbol tracing
|
||||
@item -y @var{symbol}
|
||||
@itemx --trace-symbol=@var{symbol}
|
||||
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
|
||||
to prepend an underscore.
|
||||
|
||||
This option is useful when you have an undefined symbol in your link but
|
||||
don't know where the reference is coming from.
|
||||
|
||||
@kindex -Y @var{path}
|
||||
@item -Y @var{path}
|
||||
Add @var{path} to the default library search path. This option exists
|
||||
for Solaris compatibility.
|
||||
|
||||
@kindex -z @var{keyword}
|
||||
@item -z @var{keyword}
|
||||
This option is ignored for Solaris compatibility.
|
||||
|
||||
@kindex -(
|
||||
@cindex groups of archives
|
||||
@item -( @var{archives} -)
|
||||
@itemx --start-group @var{archives} --end-group
|
||||
The @var{archives} should be a list of archive files. They may be
|
||||
either explicit file names, or @samp{-l} options.
|
||||
|
||||
The specified archives are searched repeatedly until no new undefined
|
||||
references are created. Normally, an archive is searched only once in
|
||||
the order that it is specified on the command line. If a symbol in that
|
||||
archive is needed to resolve an undefined symbol referred to by an
|
||||
object in an archive that appears later on the command line, the linker
|
||||
would not be able to resolve that reference. By grouping the archives,
|
||||
they all be searched repeatedly until all possible references are
|
||||
resolved.
|
||||
|
||||
Using this option has a significant performance cost. It is best to use
|
||||
it only when there are unavoidable circular references between two or
|
||||
more archives.
|
||||
|
||||
@kindex -assert @var{keyword}
|
||||
@item -assert @var{keyword}
|
||||
This option is ignored for SunOS compatibility.
|
||||
|
||||
@kindex -Bdynamic
|
||||
@kindex -dy
|
||||
@kindex -call_shared
|
||||
@item -Bdynamic
|
||||
@itemx -dy
|
||||
@itemx -call_shared
|
||||
Link against dynamic libraries. This is only meaningful on platforms
|
||||
for which shared libraries are supported. This option is normally the
|
||||
default on such platforms. The different variants of this option are
|
||||
for compatibility with various systems. You may use this option
|
||||
multiple times on the command line: it affects library searching for
|
||||
@code{-l} options which follow it.
|
||||
|
||||
@kindex -Bstatic
|
||||
@kindex -dn
|
||||
@kindex -non_shared
|
||||
@kindex -static
|
||||
@item -Bstatic
|
||||
@itemx -dn
|
||||
@itemx -non_shared
|
||||
@itemx -static
|
||||
Do not link against shared libraries. This is only meaningful on
|
||||
platforms for which shared libraries are supported. The different
|
||||
variants of this option are for compatibility with various systems. You
|
||||
may use this option multiple times on the command line: it affects
|
||||
library searching for @code{-l} options which follow it.
|
||||
|
||||
@kindex -Bsymbolic
|
||||
@item -Bsymbolic
|
||||
When creating a shared library, bind references to global symbols to the
|
||||
definition within the shared library, if any. Normally, it is possible
|
||||
for a program linked against a shared library to override the definition
|
||||
within the shared library. This option is only meaningful on ELF
|
||||
platforms which support shared libraries.
|
||||
|
||||
@cindex symbols, from command line
|
||||
@kindex --defsym @var{symbol}=@var{exp}
|
||||
@item --defsym @var{symbol}=@var{expression}
|
||||
Create a global symbol in the output file, containing the absolute
|
||||
address given by @var{expression}. You may use this option as many
|
||||
times as necessary to define multiple symbols in the command line. A
|
||||
limited form of arithmetic is supported for the @var{expression} in this
|
||||
context: you may give a hexadecimal constant or the name of an existing
|
||||
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
|
||||
constants or symbols. If you need more elaborate expressions, consider
|
||||
using the linker command language from a script (@pxref{Assignment, ,
|
||||
Assignment: Symbol Definitions}). @emph{Note:} there should be no
|
||||
white space between @var{symbol}, the equals sign (``@key{=}''), and
|
||||
@var{expression}.
|
||||
|
||||
@cindex dynamic linker, from command line
|
||||
@kindex --dynamic-linker @var{file}
|
||||
@item --dynamic-linker @var{file}
|
||||
Set the name of the dynamic linker. This is only meaningful when
|
||||
generating dynamically linked ELF executables. The default dynamic
|
||||
linker is normally correct; don't use this unless you know what you are
|
||||
doing.
|
||||
|
||||
@cindex big-endian objects
|
||||
@cindex endianness
|
||||
@kindex -EB
|
||||
@item -EB
|
||||
Link big-endian objects. This affects the default output format.
|
||||
|
||||
@cindex little-endian objects
|
||||
@kindex -EL
|
||||
@item -EL
|
||||
Link little-endian objects. This affects the default output format.
|
||||
|
||||
@cindex MIPS embedded PIC code
|
||||
@kindex -embedded-relocs
|
||||
@item -embedded-relocs
|
||||
This option is only meaningful when linking MIPS embedded PIC code,
|
||||
generated by the -membedded-pic option to the @sc{gnu} compiler and
|
||||
assembler. It causes the linker to create a table which may be used at
|
||||
runtime to relocate any data which was statically initialized to pointer
|
||||
values. See the code in testsuite/ld-empic for details.
|
||||
|
||||
@cindex help
|
||||
@cindex usage
|
||||
@kindex --help
|
||||
@item --help
|
||||
Print a summary of the command-line options on the standard output and exit.
|
||||
|
||||
@cindex link map
|
||||
@kindex -Map
|
||||
@item -Map @var{mapfile}
|
||||
@ -491,52 +687,27 @@ Print to the file @var{mapfile} a link map---diagnostic information
|
||||
about where symbols are mapped by @code{ld}, and information on global
|
||||
common storage allocation.
|
||||
|
||||
@cindex emulation
|
||||
@kindex -m @var{emulation}
|
||||
@item -m@var{emulation}
|
||||
@itemx -m @var{emulation}
|
||||
Emulate the @var{emulation} linker. You can list the available
|
||||
emulations with the @samp{--verbose} or @samp{-V} options. The default
|
||||
depends on how your @code{ld} was configured.
|
||||
|
||||
@kindex -N
|
||||
@cindex read/write from cmd line
|
||||
@kindex OMAGIC
|
||||
@item -N
|
||||
Set the text and data sections to be readable and writable. Also, do
|
||||
not page-align the data segment. If the output format supports Unix
|
||||
style magic numbers, mark the output as @code{OMAGIC}.
|
||||
|
||||
@kindex -n
|
||||
@cindex read-only text
|
||||
@kindex NMAGIC
|
||||
@item -n
|
||||
Set the text segment to be read only, and mark the output as
|
||||
@code{NMAGIC} if possible.
|
||||
|
||||
@cindex output file after errors
|
||||
@kindex -noinhibit-exec
|
||||
@item -noinhibit-exec
|
||||
Retain the executable output file whenever it is still usable.
|
||||
Normally, the linker will not produce an output file if it encounters
|
||||
errors during the link process; it exits without writing an output file
|
||||
when it issues any error whatsoever.
|
||||
|
||||
@cindex memory usage
|
||||
@kindex -no-keep-memory
|
||||
@item -no-keep-memory
|
||||
@kindex --no-keep-memory
|
||||
@item --no-keep-memory
|
||||
@code{ld} normally optimizes for speed over memory usage by caching the
|
||||
symbol tables of input files in memory. This option tells @code{ld} to
|
||||
instead optimize for memory usage, by rereading the symbol tables as
|
||||
necessary. This may be required if @code{ld} runs out of memory space
|
||||
while linking a large executable.
|
||||
|
||||
@kindex -o @var{output}
|
||||
@cindex naming the output file
|
||||
@item -o @var{output}
|
||||
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 --no-whole-archive
|
||||
@item --no-whole-archive
|
||||
Turn off the effect of the @code{--whole-archive} option for subsequent
|
||||
archive files.
|
||||
|
||||
@cindex output file after errors
|
||||
@kindex --noinhibit-exec
|
||||
@item --noinhibit-exec
|
||||
Retain the executable output file whenever it is still usable.
|
||||
Normally, the linker will not produce an output file if it encounters
|
||||
errors during the link process; it exits without writing an output file
|
||||
when it issues any error whatsoever.
|
||||
|
||||
@ifclear SingleFormat
|
||||
@kindex -oformat
|
||||
@ -554,25 +725,21 @@ command @code{OUTPUT_FORMAT} can also specify the output format, but
|
||||
this option overrides it. @xref{BFD}.
|
||||
@end ifclear
|
||||
|
||||
@kindex -R @var{file}
|
||||
@cindex symbol-only input
|
||||
@item -R @var{filename}
|
||||
Read symbol names and their addresses from @var{filename}, but do not
|
||||
relocate it or include it in the output. This allows your output file
|
||||
to refer symbolically to absolute locations of memory defined in other
|
||||
programs.
|
||||
@kindex -qmagic
|
||||
@item -qmagic
|
||||
This option is ignored for Linux compatibility.
|
||||
|
||||
For compatibility with other ELF linkers, if the @code{-R} option is
|
||||
followed by a directory name, rather than a file name, it is treated as
|
||||
the @code{-rpath} option.
|
||||
@kindex -Qy
|
||||
@item -Qy
|
||||
This option is ignored for SVR4 compatibility.
|
||||
|
||||
@kindex -relax
|
||||
@kindex --relax
|
||||
@cindex synthesizing linker
|
||||
@cindex relaxing addressing modes
|
||||
@item -relax
|
||||
@item --relax
|
||||
An option with machine dependent effects.
|
||||
@ifset GENERIC
|
||||
Currently this option is only supported on the H8/300 and the Intel 960.
|
||||
This option is only supported on a few targets.
|
||||
@end ifset
|
||||
@ifset H8300
|
||||
@xref{H8/300,,@code{ld} and the H8/300}.
|
||||
@ -581,10 +748,10 @@ Currently this option is only supported on the H8/300 and the Intel 960.
|
||||
@xref{i960,, @code{ld} and the Intel 960 family}.
|
||||
@end ifset
|
||||
|
||||
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.
|
||||
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
|
||||
@ -594,7 +761,7 @@ ignored.
|
||||
@cindex retaining specified symbols
|
||||
@cindex stripping all but some symbols
|
||||
@cindex symbols, retaining selectively
|
||||
@item -retain-symbols-file @var{filename}
|
||||
@item --retain-symbols-file @var{filename}
|
||||
Retain @emph{only} the symbols listed in the file @var{filename},
|
||||
discarding all others. @var{filename} is simply a flat file, with one
|
||||
symbol name per line. This option is especially useful in environments
|
||||
@ -683,109 +850,46 @@ If the required shared library is not found, the linker will issue a
|
||||
warning and continue with the link.
|
||||
@end ifset
|
||||
|
||||
@cindex partial link
|
||||
@cindex relocatable output
|
||||
@kindex -r
|
||||
@item -r
|
||||
Generate relocatable output---i.e., generate an output file that can in
|
||||
turn serve as input to @code{ld}. This is often called @dfn{partial
|
||||
linking}. As a side effect, in environments that support standard Unix
|
||||
magic numbers, this option also sets the output file's magic number to
|
||||
@code{OMAGIC}.
|
||||
@c ; see @code{-N}.
|
||||
If this option is not specified, an absolute file is produced. When
|
||||
linking C++ programs, this option @emph{will not} resolve references to
|
||||
constructors; to do that, use @samp{-Ur}.
|
||||
|
||||
This option does the same thing as @samp{-i}.
|
||||
|
||||
@kindex -S
|
||||
@cindex strip debugger symbols
|
||||
@item -S
|
||||
Omit debugger symbol information (but not all symbols) from the output file.
|
||||
|
||||
@kindex -s
|
||||
@cindex strip all symbols
|
||||
@item -s
|
||||
Omit all symbol information from the output file.
|
||||
|
||||
@ifset GENERIC
|
||||
@cindex runtime library name
|
||||
@kindex -soname
|
||||
@item -soname @var{name}
|
||||
When creating an ELF shared object, set the internal DT_SONAME field to
|
||||
the specified name. When an executable is linked with a shared object
|
||||
which has a DT_SONAME field, then when the executable is run the dynamic
|
||||
linker will attempt to load the shared object specified by the DT_SONAME
|
||||
field rather than the using the file name given to the linker.
|
||||
@end ifset
|
||||
|
||||
@item -shared
|
||||
@cindex shared libraries
|
||||
@kindex -shared
|
||||
Create a shared library. This is currently only supported on ELF and
|
||||
SunOS platforms. On SunOS, the linker will automatically create a
|
||||
@kindex -Bshareable
|
||||
@item -shared
|
||||
@itemx -Bshareable
|
||||
@cindex shared libraries
|
||||
Create a shared library. This is currently only supported on ELF, XCOFF
|
||||
and SunOS platforms. On SunOS, the linker will automatically create a
|
||||
shared library if the @code{-e} option is not used and there are
|
||||
undefined symbols in the link.
|
||||
|
||||
@item -sort-common
|
||||
@kindex -sort-common
|
||||
Normally, when @code{ld} places the global common symbols in the
|
||||
appropriate output sections, it sorts them by size. First come all the
|
||||
one byte symbols, then all the two bytes, then all the four bytes, and
|
||||
then everything else. This is to prevent gaps between symbols due to
|
||||
alignment constraints. This option disables that sorting.
|
||||
@item --sort-common
|
||||
@kindex --sort-common
|
||||
This option tells @code{ld} to sort the common symbols by size when it
|
||||
places them in the appropriate output sections. First come all the one
|
||||
byte symbols, then all the two bytes, then all the four bytes, and then
|
||||
everything else. This is to prevent gaps between symbols due to
|
||||
alignment constraints.
|
||||
|
||||
@kindex split
|
||||
@item -split-by-reloc @var{count}
|
||||
Trys to creates extra sections in the output file so that no single output section
|
||||
in the file contains more than @var{count} relocations. This
|
||||
is useful when generating huge relocatable for downloading into
|
||||
certain real time kernels with the COFF object file format; since
|
||||
COFF cannot represent more than 65535 relocations in a single section.
|
||||
Note that this will fail to work with object file formats which do not
|
||||
support arbitrary sections. The linker will not split up individual input
|
||||
sections for redistribution, so if a single input section contains
|
||||
@kindex --split-by-file
|
||||
@item --split-by-file
|
||||
Similar to @code{--split-by-reloc} but creates a new output section for
|
||||
each input file.
|
||||
|
||||
@kindex --split-by-reloc
|
||||
@item --split-by-reloc @var{count}
|
||||
Trys to creates extra sections in the output file so that no single
|
||||
output section in the file contains more than @var{count} relocations.
|
||||
This is useful when generating huge relocatable for downloading into
|
||||
certain real time kernels with the COFF object file format; since COFF
|
||||
cannot represent more than 65535 relocations in a single section. Note
|
||||
that this will fail to work with object file formats which do not
|
||||
support arbitrary sections. The linker will not split up individual
|
||||
input sections for redistribution, so if a single input section contains
|
||||
more than @var{count} relocations one output section will contain that
|
||||
many relocations.
|
||||
|
||||
@kindex split
|
||||
@item -split-by-file
|
||||
Similar to -split-by-reloc but creates a new output section for each
|
||||
input file.
|
||||
|
||||
@item -stats
|
||||
Compute and display statistics about the operation of the linker,
|
||||
such as execution time and memory usage.
|
||||
|
||||
@kindex -Tbss @var{org}
|
||||
@kindex -Tdata @var{org}
|
||||
@kindex -Ttext @var{org}
|
||||
@cindex segment origins, cmd line
|
||||
@item -Tbss @var{org}
|
||||
@itemx -Tdata @var{org}
|
||||
@itemx -Ttext @var{org}
|
||||
Use @var{org} as the starting address for---respectively---the
|
||||
@code{bss}, @code{data}, or the @code{text} segment of the output file.
|
||||
@var{org} must be a single hexadecimal integer;
|
||||
for compatibility with other linkers, you may omit the leading
|
||||
@samp{0x} usually associated with hexadecimal values.
|
||||
|
||||
@kindex -T @var{script}
|
||||
@cindex script files
|
||||
@item -T @var{commandfile}
|
||||
@itemx -T@var{commandfile}
|
||||
Read link commands from the file @var{commandfile}. These commands
|
||||
replace @code{ld}'s default link script (rather than adding
|
||||
to it), so @var{commandfile} must specify everything necessary to describe
|
||||
the target format. @xref{Commands}. If @var{commandfile} does not
|
||||
exist, @code{ld} looks for it in the directories specified by any
|
||||
preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
|
||||
|
||||
@kindex -t
|
||||
@cindex input files, displaying
|
||||
@item -t
|
||||
Print the names of the input files as @code{ld} processes them.
|
||||
@kindex --stats
|
||||
@item --stats
|
||||
Compute and display statistics about the operation of the linker, such
|
||||
as execution time and memory usage.
|
||||
|
||||
@kindex -traditional-format
|
||||
@cindex traditional format
|
||||
@ -802,15 +906,18 @@ full debugging information by over 30 percent. Unfortunately, the SunOS
|
||||
trouble). The @samp{-traditional-format} switch tells @code{ld} to not
|
||||
combine duplicate entries.
|
||||
|
||||
@kindex -u @var{symbol}
|
||||
@cindex undefined symbol
|
||||
@item -u @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.
|
||||
@kindex -Tbss @var{org}
|
||||
@kindex -Tdata @var{org}
|
||||
@kindex -Ttext @var{org}
|
||||
@cindex segment origins, cmd line
|
||||
@item -Tbss @var{org}
|
||||
@itemx -Tdata @var{org}
|
||||
@itemx -Ttext @var{org}
|
||||
Use @var{org} as the starting address for---respectively---the
|
||||
@code{bss}, @code{data}, or the @code{text} segment of the output file.
|
||||
@var{org} must be a single hexadecimal integer;
|
||||
for compatibility with other linkers, you may omit the leading
|
||||
@samp{0x} usually associated with hexadecimal values.
|
||||
|
||||
@kindex -Ur
|
||||
@cindex constructors
|
||||
@ -831,18 +938,6 @@ Display the version number for @code{ld} and list the linker emulations
|
||||
supported. Display which input files can and cannot be opened. Display
|
||||
the linker script if using a default builtin script.
|
||||
|
||||
@kindex -v
|
||||
@kindex -V
|
||||
@cindex version
|
||||
@item -v
|
||||
@itemx -V
|
||||
Display the version number for @code{ld}. The @code{-V} option also
|
||||
lists the supported emulations.
|
||||
|
||||
@kindex -version
|
||||
@item -version
|
||||
Display the version number for @code{ld} and exit.
|
||||
|
||||
@kindex -warn-comon
|
||||
@cindex warnings, on combining symbols
|
||||
@cindex combining symbols, warnings on
|
||||
@ -963,12 +1058,7 @@ For each archive mentioned on the command line after the
|
||||
in the link, rather than searching the archive for the required object
|
||||
files. This is normally used to turn an archive file into a shared
|
||||
library, forcing every object to be included in the resulting shared
|
||||
library.
|
||||
|
||||
@kindex --no-whole-archive
|
||||
@item --no-whole-archive
|
||||
Turn off the effect of the @code{--whole-archive} option for archives
|
||||
which appear later on the command line.
|
||||
library. This option may be used more than once.
|
||||
|
||||
@kindex --wrap
|
||||
@item --wrap @var{symbol}
|
||||
@ -1004,47 +1094,6 @@ you should not put the definition of @code{__real_malloc} in the same
|
||||
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
|
||||
call before the linker has a chance to wrap it to @code{malloc}.
|
||||
|
||||
@kindex -X
|
||||
@cindex local symbols, deleting
|
||||
@cindex L, deleting symbols beginning
|
||||
@item -X
|
||||
Delete all temporary local symbols. For most targets, this is all local
|
||||
symbols whose names begin with @samp{L}.
|
||||
|
||||
@kindex -x
|
||||
@cindex deleting local symbols
|
||||
@item -x
|
||||
Delete all local symbols.
|
||||
|
||||
@kindex -y @var{symbol}
|
||||
@cindex symbol tracing
|
||||
@item -y @var{symbol}
|
||||
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
|
||||
to prepend an underscore.
|
||||
|
||||
This option is useful when you have an undefined symbol in your link but
|
||||
don't know where the reference is coming from.
|
||||
|
||||
@kindex -(
|
||||
@cindex groups of archives
|
||||
@item -( @var{archives} -)
|
||||
@itemx --start-group @var{archives} --end-group
|
||||
The @var{archives} should be a list of archive files. They may be
|
||||
either explicit file names, or @samp{-l} options.
|
||||
|
||||
The specified archives are searched repeatedly until no new undefined
|
||||
references are created. Normally, an archive is searched only once in
|
||||
the order that it is specified on the command line. If a symbol in that
|
||||
archive is needed to resolve an undefined symbol referred to by an
|
||||
object in an archive that appears later on the command line, the linker
|
||||
would not be able to resolve that reference. By grouping the archives,
|
||||
they all be searched repeatedly until all possible references are
|
||||
resolved.
|
||||
|
||||
Using this option has a significant performance cost. It is best to use
|
||||
it only when there are unavoidable circular references between two or
|
||||
more archives.
|
||||
@end table
|
||||
|
||||
@ifset UsesEnvVars
|
||||
@ -1161,6 +1210,7 @@ You may call special purpose built-in functions.
|
||||
* Evaluation:: Evaluation
|
||||
* Assignment:: Assignment: Defining Symbols
|
||||
* Arithmetic Functions:: Built-In Functions
|
||||
* Semicolons:: Semicolon Usage
|
||||
@end menu
|
||||
|
||||
@node Integers
|
||||
@ -1602,6 +1652,22 @@ paging.
|
||||
|
||||
@end table
|
||||
|
||||
@node Semicolons
|
||||
@subsection Semicolons
|
||||
|
||||
Semicolons (``@key{;}'') are required in the following places. In all
|
||||
other places they can appear for aesthetic reasons but are otherwise ignored.
|
||||
|
||||
@table @code
|
||||
@item Assignment
|
||||
Semicolons must appear at the end of assignment expressions.
|
||||
@xref{Assignment}
|
||||
|
||||
@item PHDRS
|
||||
Semicolons must appear at the end of a @code{PHDRS} statement.
|
||||
@xref{PHDRS}
|
||||
@end table
|
||||
|
||||
@node MEMORY
|
||||
@section Memory Layout
|
||||
@kindex MEMORY
|
||||
|
||||
Loading…
Reference in New Issue
Block a user