Linker command (POSIX)
You should use qcc instead of
calling ld directly.|
ld_variant [option...] objfile
The ld_variant depends on the target platform, as follows:
- This option is supported for HP/UX compatibility. The keyword
argument must be one of the strings:
- archive (equivalent to -Bstatic)
- shared (equivalent to -Bdynamic)
- default (equivalent to -Bdynamic).
This option may be used any number of times.
- -b input-format
- The QNX version of ld is configured to support more than
one kind of object file. You can use the
-b option to specify the binary format for input object files
that follow this option on the command line.
The 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.)
See "BFD" in the full online GNU documentation.
You may want to use this option if you're 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
The default format is taken from the environment variable
See "Environment variables."
You can also define the input
format from a script, using the command TARGET; see
"Option Commands" in the full online GNU documentation.
- 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. See
"Option Commands" in the full online GNU documentation.
- -e entry
- Use entry as the explicit symbol for beginning execution of your
program, rather than the default entry point. See
"The Entry Point" in the full online GNU documentation for a
discussion of defaults and other ways of specifying the
- When creating a dynamically linked executable, add all symbols to the
dynamic symbol table. The dynamic symbol table is the set of symbols
that are visible from dynamic objects at runtime.
If you don't use this option, the dynamic symbol table normally
contains only those symbols that are referenced by some dynamic object
mentioned in the link --
symbols that you define as extern in your code aren't global
symbols as far as dl_open() and dlsym() are concerned.
If you use
to load a dynamic object that needs to refer
back to the symbols defined by the program, rather than some other
dynamic object, then you probably need to use this option when
linking the program itself.
- Ignored. Provided for compatibility with other tools.
- Set the maximum size of objects to be optimized using the GP register.
This is meaningful only for object file formats such as
MIPS that support putting large and small objects into different
sections. This is ignored for other object file formats.
- 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
that has a DT_SONAME field, then when the executable is run, the dynamic
linker attempts to load the shared object specified by the DT_SONAME
field (rather than use the file name given to the linker).
- Perform an incremental link (same as option -r).
Add archive file archive to the list of files to link. This
option may be used any number of times. The ld utility
path list for occurrences of libarchive.a for every
The ld utility searches for
libraries with extensions other than .a. Specifically,
ld searches 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
The linker searches an archive only once at the location where it's
specified on the command line. If the archive defines a symbol that
was undefined in some object that appeared before the archive on the
command line, the linker includes the appropriate file(s) from the
archive. However, an undefined symbol in an object appearing later on
the command line doesn't 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.
- Add searchdir to the list of paths that ld searches
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're 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.
The default set of paths searched (without being specified with
-L) depends on which emulation mode ld is using, and in
some cases also on how it was configured. See
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 on the command line.
- Emulate the emulation linker. You can list the available
emulations with the -V option.
If the -m option isn't used, the emulation is taken from the
LDEMULATION environment variable, if defined.
Otherwise, the default emulation depends on how the linker was
- 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
that caused the archive member to be brought in.
- -o output
- Use output as the name for the program produced by ld; if this
option isn't specified, the name a.out is used by default. The
script command OUTPUT can also specify the output file name.
- Generate relocatable output, i.e. generate an output file that can in
turn serve as input to ld. This is often called partial
If this option isn't specified, an absolute file is produced. When
linking C++ programs, this option doesn't resolve references to
constructors; to do that, use -Ur.
This option does the same thing as -i.
- -R filename
- Read symbol names and their addresses from filename, but don't
relocate it or include it in the output. This lets your output file
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 filename, it's treated as
the -rpath option.
- Omit all symbol information from the output file.
- Omit debugger symbol information (but not all symbols) from the output file.
- Print the names of the input files as ld processes them.
- -T commandfile
- Read link commands from the file commandfile. These commands
replace ld's default link script (rather than add to it), so
commandfile must specify everything necessary to describe the
target format. You must use this option if you want to use a command
that can appear only once in a linker script, such as the
SECTIONS or MEMORY command. See
"Command Language" in the full online GNU documentation. If
commandfile doesn't exist, ld looks for it in the
directories specified by any preceding -L options. Multiple
-T options accumulate.
- -u symbol
- Force symbol to be entered in the output file as an undefined symbol.
Doing this may, for example, trigger the linking of additional modules from
The -u option may be repeated with different option
arguments to enter additional undefined symbols.
- Display the version number for ld. The -V
(uppercase) option also
lists the supported emulations.
- Delete all local symbols.
- Delete all temporary local symbols. For most targets, this is all local
symbols whose names begin with L.
- -y symbol
- Print the name of each linked file in which symbol appears. This
option may be given any number of times.
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
- This option is ignored for Solaris compatibility.
- -( archives -)
- 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's 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
can't resolve that reference. By grouping the archives,
they're searched repeatedly until all possible references are
Using this option has a significant performance cost. It's best to use
it only when there are unavoidable circular references between two or
- -assert keyword
- This option is ignored for SunOS compatibility.
- Link against dynamic libraries.
This option is the default.
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 that follow it.
- Don't link against shared libraries.
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 that follow it.
- When creating a shared library, bind references to global symbols to the
definition within the shared library, if any. Normally, it's possible
for a program linked against a shared library to override the definition
within the shared library.
- Link big-endian objects. This affects the default output format.
- Link little-endian objects. This affects the default output format.
- -Map mapfile
- Print a link map to the file mapfile. See the description of the
-M option, above.
- This option is ignored for Linux compatibility.
- This option is ignored for SVR4 compatibility.
- -rpath dir
- Add a directory to the runtime library search path. This is used when
linking an ELF executable with shared objects. All -rpath
arguments are concatenated and passed to the runtime linker, which uses
them to locate shared objects at runtime. The -rpath option is
also used when locating shared objects that are needed by shared
objects explicitly included in the link; see the description of the
-rpath-link option. If -rpath isn't used when linking an
ELF executable, the contents of the following directories are searched in
||_CS_LIBPATH is populated by the kernel, and the default value
is based on the LD_LIBRARY_PATH value on the procnto command
line in the boot image.|
For compatibility with other ELF linkers, if the -R option is
followed by a directory name, rather than a file name, it's treated as
the -rpath option.
- -rpath-link dir[:dir...]
- When using ELF (which QNX Neutrino does),
one shared library may require another. This
happens when an ld -shared link includes a shared library as one
of the input files.
When the linker encounters such a dependency when doing a nonshared,
nonrelocatable link, it automatically tries to locate the required
shared library and includes it in the link, if it isn't included
explicitly. In such a case, the -rpath-link option
specifies the first set of directories to search. The
-rpath-link option may specify a sequence of directory names
either by specifying a list of names separated by colons or by
appearing multiple times.
The linker uses the following search paths to locate required shared
- Any directories specified by -rpath-link options.
- Any directories specified by -rpath options. The difference
between -rpath and -rpath-link is that directories
specified by -rpath options are included in the executable and
used at runtime, whereas the -rpath-link option is effective only
at link time.
- On an ELF system (including QNX Neutrino),
if the -rpath and rpath-link options
weren't used, search the contents of the environment variable
- For a native linker, the contents of the
LD_LIBRARY_PATH environment variable.
- The default directories, normally /lib and /usr/lib.
If the required shared library isn't found, the linker issues a
warning and continues with the link.
- Create a shared library.
- -Tbss org
- Use org as the starting address for the
bss, data, or the text segment of the output file.
The org argument must be a single hexadecimal integer;
for compatibility with other linkers, you may omit the leading
0x usually associated with hexadecimal values.
- 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.
Using -Ur on files that were themselves linked
with -Ur doesn't work;
once the constructor table has been built, it can't
be added to. Use -Ur only for the last partial link, and
-r for the others.
- 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's printed on 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 filenames 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.
- --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 (see
"Assignment: Defining Symbols" in the full online GNU
NOTE: there should be no
white space between symbol, the equals sign (=), and
- --dynamic-linker file
- Set the name of the dynamic linker. This is meaningful only when
generating dynamically linked ELF executables. The default dynamic
linker is normally correct; don't use this unless you know what you're
- Print a summary of the command-line options on standard output and exit.
- The ld utility
normally optimizes for speed over memory usage by caching the
symbol tables of input files in memory. This option tells ld
instead to 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.
- Normally ld gives an error if you try to link together input
files that are mismatched for some reason, perhaps because they've
been compiled for different processors or for different
This option tells ld to silently permit such possible
errors. Use this option with care, and only in cases when you've
taken some special action that ensures that the linker errors are
- Turn off the effect of the --whole-archive option for subsequent
- Retain the executable output file whenever it's still usable.
Normally, the linker doesn't 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.
- --oformat output-format
- The ld utility
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, because ld
should be configured to produce as a default output format the most
usual format on each machine.
The output-format argument 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.) The script
command OUTPUT_FORMAT can also specify the output format, but
this option overrides it. See "BFD" in the full online GNU
- This option tells 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-byte, then all the four-byte, and then
everything else. This is to prevent gaps between symbols due to
- Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
- Display the version number for ld and list the linker emulations
supported. Display which input files can and can't be opened. Display
the linker script if using a default builtin script.
- Warn when a common symbol is combined with another common symbol or with
a symbol definition. Unix linkers allow this somewhat sloppy practice,
but linkers on some other operating systems don't. This option lets
you find potential problems from combining global symbols.
Unfortunately, some C libraries use this practice, so you may get some
warnings about symbols in the libraries as well as in your programs.
There are three kinds of global symbols, illustrated here by C examples:
- int i = 1; --
a definition, which goes in the initialized data section of the output
- extern int i; --
an undefined reference, which doesn't allocate space.
There must be either a definition or a common symbol for the
- int i; --
a common symbol. If there are only (one or more) common symbols for a
variable, it goes in the uninitialized data area of the output file.
The linker merges multiple common symbols for the same variable into a
single symbol. If they are of different sizes, it picks the largest
size. The linker turns a common symbol into a declaration if there's
a definition of the same variable.
The --warn-common option can produce five kinds of warnings.
Each warning consists of a pair of lines: the first describes the symbol
just encountered, and the second describes the previous symbol
encountered with the same name. At least one of the two symbols is
a common symbol.
- Turning a common symbol into a reference, because there's already a
definition for the symbol:
file(section): warning: common of `symbol'
overridden by definition
file(section): warning: defined here
- Turning a common symbol into a reference, because a later definition for
the symbol is encountered. This is the same as the previous case,
except that the symbols are encountered in a different order:
file(section): warning: definition of `symbol'
file(section): warning: common is here
- Merging a common symbol with a previous same-sized common symbol:
file(section): warning: multiple common
file(section): warning: previous common is here
- Merging a common symbol with a previous larger common symbol:
file(section): warning: common of `symbol'
overridden by larger common
file(section): warning: larger common is here
- Merging a common symbol with a previous smaller common symbol. This is
similar to the previous case, except that the symbols are
encountered in a different order:
file(section): warning: common of `symbol'
overriding smaller common
file(section): warning: smaller common is here
- Warn if any global constructors are used. This is useful only for a few
object file formats. For formats like COFF or ELF (which QNX Neutrino uses),
the linker can't
detect the use of global constructors.
- Warn if multiple global pointer values are required in the output file.
This is meaningful only for certain processors, such as the MIPS/PPC.
Specifically, some processors put large-valued constants in a special
section. A special register (the global pointer) points into the middle
of this section, so that constants can be loaded efficiently via a
base-register relative addressing mode. Since the offset in
base-register relative mode is fixed and relatively small (e.g. 16
bits), this limits the maximum size of the constant pool. Thus, in
large programs, it's often necessary to use multiple global pointer
values in order to be able to address all possible constants. This
option causes a warning to be issued whenever this occurs.
- Warn only once for each undefined symbol, rather than once per module
that refers to it.
- Warn if the address of an output section is changed because of
alignment. Typically, the alignment is set by an input section.
The address is changed only if it isn't explicitly specified; that
is, if the SECTIONS command doesn't specify a start address for
the section (see "Specifying Output Sections" in the full
online GNU documentation).
- For each archive mentioned on the command line after the
--whole-archive option, include every object file in the archive
in the link, rather than search 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
You can use this option more than once and can turn it off
with the --no-whole-archiveoption.
- --wrap symbol
- Use a wrapper function for symbol. Any undefined reference to
symbol is resolved to __wrap_symbol. Any
undefined reference to __real_symbol is resolved to
You can use this to provide a wrapper for a system function. The
wrapper function should be called __wrap_symbol. If it
wishes to call the system function, it should call
Here's a trivial example:
__wrap_malloc (int c)
printf ("malloc called with %ld\n", c);
return __real_malloc (c);
If you link other code with this file using --wrap malloc, then
all calls to malloc() call the function __wrap_malloc()
instead. The call to __real_malloc() in __wrap_malloc()
calls the real malloc() function.
You may wish to provide a __real_malloc() function as well, so that
links without the --wrap option succeed. If you do this,
you shouldn't put the definition of __real_malloc() in the same
file as __wrap_malloc(); if you do, the assembler may resolve the
call before the linker has a chance to wrap it to malloc().
The ld linker 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.
The ld utility 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 lets ld 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.
For more information, see "BFD" in the full online GNU
Aside from its flexibility, the GNU linker is more helpful than other
linkers in providing diagnostic information. Many linkers abandon
execution immediately on 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).
Determines the input-file object format if you don't
use -b. Its value should be one
of the BFD names for an input format (see
"BFD" in the full online GNU
documentation). If there's no
GNUTARGET in the environment, ld
uses the natural format
of the target. If GNUTARGET is set to
default, then BFD
attempts to discover the input format by examining binary input files;
this method often succeeds, but there are potential ambiguities, since
there's no method of ensuring that the magic number used to specify
object-file formats is unique. However, the configuration procedure for
BFD on each system places the conventional format for that system first
in the search-list, so ambiguities are resolved in favor of convention.
Determines the default emulation if you don't use the
-m option. The emulation can affect various aspects of linker
behavior, particularly the default linker script. You can list the
available emulations with the -V option. If
the -m option isn't used, and the LDEMULATION
variable isn't defined, the default emulation depends on how the
linker was configured.
- A path to load shared libraries on an ELF system before other libraries
are loaded. The libraries are listed using colon as delimiters.
- A path to search for shared libraries on an ELF system, used if the
-rpath and rpath-link options weren't used.
- A path to search for shared libraries for a native linker.
in the Library Reference