`ld`

Linker command (POSIX)

Syntax:

You should use qcc instead of calling ld directly.

ld [option...] objfile

Options:

-akeyword

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 particular format.

The default format is taken from the environment variable GNUTARGET. 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.

-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. 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 entry point.

-E

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 dlopen() 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.

-g

Ignored. Provided for compatibility with other tools.

-Gsize

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.

-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 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).

-i

Perform an incremental link (same as option -r).

-larchive

("el") Add archive file archive to the list of files to link. This option may be used any number of times. The ld utility searches its path list for occurrences of libarchive.a for every archive specified.

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 library.

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.

-Lsearchdir

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 "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 on the command line.

-memulation

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 configured.

-M

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.

-r

Generate relocatable output, i.e. generate an output file that can in turn serve as input to ld. This is often called partial linking.

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.

-s

Omit all symbol information from the output file.

-S

Omit debugger symbol information (but not all symbols) from the output file.

-t

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 standard libraries. The -u option may be repeated with different option arguments to enter additional undefined symbols.

-v -V

Display the version number for ld. The -V (uppercase) option also lists the supported emulations.

-x

Delete all local symbols.

-X

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 resolved.

Using this option has a significant performance cost. It's best to use it only when there are unavoidable circular references between two or more archives.

-assert keyword

This option is ignored for SunOS compatibility.

-Bdynamic -dy -call_shared

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.

-Bstatic -dn -non_shared -static

Don't link against shared libraries. 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.

-Bsymbolic

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.

-EB

Link big-endian objects. This affects the default output format.

-EL

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.

-qmagic

This option is ignored for Linux compatibility.

-Qy

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 order:

LD_LIBRARY_PATH
CS_LIBPATH.

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 libraries:

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 LD_RUN_PATH.
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.

-shared -Bshareable

Create a shared library.

-Tbss org -Tdata org -Ttext 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.

-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. 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.

GNU extensions

--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'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 documentation).

NOTE: there should be no white space between symbol, the equals sign (=), and expression.

--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 doing.

--help

Print a summary of the command-line options on standard output and exit.

--no-keep-memory

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.

--no-warn-mismatch

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 "endian-ness." 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 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'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 documentation.

--sort-common

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 alignment constraints.

--stats

Compute and display statistics about the operation of the linker, such as execution time and memory usage.

--verbose

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-common

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 file.
extern int i; -- an undefined reference, which doesn't allocate space. There must be either a definition or a common symbol for the variable somewhere.
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'
   overriding common
file(section): warning: common is here
```

Merging a common symbol with a previous same-sized common symbol:

file(section): warning: multiple common
   of `symbol'
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-constructors

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-multiple-gp

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-once

Warn only once for each undefined symbol, rather than once per module that refers to it.

--warn-section-align

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).

--whole-archive

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 library. 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 symbol.

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 __real_symbol.

Here's a trivial example:

void *
__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().

Description:

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 documentation.

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).

Environment variables:

GNUTARGET: 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.
LDEMULATION: 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 environment variable isn't defined, the default emulation depends on how the linker was configured.
LD_PRELOAD: A path to load shared libraries on an ELF system before other libraries are loaded. The libraries are listed using colon as delimiters.
LD_RUN_PATH: A path to search for shared libraries on an ELF system, used if the -rpath and rpath-link options weren't used.
LD_LIBRARY_PATH: A path to search for shared libraries for a native linker

Author:

GNU