Red Hat ENTERPRISE LINUX 3 - USING BINUTILS Manual

Red Hat Enterprise Linux 3
Using ld, the Gnu Linker

Red Hat Enterprise Linux 3: Using ld, the Gnu Linker
Copyright © 1991-2003 by Free Software Foundation, Inc.
Copyright © 2003 by Red Hat, Inc.
This documentation has been prepared by Red Hat, Inc.
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-2072 USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588
Research Triangle Park NC 27709 USA
Manual identifier:
•PDF: rhds-ld-EN-3-PDF-RHI (2003-09-24T01:08)
•HTML: rhds-ld-EN-3-HTML-RHI (2003-09-24T01:08)
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free
Documentation License”.
Red Hat, Inc. is not granting permission to any redistributor to use the Red Hat name.
Red Hat is a registered trademark and the Red Hat Shadow Man logo, RPM, and the RPM logo are trademarks of Red Hat, Inc.
Linux is a registered trademark of Linus Torvalds.
All other trademarks and copyrights referred to are the property of their respective owners.
HTML, PDF, and RPM versions of the manuals are available on the Documentation CD and online at
http://www.redhat.com/docs/.
The GPG fingerprint of the [email protected] key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E

Table of Contents
1. Using ld ............................................................................................................................................ 1
2. Overview .......................................................................................................................................... 3
3. Invocation ........................................................................................................................................ 5
3.1. Command Line Options..................................................................................................... 5
3.1.1. Options Specific to i386 PE Targets ................................................................. 21
3.2. Environment Variables..................................................................................................... 27
4. Linker Scripts................................................................................................................................ 29
4.1. Basic Linker Script Concepts........................................................................................... 29
4.2. Linker Script Format........................................................................................................ 29
4.3. Simple Linker Script Example......................................................................................... 30
4.4. Simple Linker Script Commands..................................................................................... 31
4.4.1. Setting the Entry Point...................................................................................... 31
4.4.2. Commands Dealing with Files.......................................................................... 31
4.4.3. Commands Dealing with Object File Formats.................................................. 32
4.4.4. Other Linker Script Commands ........................................................................ 33
4.5. Assigning Values to Symbols .......................................................................................... 33
4.5.1. Simple Assignments ......................................................................................... 33
4.5.2. PROVIDE.......................................................................................................... 34
4.6. SECTIONS Command..................................................................................................... 35
4.6.1. Output Section Description............................................................................... 35
4.6.2. Output Section Name........................................................................................ 36
4.6.3. Output Section Description............................................................................... 36
4.6.4. Input Section Description ................................................................................. 37
4.6.5. Output Section Data.......................................................................................... 39
4.6.6. Output Section Keywords ................................................................................. 40
4.6.7. Output Section Discarding................................................................................ 41
4.6.8. Output Section Attributes ................................................................................. 42
4.6.9. Overlay Description .......................................................................................... 44
4.7. MEMORY Command ...................................................................................................... 45
4.8. PHDRS Command ........................................................................................................... 47
4.9. VERSION Command....................................................................................................... 49
4.10. Expressions in Linker Scripts ........................................................................................ 51
4.10.1. Constants......................................................................................................... 51
4.10.2. Symbol Names................................................................................................ 51
4.10.3. The Location Counter ..................................................................................... 51
4.10.4. Operators......................................................................................................... 52
4.10.5. Evaluation ....................................................................................................... 53
4.10.6. The Section of an Expression ......................................................................... 53
4.10.7. Builtin Functions............................................................................................. 54
4.11. Implicit Linker Scripts ................................................................................................... 56
5. Machine Dependent Features ...................................................................................................... 59
5.1. ld and the H8/300............................................................................................................ 59
5.2. ld and the Intel 960 Family............................................................................................. 59
5.3. ld’s Support for Interworking Between ARM and Thumb Code ................................... 59
5.4. ld and HPPA 32-bit ELF Support ................................................................................... 60
5.5. ld and MMIX .................................................................................................................. 60
5.6. ld and MSP430 ............................................................................................................... 60
5.7. ld’s Support for Various TI COFF Versions ................................................................... 61
5.8. ld and WIN32 (cygwin/mingw)...................................................................................... 61
5.9. ld and Xtensa Processors ................................................................................................ 65

6. BFD................................................................................................................................................. 67
6.1. How It Works: An Outline of BFD.................................................................................. 67
6.1.1. Information Loss............................................................................................... 67
6.1.2. The BFD canonical object-file format .............................................................. 68
7. Reporting Bugs.............................................................................................................................. 71
7.1. Have You Found a Bug? .................................................................................................. 71
7.2. How to Report Bugs......................................................................................................... 71
A. MRI Compatible Script Files...................................................................................................... 75
B. GNU Free Documentation License ............................................................................................. 77
B.1. ADDENDUM: How to use this License for your documents......................................... 81
Index................................................................................................................................................... 83

Chapter 1.
Using ld
This file documents the gnu linker ld version 2.14.90.0.4.
This document is distributed under the terms of the GNU Free Documentation License. A copy of the
license is included in the section entitled "GNU Free Documentation License".

2 Chapter 1. Using ld

Chapter 2.
Overview
ld combines a number of object and archive files, relocates their data and ties up symbol references.
Usually the last step in compiling a program is to run ld.
ld accepts Linker Command Language files written in a superset of AT&T’s Link Editor Command
Language syntax, to provide explicit and total control over the linking process.
This version of ld uses the general purpose BFD libraries to operate on object files. This allows ld
to read, combine, and write object files in many different formats--for example, COFF or a.out.
Different formats may be linked together to produce any available kind of object file. Refer to Chapter
6BFD, for more information.
Aside from its flexibility, the gnu linker is more helpful than other linkers in providing diagnostic
information. Many linkers abandon execution immediately upon encountering an error; whenever
possible, ld continues executing, allowing you to identify other errors (or, in some cases, to get an
output file in spite of the error).

4 Chapter 2. Overview

Chapter 3.
Invocation
The gnu linker ld is meant to cover a broad range of situations, and to be as compatible as possible
with other linkers. As a result, you have many choices to control its behavior.
3.1. Command Line Options
The linker supports a plethora of command-line options, but in actual practice few of them are used
in any particular context. For instance, a frequent use of ld is to link standard Unix object files on a
standard, supported Unix system. On such a system, to link a file hello.o:
ld -o output /lib/crt0.o hello.o -lc
This tells ld to produce a file called output as the result of linking the file /lib/crt0.o with
hello.o and the library libc.a, which will come from the standard search directories. (See the
discussion of the -l option below.)
Some of the command-line options to ld may be specified at any point in the command line. However,
options which refer to files, such as -l or -T, cause the file to be read at the point at which the option
appears in the command line, relative to the object files and other file options. Repeating non-file
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. Options which may be meaningfully
specified more than once are noted in the descriptions below.
Non-option arguments are object files or archives 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 -l,-R, and the script command language. If no binary input files at all are specified,
the linker does not produce any output, and issues the message No input files.
If the linker cannot recognize the format of an object file, it will assume that it is a linker script. A
script specified in this way augments the main linker script used for the link (either the default linker
script or the one specified by using -T). This feature permits the linker to link against a file which
appears to be an object or an archive, but actually merely defines some symbol values, or uses INPUT
or GROUP to load other objects. Note that specifying a script in this way merely augments the main
linker script; use the -T option to replace the default linker script entirely. Chapter 4 Linker Scripts.
For options whose names are a single letter, option arguments must either follow the option letter
without intervening whitespace, or be given as separate arguments immediately following the option
that requires them.
For options whose names are multiple letters, either one dash or two can precede the option name;
for example, -trace-symbol and -trace-symbol are equivalent. Note--there is one exception to
this rule. Multiple letter options that start with a lower case ’o’ can only be preceeded by two dashes.
This is to reduce confusion with the -o option. So for example -omagic sets the output file name to
magic whereas -omagic sets the NMAGIC flag on the output.
Arguments to multiple-letter options must either be separated from the option name by an equals sign,
or be given as separate arguments immediately following the option that requires them. For example,
-trace-symbol foo and -trace-symbol=foo are equivalent. Unique abbreviations of the names
of multiple-letter options are accepted.

6 Chapter 3. Invocation
Note--if the linker is being invoked indirectly, via a compiler driver (e.g. gcc) then all the linker com-
mand line options should be prefixed by -Wl, (or whatever is appropriate for the particular compiler
driver) like this:
gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
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:
-akeyword
This option is supported for HP/UX compatibility. The keyword argument must be one of the
strings archive,shared, or default.-aarchive is functionally equivalent to -Bstatic,
and the other two keywords are functionally equivalent to -Bdynamic. This option may be used
any number of times.
-Aarchitecture
architecture
-architecture=architecture
In the current release of ld, this option is useful only for the Intel 960 family of architectures. In
that ld configuration, the architecture argument identifies the particular architecture in the
960 family, enabling some safeguards and modifying the archive-library search path. Refer to
Section 5.2 ld and the Intel 960 Family, for details.
Future releases of ld may support similar functionality for other architecture families.
-b input-format
-format=input-format
ld may be configured to support more than one kind of object file. If your ld is configured this
way, you can use the -b option to specify the binary format for input object files that follow this
option on the command line. Even when ld is configured to support alternative object formats,
you don’t usually need to specify this, as ld should be configured to expect as a default input
format the most usual format on each machine. 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
objdump -i.) Chapter 6 BFD.
You may want to use this option if you are linking files with an unusual binary format. You
can also use -b to switch formats explicitly (when linking object files of different formats), by
including -b input-format before each group of object files in a particular format.
The default format is taken from the environment variable GNUTARGET. Section 3.2 Environment
Variables. You can also define the input format from a script, using the command TARGET; see
Section 4.4.3 Commands Dealing with Object File Formats.
-c MRI-commandfile
-mri-script=MRI-commandfile
For compatibility with linkers produced by MRI, ld accepts script files written in an alternate,
restricted command language, described in Appendix A MRI Compatible Script Files. Introduce
MRI script files with the option -c; use the -T option to run linker scripts written in the general-
purpose ld scripting language. If MRI-cmdfile does not exist, ld looks for it in the directories
specified by any -L options.

Chapter 3. Invocation 7
-d
-dc
-dp
These three options are equivalent; multiple forms are supported for compatibility with other
linkers. They assign space to common symbols even if a relocatable output file is specified (with
-r). The script command FORCE_COMMON_ALLOCATION has the same effect. Refer to Section
4.4.4 Other Linker Script Commands.
-e entry
-entry=entry
Use entry as the explicit symbol for beginning execution of your program, rather than the
default entry point. If there is no symbol named entry, the linker will try to parse entry as a
number, and use that as the entry address (the number will be interpreted in base 10; you may
use a leading 0x for base 16, or a leading 0for base 8). Refer to Section 4.4.1 Setting the Entry
Point for a discussion of defaults and other ways of specifying the entry point.
-E
-export-dynamic
When creating a dynamically linked executable, add all symbols to the dynamic symbol table.
The dynamic symbol table is the set of symbols which are visible from dynamic objects at run
time.
If you do not use this option, the dynamic symbol table will normally contain only those symbols
which are referenced by some dynamic object mentioned in the link.
If you use dlopen to load a dynamic object which needs to refer back to the symbols defined
by the program, rather than some other dynamic object, then you will probably need to use this
option when linking the program itself.
You can also use the version script to control what symbols should be added to the dynamic sym-
bol table if the output format supports it. See the description of -version-script in Section
4.9 VERSION Command.
-EB
Link big-endian objects. This affects the default output format.
-EL
Link little-endian objects. This affects the default output format.
-f
-auxiliary name
When creating an ELF shared object, set the internal DT_AUXILIARY field to the specified
name. This tells the dynamic linker that the symbol table of the shared object should be used as
an auxiliary filter on the symbol table of the shared object name.
If you later link a program against this filter object, then, when you run the program, the dynamic
linker will see the DT_AUXILIARY field. If the dynamic linker resolves any symbols from the
filter object, it will first check whether there is a definition in the shared object name. If there
is one, it will be used instead of the definition in the filter object. The shared object name need
not exist. Thus the shared object name may be used to provide an alternative implementation of
certain functions, perhaps for debugging or for machine specific performance.
This option may be specified more than once. The DT_AUXILIARY entries will be created in
the order in which they appear on the command line.

8 Chapter 3. Invocation
-F name
-filter name
When creating an ELF shared object, set the internal DT_FILTER field to the specified name.
This tells the dynamic linker that the symbol table of the shared object which is being created
should be used as a filter on the symbol table of the shared object name.
If you later link a program against this filter object, then, when you run the program, the dynamic
linker will see the DT_FILTER field. The dynamic linker will resolve symbols according to the
symbol table of the filter object as usual, but it will actually link to the definitions found in the
shared object name. Thus the filter object can be used to select a subset of the symbols provided
by the object name.
Some older linkers used the -F option throughout a compilation toolchain for specifying object-
file format for both input and output object files. The gnu linker uses other mechanisms for this
purpose: the -b,-format,-oformat options, the TARGET command in linker scripts, and the
GNUTARGET environment variable. The gnu linker will ignore the -F option when not creating an
ELF shared object.
-fini 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
_fini as the function to call.
-g
Ignored. Provided for compatibility with other tools.
-Gvalue
-gpsize=value
Set the maximum size of objects to be optimized using the GP register to 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.
-hname
-soname=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.
-i
Perform an incremental link (same as option -r).
-init 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
_init as the function to call.
-larchive
-library=archive
Add archive file archive to the list of files to link. This option may be used any number of times.
ld will search its path-list for occurrences of libarchive.a for every archive specified.

Chapter 3. Invocation 9
On systems which support shared libraries, ld may also search for libraries with extensions other
than .a. Specifically, on ELF and SunOS systems, ld will search a directory for a library with
an extension of .so before searching for one with an extension of .a. By convention, a .so
extension indicates a shared library.
The linker will search an archive only once, at the location where it is specified on the command
line. If the archive defines a symbol which was undefined in some object which appeared before
the archive on the command line, the linker will include the appropriate file(s) from the archive.
However, an undefined symbol in an object appearing later on the command line will not cause
the linker to search the archive again.
See the -( option for a way to force the linker to search archives multiple times.
You may list the same archive multiple times on the command line.
This type of archive searching is standard for Unix linkers. However, if you are using ld on AIX,
note that it is different from the behaviour of the AIX linker.
-Lsearchdir
-library-path=searchdir
Add path searchdir to the list of paths that ld will search for archive libraries and ld control
scripts. You may use this option any number of times. The directories are searched in the order
in which they are specified on the command line. Directories specified on the command line are
searched before the default directories. All -L options apply to all -l options, regardless of the
order in which the options appear.
If searchdir begins with =, then the =will be replaced by the sysroot prefix, a path specified
when the linker is configured.
The default set of paths searched (without being specified with -L) depends on which emula-
tion mode ld is using, and in some cases also on how it was configured. Refer to Section 3.2
Environment Variables.
The paths can also be specified in a link script with the SEARCH_DIR command. Directories
specified this way are searched at the point in which the linker script appears in the command
line.
-memulation
Emulate the emulation linker. You can list the available emulations with the -verbose or -V
options.
If the -m option is not used, the emulation is taken from the LDEMULATION environment variable,
if that is defined.
Otherwise, the default emulation depends upon how the linker was configured.
-M
-print-map
Print a link map to the standard output. A link map provides information about the link, including
the following:
•Where object files and symbols are mapped into memory.
•How common symbols are allocated.
•All archive members included in the link, with a mention of the symbol which caused the
archive member to be brought in.

10 Chapter 3. Invocation
-n
-nmagic
Turn off page alignment of sections, and mark the output as NMAGIC if possible.
-N
-omagic
Set the text and data sections to be readable and writable. Also, do not page-align the data seg-
ment, and disable linking against shared libraries. If the output format supports Unix style magic
numbers, mark the output as OMAGIC.
-no-omagic
This option negates most of the effects of the -N option. It sets the text section to be read-only,
and forces the data segment to be page-aligned. Note - this option does not enable linking against
shared libraries. Use -Bdynamic for this.
-o output
-output=output
Use output as the name for the program produced by ld; if this option is not specified, the name
a.out is used by default. The script command OUTPUT can also specify the output file name.
-O level
If level is a numeric values greater than zero ld optimizes the output. This might take signifi-
cantly longer and therefore probably should only be enabled for the final binary.
-q
-emit-relocs
Leave relocation sections and contents in fully linked exececutables. Post link analysis and op-
timization tools may need this information in order to perform correct modifications of executa-
bles. This results in larger executables.
This option is currently only supported on ELF platforms.
-r
-relocateable
Generate relocatable output--i.e., generate an output file that can in turn serve as input to ld.
This is often called 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 OMAGIC. If this option
is not specified, an absolute file is produced. When linking C++ programs, this option will not
resolve references to constructors; to do that, use -Ur.
When an input file does not have the same format as the output file, partial linking is only sup-
ported if that input file does not contain any relocations. Different output formats can have further
restrictions; for example some a.out-based formats do not support partial linking with input files
in other formats at all.
This option does the same thing as -i.

Chapter 3. Invocation 11
-R filename
-just-symbols=filename
Read symbol names and their addresses from 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 -R option is followed by a directory name, rather
than a file name, it is treated as the -rpath option.
-s
-strip-all
Omit all symbol information from the output file.
-S
-strip-debug
Omit debugger symbol information (but not all symbols) from the output file.
-t
-trace
Print the names of the input files as ld processes them.
-T scriptfile
-script=scriptfile
Use scriptfile as the linker script. This script replaces ld’s default linker script (rather than
adding to it), so commandfile must specify everything necessary to describe the output file.
Refer to Chapter 4 Linker Scripts. If scriptfile does not exist in the current directory, ld looks
for it in the directories specified by any preceding -L options. Multiple -T options accumulate.
-u symbol
-undefined=symbol
Force symbol to be entered in the output file as an undefined symbol. Doing this may, for ex-
ample, trigger linking of additional modules from standard libraries. -u may be repeated with
different option arguments to enter additional undefined symbols. This option is equivalent to the
EXTERN linker script command.
-Ur
For anything other than C++ programs, this option is equivalent to -r: it generates relocatable
output--i.e., an output file that can in turn serve as input to ld. When linking C++ programs, -Ur
does resolve references to constructors, unlike -r. It does not work to use -Ur on files that were
themselves linked with -Ur; once the constructor table has been built, it cannot be added to. Use
-Ur only for the last partial link, and -r for the others.
-unique[=SECTION]
Creates a separate output section for every input section matching SECTION, or if the optional
wildcard SECTION argument is missing, for every orphan input section. An orphan section is
one not specifically mentioned in a linker script. You may use this option multiple times on the
command line; It prevents the normal merging of input sections with the same name, overriding
output section assignments in a linker script.

12 Chapter 3. Invocation
-v
-version
-V
Display the version number for ld. The -V option also lists the supported emulations.
-x
-discard-all
Delete all local symbols.
-X
-discard-locals
Delete all temporary local symbols. For most targets, this is all local symbols whose names begin
with L.
-y symbol
-trace-symbol=symbol
Print the name of each linked file in which 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.
-Y path
Add path to the default library search path. This option exists for Solaris compatibility.
-z keyword
The recognized keywords are initfirst,interpose,loadfltr,nodefaultlib,
nodelete,nodlopen,nodump,now,origin,combreloc,nocombreloc and
nocopyreloc. The other keywords are ignored for Solaris compatibility. initfirst marks
the object to be initialized first at runtime before any other objects. interpose marks the
object that its symbol table interposes before all symbols but the primary executable. loadfltr
marks the object that its filtees be processed immediately at runtime. nodefaultlib marks the
object that the search for dependencies of this object will ignore any default library search
paths. nodelete marks the object shouldn’t be unloaded at runtime. nodlopen marks the
object not available to dlopen.nodump marks the object can not be dumped by dldump.now
marks the object with the non-lazy runtime binding. origin marks the object may contain
$ORIGIN. defs disallows undefined symbols. muldefs allows multiple definitions.
combreloc combines multiple reloc sections and sorts them to make dynamic symbol lookup
caching possible. nocombreloc disables multiple reloc sections combining. nocopyreloc
disables production of copy relocs.
-( archives -)
-start-group archives -end-group
The archives should be a list of archive files. They may be either explicit file names, or -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.

Chapter 3. Invocation 13
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.
-accept-unknown-input-arch
-no-accept-unknown-input-arch
Tells the linker to accept input files whose architecture cannot be recognised. The assumption is
that the user knows what they are doing and deliberately wants to link in these unknown input
files. This was the default behaviour of the linker, before release 2.14. The default behaviour from
release 2.14 onwards is to reject such input files, and so the -accept-unknown-input-arch
option has been added to restore the old behaviour.
-assert keyword
This option is ignored for SunOS compatibility.
-Bdynamic
-dy
-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 -l options which follow it.
-Bgroup
Set the DF_1_GROUP flag in the DT_FLAGS_1 entry in the dynamic section. This causes the
runtime linker to handle lookups in this object and its dependencies to be performed only inside
the group. -no-undefined is implied. This option is only meaningful on ELF platforms which
support shared libraries.
-Bstatic
-dn
-non_shared
-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 -l options which follow it.
-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.
-check-sections
-no-check-sections
Asks the linker not to check section addresses after they have been assigned to see if there
any overlaps. Normally the linker will perform this check, and if it finds any overlaps it will
produce suitable error messages. The linker does know about, and does make allowances for
sections in overlays. The default behaviour can be restored by using the command line switch
-check-sections.

14 Chapter 3. Invocation
-cref
Output a cross reference table. If a linker map file is being generated, the cross reference table is
printed to the map file. Otherwise, it is printed on the standard output.
The format of the table is intentionally simple, so that it may be easily processed by a script if
necessary. The symbols are printed out, sorted by name. For each symbol, a list of file names is
given. If the symbol is defined, the first file listed is the location of the definition. The remaining
files contain references to the symbol.
-no-define-common
This option inhibits the assignment of addresses to common symbols. The script command
INHIBIT_COMMON_ALLOCATION has the same effect. Refer to Section 4.4.4 Other Linker Script
Commands.
The -no-define-common option allows decoupling the decision to assign addresses to Com-
mon symbols from the choice of the output file type; otherwise a non-Relocatable output type
forces assigning addresses to Common symbols. Using -no-define-common allows Common
symbols that are referenced from a shared library to be assigned addresses only in the main pro-
gram. This eliminates the unused duplicate space in the shared library, and also prevents any
possible confusion over resolving to the wrong duplicate when there are many dynamic modules
with specialized search paths for runtime symbol resolution.
-defsym symbol=expression
Create a global symbol in the output file, containing the absolute address given by 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 expression in this context: you may
give a hexadecimal constant or the name of an existing symbol, or use +and -to add or subtract
hexadecimal constants or symbols. If you need more elaborate expressions, consider using the
linker command language from a script (refer to Section 4.5 Assigning Values to Symbols). Note:
there should be no white space between symbol, the equals sign ("[=]"), and expression.
-demangle[=style]
-no-demangle
These options control whether to demangle symbol names in error messages and other out-
put. When the linker is told to demangle, it tries to present symbol names in a readable fash-
ion: it strips leading underscores if they are used by the object file format, and converts C++
mangled symbol names into user readable names. Different compilers have different mangling
styles. The optional demangling style argument can be used to choose an appropriate demangling
style for your compiler. The linker will demangle by default unless the environment variable
COLLECT_NO_DEMANGLE is set. These options may be used to override the default.
-dynamic-linker 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.
-embedded-relocs
This option is only meaningful when linking MIPS embedded PIC code, generated by the -
membedded-pic option to the 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.

Chapter 3. Invocation 15
-fatal-warnings
Treat all warnings as errors.
-force-exe-suffix
Make sure that an output file has a .exe suffix.
If a successfully built fully linked output file does not have a .exe or .dll suffix, this option
forces the linker to copy the output file to one of the same name with a .exe suffix. This option is
useful when using unmodified Unix makefiles on a Microsoft Windows host, since some versions
of Windows won’t run an image unless it ends in a .exe suffix.
-no-gc-sections
-gc-sections
Enable garbage collection of unused input sections. It is ignored on targets that do not support
this option. This option is not compatible with -r, nor should it be used with dynamic linking.
The default behaviour (of not performing this garbage collection) can be restored by specifying
-no-gc-sections on the command line.
-help
Print a summary of the command-line options on the standard output and exit.
-target-help
Print a summary of all target specific options on the standard output and exit.
-Map mapfile
Print a link map to the file mapfile. See the description of the -M option, above.
-no-keep-memory
ld normally optimizes for speed over memory usage by caching the symbol tables of input files
in memory. This option tells ld to instead optimize for memory usage, by rereading the symbol
tables as necessary. This may be required if ld runs out of memory space while linking a large
executable.
-no-undefined
-z defs
Normally when creating a non-symbolic shared library, undefined symbols are allowed and left
to be resolved by the runtime loader. This option disallows such undefined symbols if they come
from regular object files. The switch -no-allow-shlib-undefined controls the behaviour
for shared objects being linked into the shared library.
-allow-multiple-definition
-z muldefs
Normally when a symbol is defined multiple times, the linker will report a fatal error. These
options allow multiple definitions and the first definition will be used.
-allow-shlib-undefined
-no-allow-shlib-undefined
Allow (the default) or disallow undefined symbols in shared objects. The setting of this switch
overrides -no-undefined where shared objects are concerned. Thus if -no-undefined is

16 Chapter 3. Invocation
set but -no-allow-shlib-undefined is not, the net result will be that undefined symbols in
regular object files will trigger an error, but undefined symbols in shared objects will be ignored.
The reason that -allow-shlib-undefined is the default is that the shared object being spec-
ified at link time may not be the same one that is available at load time, so the symbols might
actually be resolvable at load time. Plus there are some systems, (eg BeOS) where undefined
symbols in shared libraries is normal since the kernel patches them at load time to select which
function is most appropriate for the current architecture. eg. to dynamically select an appropri-
ate memset function. Apparently it is also normal for HPPA shared libraries to have undefined
symbols.
-no-undefined-version
Normally when a symbol has an undefined version, the linker will ignore it. This option disallows
symbols with undefined version and a fatal error will be issued instead.
-no-warn-mismatch
Normally ld will give an error if you try to link together input files that are mismatched for
some reason, perhaps because they have been compiled for different processors or for different
endiannesses. This option tells ld that it should silently permit such possible errors. This option
should only be used with care, in cases when you have taken some special action that ensures
that the linker errors are inappropriate.
-no-whole-archive
Turn off the effect of the -whole-archive option for subsequent archive files.
-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.
-nostdlib
Only search library directories explicitly specified on the command line. Library directories spec-
ified in linker scripts (including linker scripts specified on the command line) are ignored.
-oformat output-format
ld may be configured to support more than one kind of object file. If your ld is configured
this way, you can use the -oformat option to specify the binary format for the output object
file. Even when ld is configured to support alternative object formats, you don’t usually need
to specify this, as ld should be configured to produce as a default output format the most usual
format on each machine. output-format is a text string, the name of a particular format sup-
ported by the BFD libraries. (You can list the available binary formats with objdump -i.) The
script command OUTPUT_FORMAT can also specify the output format, but this option overrides
it. Refer to Chapter 6 BFD.
-pie
-pic-executable
Create a position independent executable. This is currently only supported on ELF platforms.
Position independent executables are similar to shared libraries in that they are relocated by the
dynamic linker to the virtual address OS chooses for them (which can varry between invocations),
like normal dynamically linked executables they can be executed and symbols defined in the
executable cannot be overridden by shared libraries.