Gnu ld

loader

-b input-format
--format=input-format
the binary format for input object files that follow this option on the command line.
usually unnecesasry. the name of a particular format supported by the BFD libraries. (list the formats with `objdump -i'.) See section BFD.
use this option for linking files with an unusual binary format. or 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 $GNUTARGET. Define the input format from a script, using the command TARGET; see section Option Commands.
-d
-dc
-dp
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 section Option Commands.
-e entry
--entry=entry explicit symbol for beginning execution. See section The Entry Point
-E
--export-dynamic
creating a dynamically linked executable, add all symbols to the dynamic symbol table, the set of symbols which are visible from dynamic objects at run time.
without this the dynamic symbol table will normally contain only those symbols which are referenced by some dynamic object mentioned in the link.
With dlopen to load a dynamic object which needs to refer back to the symbols defined by the program, rather than some other dynamic object, use this option when linking the program itself.
-f
--auxiliary name
When creating an ELF shared object, set the internal DT_AUXILIARY field.
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 link a program against this filter object, 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. it will be used instead of the definition in the filter object.
The shared object name need not exist and may be used to provide an alternative implementation of certain functions, for debugging or for machine specific performance.
May be specified more than once. The DT_AUXILIARY entries will be created in the order in which they appear on the command line.
-F name
--filter name
When creating an ELF shared object, set the internal DT_FILTER field to the specified name to inform 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 link a program against this filter object, the dynamic linker will see the DT_FILTER field and will resolve symbols according to the symbol table of the filter object as usual, but it will link to the definitions found in the shared object name.
The filter object can be used to select a subset of the symbols provided by the object name. The -b, --format, --oformat options, the TARGET command in linker scripts, and the GNUTARGET environment variable.
--force-exe-suffix Insure that output file has an .exe suffix. Useful when using unmodified Unix makefiles on a Microsoft Windows host
-hname
-soname=name When creating an ELF shared object, set the internal DT_SONAME field. 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').
-larchive
--library=archive
Add archive file archive to the list of files to link. may be used any number of times.
ld will search its path-list for occurrences of libarchive.a for every archive specified.
On systems which support shared libraries, ld also searchs for libraries with extensions other than .a. 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.
A .so extension indicates a shared library.
The linker will search an archive only once, 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. 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 section 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.
-n
--nmagic Set the text segment to be read only, 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 segment. If the output format supports Unix style magic numbers, mark the output as OMAGIC.
-o output
--output=output Use output as the name for the program produced by ld; if not specified, the name `a.out' is used by default. The script command OUTPUT can also specify the output file name.
-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 not specified, an absolute file is produced. When linking C++ programs, this option will not resolve references to constructors; to do that, use `-Ur'. This option does the same thing as `-i'.
-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 commandfile
--script=commandfile Read link commands from the file commandfile. These commands replace ld's default link script (rather than adding 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 which can only appear once in a linker script, such as the SECTIONS or MEMORY command. See section Command Language. If commandfile does not exist, 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 example, trigger linking of additional modules from standard libraries. `-u' may be repeated with different option arguments to enter additional undefined symbols.
-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. 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 ignored for Solaris compatibility.
-( 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. 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.
-assert keyword ignored for SunOS compatibility.
-Bdynamic
-dy
-call_shared Link against dynamic libraries. This is only meaningful on platforms for which shared libraries are supported. 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.
-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. only meaningful on ELF platforms which support shared libraries.
--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.
--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 section Assignment: Defining Symbols). 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 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.
-EB Link big-endian objects. This affects the default output format.
-EL Link little-endian objects. This affects the default output format.
--embedded-relocs 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.
--help Print a summary of the command-line 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-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.
--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 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 section BFD.
-qmagic ignored for Linux compatibility.
-Qy ignored for SVR4 compatibility.
--relax An option with machine dependent effects. only supported on a few targets. See section ld and the H8/300. See section ld and the Intel 960 family. On some platforms, the `--relax' option performs global optimizations that become possible when the linker resolves addressing in the program, such as relaxing address modes and synthesizing new instructions in the output object file. On platforms where this is not supported, `--relax' is accepted, but ignored.
--retain-symbols-file filename Retain only the symbols listed in the file filename, discarding all others. filename is simply a flat file, with one symbol name per line. especially useful in environments (such as VxWorks) where a large global symbol table is accumulated gradually, to conserve run-time memory. `--retain-symbols-file' does not discard undefined symbols, or symbols needed for relocations. You may only specify `--retain-symbols-file' once in the command line. It overrides `-s' and `-S'.
-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 which are needed by shared objects explicitly included in the link; see the description of the -rpath-link option. If -rpath is not used when linking an ELF executable, the contents of the environment variable LD_RUN_PATH will be used if it is defined. The -rpath option may also be used on SunOS. By default, on SunOS, the linker will form a runtime search patch out of all the -L options it is given. If a -rpath option is used, the runtime search path will be formed exclusively using the -rpath options, ignoring the -L options. This can be useful when using gcc, which adds many -L options which may be on NFS mounted filesystems. 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.
-rpath-link DIR When using ELF or SunOS, 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 non-shared, non-relocateable link, it will automatically try to locate the required shared library and include it in the link, if it is not 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 only effective at link time. On an ELF system, if the -rpath and rpath-link options were not used, search the contents of the environment variable LD_RUN_PATH. On SunOS, if the -rpath option was not used, search any directories specified using -L options. For a native linker, the contents of the environment variable LD_LIBRARY_PATH. The default directories, normally `/lib' and `/usr/lib'. If the required shared library is not found, the linker will issue a warning and continue with the link.
-shared
-Bshareable Create a shared library. This is currently only supported on ELF, XCOFF and SunOS platforms. On SunOS, the linker will automatically create a shared library if the -e option is not used and there are undefined symbols in the link.
--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 bytes, then all the four bytes, and then everything else. This is to prevent gaps between symbols due to alignment constraints.
--split-by-file Similar to --split-by-reloc but creates a new output section for each input file.
--split-by-reloc count Trys to creates extra sections in the output file so that no single output section in the file contains more than count relocations. This is useful when generating huge relocatable for downloading into certain real time kernels with the COFF object file format; since COFF cannot represent more than 65535 relocations in a single section. Note that this will fail to work with object file formats which do not support arbitrary sections. The linker will not split up individual input sections for redistribution, so if a single input section contains more than count relocations one output section will contain that many relocations.
--stats Compute and display statistics about the operation of the linker, such as execution time and memory usage.
--traditional-format For some targets, the output of ld is different in some ways from the output of some existing linker. This switch requests ld to use the traditional format instead. For example, on SunOS, ld combines duplicate entries in the symbol string table. This can reduce the size of an output file with full debugging information by over 30 percent. Unfortunately, the SunOS dbx program can not read the resulting program (gdb has no trouble). The `--traditional-format' switch tells ld to not combine duplicate entries.
-Tbss org
-Tdata org
-Ttext org Use org as the starting address for--respectively--the bss, data, or the text segment of the output file. org 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, 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.
--verbose Display the version number for ld and list the linker emulations supported. Display which input files can and cannot be opened. Display the linker script if using a default builtin script.
--version-script=version-scriptfile Specify the name of a version script to the linker. This is typically used when creating shared libraries to specify additional information about the version heirarchy for the library being created. only meaningful on ELF platforms which support shared libraries. See section Version 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 do not. This option allows you to 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 does not 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 is 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. One or both of the two symbols will be a common symbol. Turning a common symbol into a reference, because there is 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 the same as 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 only useful for a few object file formats. For formats like COFF or ELF, the linker can not detect the use of global constructors.
--warn-multiple-gp Warn if multiple global pointer values are required in the output file. This is only meaningful for certain processors, such as the Alpha. 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 is 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 case occurs.
--warn-once Only warn once for each undefined symbol, rather than once per module which refers to it.
--warn-section-align Warn if the address of an output section is changed because of alignment. Typically, the alignment will be set by an input section. The address will only be changed if it not explicitly specified; that is, if the SECTIONS command does not specify a start address for the section (see section Specifying Output Sections).
--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 searching the archive for the required object files. This is normally used to turn an archive file into a shared library, forcing every object to be included in the resulting shared library. This option may be used more than once.
--wrap symbol Use a wrapper function for symbol undefined reference to symbol will be resolved to __wrap_symbol.
undefined reference to __real_symbol will be resolved to symbol used 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 is 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, calls to malloc will call the function __wrap_malloc . The call to __real_malloc in __wrap_malloc will call the real malloc function. You may wish to provide a __real_malloc function as well, so that links without --wrap will succeed. If you do this, do not put the definition of __real_malloc in the same file as __wrap_malloc; , the assembler will resolve the call before the linker has a chance to wrap it to malloc.
-a keyword 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.
-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 section 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.
Distilled from Gnu.org Manuals