-.\" Copyright (c) 1991, 1992 Free Software Foundation
+.\" Copyright (c) 1991, 92, 93, 94, 95, 1996 Free Software Foundation
.\" See section COPYING for conditions for redistribution
.TH ld 1 "17 August 1992" "cygnus support" "GNU Development Tools"
.de BP
.I input-format\c
\&\|]
.RB "[\|" \-Bstatic "\|]"
+.RB "[\|" \-Bdynamic "\|]"
+.RB "[\|" \-Bsymbolic "\|]"
.RB "[\|" "\-c\ "\c
.I commandfile\c
\&\|]
+.RB "[\|" \-\-cref "\|]"
.RB "[\|" \-d | \-dc | \-dp\c
\|]
.br
.I entry\c
\&\|]
.RB "[\|" \-embedded\-relocs "\|]"
-.RB "[\|" \-F "\|]"
+.RB "[\|" \-E "\|]"
+.RB "[\|" \-export\-dynamic "\|]"
+.RB "[\|" "\-f\ "\c
+.I name\c
+\&\|]
+.RB "[\|" "\-\-auxiliary\ "\c
+.I name\c
+\&\|]
.RB "[\|" "\-F\ "\c
-.I format\c
+.I name\c
+\&\|]
+.RB "[\|" "\-\-filter\ "\c
+.I name\c
\&\|]
.RB "[\|" "\-format\ "\c
.I input-format\c
\&\|]
.RB "[\|" \-g "\|]"
-.RB "[\|" \-G\c
+.RB "[\|" \-G
.I size\c
\&\|]
+.RB "[\|" "\-h\ "\c
+.I name\c
+\&\|]
+.RB "[\|" "\-soname\ "\c
+.I name\c
+\&\|]
.RB "[\|" \-\-help "\|]"
.RB "[\|" \-i "\|]"
.RB "[\|" \-l\c
.I searchdir\c
\&\|]
.RB "[\|" \-M "\|]"
-.RB "[\|" \-Map\c
+.RB "[\|" \-Map
.I mapfile\c
\&\|]
-.RB "[\|" \-m\c
+.RB "[\|" \-m
.I emulation\c
\&\|]
.RB "[\|" \-n | \-N "\|]"
.RB "[\|" \-noinhibit-exec "\|]"
+.RB "[\|" \-no\-keep\-memory "\|]"
.RB "[\|" "\-oformat\ "\c
.I output-format\c
\&\|]
\&\|]
.RB "[\|" \-relax "\|]"
.RB "[\|" \-r | \-Ur "\|]"
+.RB "[\|" "\-rpath\ "\c
+.I directory\c
+\&\|]
+.RB "[\|" "\-rpath\-link\ "\c
+.I directory\c
+\&\|]
.RB "[\|" \-S "\|]"
.RB "[\|" \-s "\|]"
+.RB "[\|" \-shared "\|]"
.RB "[\|" \-sort\-common "\|]"
-.RB "[\|" \-split\-by\-reloc\ "\c
+.RB "[\|" "\-split\-by\-reloc\ "\c
.I count\c
\&\|]
.RB "[\|" \-split\-by\-file "\|]"
.RB "[\|" \-\-verbose "\|]"
.RB "[\|" \-\-version "\|]"
.RB "[\|" \-warn\-common "\|]"
+.RB "[\|" \-warn\-constructors "\|]"
+.RB "[\|" \-warn\-multiple\-gp "\|]"
.RB "[\|" \-warn\-once "\|]"
+.RB "[\|" \-warn\-section\-align "\|]"
.RB "[\|" \-\-whole\-archive "\|]"
+.RB "[\|" \-\-no\-whole\-archive "\|]"
+.RB "[\|" "\-\-wrap\ "\c
+.I symbol\c
+\&\|]
.RB "[\|" \-X "\|]"
.RB "[\|" \-x "\|]"
.ad b
option that requires them.
.TP
-.BI "-A" "architecture"\c
-\&
+.BI "-A" "architecture"
In the current release of \c
.B ld\c
\&, this option is useful only for the
\& more than once on a command line, if
an architecture family allows combination of target architectures; each
use will add another pair of name variants to search for when \c
-.B \-l\c
-\&
+.B \-l
specifies a library.
.TP
-.BI "\-b " "input-format"\c
-\&
+.BI "\-b " "input-format"
Specify the binary format for input object files that follow this option
on the command line. You don't usually need to specify this, as
\c
.TP
.B \-Bstatic
-This flag is accepted for command-line compatibility with the SunOS linker,
-but has no effect on \c
-.B ld\c
-\&.
+Do not link against shared libraries. This is only meaningful on
+platforms for which shared libraries are supported.
+
+.TP
+.B \-Bdynamic
+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.
+
+.TP
+.B \-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.
.TP
-.BI "\-c " "commandfile"\c
-\&
+.BI "\-c " "commandfile"
Directs \c
.B ld\c
\& to read link commands from the file
.B }\c
\|' characters.
+.TP
+.B \-\-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.
+
.TP
.B \-d
.TP
.B \-dp
These three options are equivalent; multiple forms are supported for
compatibility with other linkers. Use any of them to make \c
-.B ld\c
-\&
+.B ld
assign space to common symbols even if a relocatable output file is
specified (\c
.B \-r\c
\& has the same effect.
.TP
-.BI "-defsym " "symbol"\c
-\& = \c
-.I expression\c
-\&
+.BI "-defsym " "symbol" "\fR = \fP" expression
Create a global symbol in the output file, containing the absolute
address given by \c
.I expression\c
testsuite/ld-empic for details.
.TP
-.B \-F
+.B \-E
.TP
-.BI "-F" "format"\c
-\&
-Some older linkers used this option throughout a compilation toolchain
-for specifying object-file format for both input and output object
-files. \c
-.B ld\c
-\&'s mechanisms (the \c
-.B \-b\c
-\& or \c
-.B \-format\c
-\& options
-for input files, the \c
-.B TARGET\c
-\& command in linker scripts for output
-files, the \c
-.B GNUTARGET\c
-\& environment variable) are more flexible, but
-but it accepts (and ignores) the \c
-.B \-F\c
-\& option flag for compatibility
-with scripts written to call the old linker.
+.B \-export\-dynamic
+When creating an ELF file, add all symbols to the dynamic symbol table.
+Normally, the dynamic symbol table contains only symbols which are used
+by a dynamic object. This option is needed for some uses of
+.I dlopen.
+
+.TP
+.BI "-f " "name"
+.TP
+.BI "--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
+.I name.
+
+.TP
+.BI "-F " "name"
+.TP
+.BI "--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 should be used as a filter on the symbol table of
+the shared object
+.I name.
.TP
-.BI "\-format " "input\-format"\c
-\&
+.BI "\-format " "input\-format"
Synonym for \c
.B \-b\c
\& \c
.I size
under MIPS ECOFF. Ignored for other object file formats.
+.TP
+.BI "-h " "name"
+.TP
+.BI "-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.
+
.TP
.B \-\-help
Print a summary of the command-line options on the standard output and exit.
.I ar\c
\&.a\c
\& for every \c
-.I ar\c
-\&
+.I ar
specified.
.TP
-.BI "\-L" "searchdir"\c
-\&
+.BI "\-L" "searchdir"
This command adds path \c
.I searchdir\c
\& to the list of paths that
\& is using, and in
some cases also on how it was configured. The
paths can also be specified in a link script with the \c
-.B SEARCH_DIR\c
-\&
+.B SEARCH_DIR
command.
.TP
you wish the output file retained even after non-fatal errors.
.TP
-.BI "\-o " "output"\c
-\&
-.I output\c
-\&
-\c
+.B \-no\-keep\-memory
+The linker normally optimizes for speed over memory usage by caching
+the symbol tables of input files in memory. This option tells the
+linker to instead optimize for memory usage, by rereading the symbol
+tables as necessary. This may be required if the linker runs out of
+memory space while linking a large executable.
+
+.TP
+.BI "\-o " "output"
.I output\c
\& is a name for the program produced by \c
.B ld\c
\& can also specify the output file name.
.TP
-.BI "\-oformat " "output\-format"\c
-\&
+.BI "\-oformat " "output\-format"
Specify the binary format for the output object file.
You don't usually need to specify this, as
\c
can also specify the output format, but this option overrides it.
.TP
-.BI "\-R " "filename"\c
-\&
-.I file\c
-\&
+.BI "\-R " "filename"
Read symbol names and their addresses from \c
.I filename\c
\&, but do not
.B \-i\c
\&.
+.TP
+.B \-rpath\ \fIdirectory
+Add a directory to the runtime library search path. This is used when
+linking an ELF executable with shared objects. All
+.B \-rpath
+arguments are concatenated and passed to the runtime linker, which uses
+them to locate shared objects at runtime. The
+.B \-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
+.B \-rpath\-link
+option. If
+.B \-rpath
+is not used when linking an ELF executable, the contents of the
+environment variable
+.B LD_RUN_PATH
+will be used if it is defined.
+
+The
+.B \-rpath
+option may also be used on SunOS. By default, on SunOS, the linker
+will form a runtime search patch out of all the
+.B \-L
+options it is given. If a
+.B \-rpath
+option is used, the runtime search path will be formed exclusively
+using the
+.B \-rpath
+options, ignoring
+the
+.B \-L
+options. This can be useful when using gcc, which adds many
+.B \-L
+options which may be on NFS mounted filesystems.
+
+.TP
+.B \-rpath\-link\ \fIdirectory
+When using ELF or SunOS, one shared library may require another. This
+happens when an
+.B 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
+.B \-rpath\-link
+option specifies the first set of directories to search. The
+.B \-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.
+
+If the required shared library is not found, the linker will issue a
+warning and continue with the link.
+
.TP
.B \-S
Omits debugger symbol information (but not all symbols) from the output file.
.B \-s
Omits all symbol information from the output file.
+.TP
+.B \-shared
+Create a shared library. This is currently only supported on ELF and
+SunOS platforms (on SunOS it is not required, as the linker will
+automatically create a shared library when there are undefined symbols
+and the
+.B \-e
+option is not used).
+
.TP
.B \-sort\-common
Normally, when
\& must be a hexadecimal integer.
.TP
-.BI "\-T " "commandfile"\c
-\&
-.TP
-.BI "\-T" "commandfile"\c
+.BI "\-T " "commandfile"
Equivalent to \c
.B \-c \c
.I commandfile\c
turn serve as input to \c
.B ld\c
\&. When linking C++ programs, \c
-.B \-Ur\c
-\&
-\c
+.B \-Ur
.I will\c
\& resolve references to constructors, unlike \c
.B \-r\c
but linkers on some other operating systems do not. This option allows
you to find potential problems from combining global symbols.
+.TP
+.B \-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.
+
+.TP
+.B \-warn\-multiple\-gp
+Warn if the output file requires multiple global-pointer values. This
+option is only meaningful for certain processors, such as the Alpha.
+
.TP
.B \-warn\-once
Only warn once for each undefined symbol, rather than once per module
which refers to it.
.TP
+.B \-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.
+
+.TP
+.B \-\-whole\-archive
+For each archive mentioned on the command line after the
+.B \-\-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.
+
+.TP
+.B \-\-no\-whole\-archive
+Turn off the effect of the
.B \-\-whole\-archive
-For each archive mentioned on the command line, 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.
+option for archives which appear later on the command line.
+
+.TP
+.BI "--wrap " "symbol"
+Use a wrapper function for
+.I symbol.
+Any undefined reference to
+.I symbol
+will be resolved to
+.BI "__wrap_" "symbol".
+Any undefined reference to
+.BI "__real_" "symbol"
+will be resolved to
+.I symbol.
.TP
.B \-X
projects / deliverable / binutils-gdb.git / blobdiff