NAME
ld - the GNU link editor
SYNOPSIS
ld [-A file] [-D size] [-L directory] [-M] [-N] [-S] [-T address] [-Tdata
address] [-Ttext address] [-X] [-d] [-e symbol] [-lc] [-n] [-o file]
[-q] [-r] [-s] [-t] [-u symbol] [-x] [-ysymbol] [-z] files ...
DESCRIPTION
The link editor reads relocatable object files and edits them into a sin-
gle image, resolving undefined symbols into addresses. By default, it
also resolves relocations and generates an absolute binary file suitable
for direct execution. The link editor is normally run automatically as
the last pass of a compiler such as cc(1). Compilers will often pass
link editor flags from their own command lines to the link editor.
There are many options:
-A file
Don't incorporate the text and data from file into the output
file, just use the symbols. This flag must appear before any in-
put files in the argument list. The -A flag can be used to im-
plement crude dynamic loading.
-D size
Pad the data segment to size. The padding may overlap with the
bss segment.
-L directory
Search the given directory for library archives in addition to
the default directories, /usr/lib and /usr/local/lib. Ld searches
directories supplied with the -L flag in order by appearance in
the argument list and before the default directories.
-M Print a crude load map on the standard output.
-N Create an OMAGIC format (a.out(5)) unshared executable binary.
This is the default format for relocatable object files, and is
the default output format for ld when the -r flag is used.
-S Strip special debugger symbols (stab(5)).
-T address
Relocate the start of the text segment to the hexadecimal value
address. The format of the binary output file (a.out(5)) normal-
ly determines the starting address of the text segment, but the
-T flag overrides the default.
-Tdata address
Relocate the start of the data segment.
-Ttext address
Identical to -T.
-X Strip local symbols which start with the letter L. Note that the
assembler (as(1)) omits these symbols by default, so this is
normally unnecessary.
-d Define `common' symbols even if the output file is relocatable;
see the discussion under the -r flag.
-e symbol
Set the entry address in the output file to symbol. If the output
file is executable, execution will begin at the named address.
Without -e, the executable file format determines the default en-
try address.
-lc Search directories for an archive named libc.a containing relo-
catable object files, and link in archive members which resolve
currently undefined symbols. Check under the -L flag for a de-
scription of directory searching. If the library archive has a
table of contents of its symbols (ranlib(1)), ld will select re-
locatable objects from the archive using this index; otherwise,
the object files are searched in order from the beginning of the
archive. More than one -l flag may be provided. The ordering of
-l arguments is significant; they are treated exactly like li-
brary archives provided as pathname arguments. Note that ld will
not link in an object file from the archive if the only outstand-
ing `undefined' symbol it satisfies is a common symbol. This
helps prevent text or data symbols in the library from linking
against similarly-named but unrelated common symbols in a user
program.
-n Create an NMAGIC format shared executable binary.
-o file
Write output to the named file instead of the default a.out.
-q Create a QMAGIC format demand loaded executable binary. This is
the default output format unless the -r flag is used.
-r Generate a relocatable output file, suitable for further link
editing. Ld does attempt to resolve undefined symbols, although
common symbols are not converted into bss symbols unless the -d
flag is used.
-s Strip all symbols from the output file. This overrides other
strip options.
-t Trace the operation of ld as it runs. The trace output is sent
to stderr.
-u symbol
Treat the given symbol as undefined. This feature is normally
used to force the extraction of certain files from a library.
-x Strip all local symbols.
-ysymbol
Trace the given symbol during linking. Trace output is sent to
stderr.
-z Create a ZMAGIC format demand loaded executable binary.
files ...
Link each relocatable object file or library archive in order.
Ld will edit each relocatable file into the output file, and will
select some or none of the relocatable files in each archive.
If some symbols are still unresolved at the end of linking and the output
file is not relocatable, ld will generate a link error. If there is more
than one definition for a symbol, ld will also generate a link error. If
line number symbols are present in the failing object file, ld will print
the line number as well as the source file in the error message. After a
link error, the resulting incomplete binary file will not have execute
permission.
Link editing is an essential but somewhat arcane practice. See a.out(5)
for more complete details about relocatable and executable binary files.
FILES
a.out default output file
*.o conventional suffix for object files
*.a conventional suffix for archive files
/usr/lib default search directory for libraries
/usr/local/lib secondary default search directory
EXAMPLES
$ ld -o cat /usr/lib/crt0.o cat.o -lc
DIAGNOSTICS
Definition of symbol %s (multiply defined)
More undefined \"%s\" refs follow
Undefined symbol \"%s\" referenced
More undefined symbol %s refs follow
Undefined symbol %s referenced from %s segment
%s: Symbol %s indirected to itself.
SEE ALSO
a.out(5), ar(1), as(1), cc(1), cpp(1), gdb(1), ranlib(1), stab(5),
strip(1)
AUTHORS
The GNU link editor is a product of the Free Software Foundation.
BUGS
Flags can't be bundled.
Because of the sequential nature of link editing, it is possible to get
link errors for an undefined symbol even though a relocatable object in a
given library archive would resolve it. This situation will occur if the
object in the archive isn't needed in order to resolve any undefined sym-
bols from earlier steps in linking, even though a later step requires it.
Ld makes a good faith effort to translate encoded symbols for C++ methods
into readable text in error messages, but this doesn't always succeed.
The version of ld distributed with this system is antique.
BSDI BSD/OS January 20, 1993 3
Jump to the MAN pages