X-Git-Url: https://repo.jachan.dev/binutils.git/blobdiff_plain/a82ae15d4b278243545bdc8290f044e69ea7c31c..4242ac27a53b03d4cdd4f1da1887ee92fd39befa:/ld/ld.1

diff --git a/ld/ld.1 b/ld/ld.1
index 102c8a2ec4..1037e2a0bb 100644
--- a/ld/ld.1
+++ b/ld/ld.1
@@ -1,4 +1,4 @@
-.\" 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
@@ -28,6 +28,8 @@ ld \- the GNU linker
 .I input-format\c
 \&\|] 
 .RB "[\|" \-Bstatic "\|]"  
+.RB "[\|" \-Bdynamic "\|]"  
+.RB "[\|" \-Bsymbolic "\|]"  
 .RB "[\|" "\-c\ "\c
 .I commandfile\c
 \&\|] 
@@ -42,6 +44,9 @@ ld \- the GNU linker
 .RB "[\|" "\-e\ "\c
 .I entry\c
 \&\|] 
+.RB "[\|" \-embedded\-relocs "\|]"
+.RB "[\|" \-E "\|]" 
+.RB "[\|" \-export\-dynamic "\|]"
 .RB "[\|" \-F "\|]" 
 .RB "[\|" "\-F\ "\c
 .I format\c
@@ -50,7 +55,7 @@ ld \- the GNU linker
 .I input-format\c
 \&\|] 
 .RB "[\|" \-g "\|]" 
-.RB "[\|" \-G\c
+.RB "[\|" \-G
 .I size\c
 \&\|]
 .RB "[\|" \-\-help "\|]"
@@ -62,14 +67,15 @@ ld \- the GNU linker
 .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
 \&\|] 
@@ -78,9 +84,20 @@ ld \- the GNU linker
 \&\|]
 .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
+.I count\c
+\&\|]
+.RB "[\|" \-split\-by\-file "\|]" 
 .RB "[\|" "\-T\ "\c
 .I commandfile\c
 \&\|]  
@@ -102,7 +119,14 @@ ld \- the GNU linker
 .RB "[\|" \-\-verbose "\|]"
 .RB "[\|" \-\-version "\|]"
 .RB "[\|" \-warn\-common "\|]" 
+.RB "[\|" \-warn\-constructors "\|]" 
+.RB "[\|" \-warn\-multiple\-gp "\|]" 
 .RB "[\|" \-warn\-once "\|]" 
+.RB "[\|" \-\-whole\-archive "\|]" 
+.RB "[\|" \-\-no\-whole\-archive "\|]" 
+.RB "[\|" "\-\-wrap\ "\c
+.I symbol\c
+\&\|]
 .RB "[\|" \-X "\|]" 
 .RB "[\|" \-x "\|]" 
 .ad b
@@ -246,8 +270,7 @@ whitespace, or be given as separate arguments immediately following the
 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
@@ -303,13 +326,11 @@ You can meaningfully use \c
 \& 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
@@ -347,14 +368,25 @@ format from a script, using the command \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
-.BI "\-c " "commandfile"\c
-\&
+.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"
 Directs \c
 .B ld\c
 \& to read link commands from the file
@@ -384,8 +416,7 @@ line by bracketing it between `\|\c
 .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
@@ -395,10 +426,7 @@ specified (\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
@@ -426,11 +454,29 @@ program, rather than the default entry point.  for a
 discussion of defaults and other ways of specifying the
 entry point.
 
+.TP
+.B \-embedded\-relocs
+This option is only meaningful when linking MIPS embedded PIC code,
+generated by the
+.B \-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.
+
+.TP
+.B \-E
+.TP
+.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
 .B \-F
 .TP
-.BI "-F" "format"\c
-\&
+.BI "-F" "format"
 Some older linkers used this option throughout a compilation toolchain
 for specifying object-file format for both input and output object
 files.  \c
@@ -452,8 +498,7 @@ but it accepts (and ignores) the \c
 with scripts written to call the old linker.
 
 .TP
-.BI "\-format " "input\-format"\c
-\&
+.BI "\-format " "input\-format"
 Synonym for \c
 .B \-b\c
 \& \c
@@ -500,13 +545,11 @@ path-list for occurrences of \c
 .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
@@ -523,8 +566,7 @@ The default set of paths searched (without being specified with
 \& 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
@@ -551,7 +593,9 @@ Emulate the
 .I emulation
 linker.  You can list the available emulations with the
 .I \-\-verbose
-option.  This option overrides the compiled-in default, which is the
+or
+.I \-V
+options.  This option overrides the compiled-in default, which is the
 system for which you configured
 .BR ld .
 
@@ -586,11 +630,15 @@ errors during the link process.  With this flag, you can specify that
 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
@@ -603,8 +651,7 @@ script command \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
@@ -619,10 +666,7 @@ The script command
 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
@@ -669,6 +713,62 @@ This option does the same as \c
 .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.
@@ -677,6 +777,15 @@ 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
@@ -687,6 +796,28 @@ the two bytes, then all the four bytes, and then everything else.
 This is to prevent gaps between symbols due to
 alignment constraints.  This option disables that sorting.
 
+.TP
+.B \-split\-by\-reloc\ \fIcount
+Trys to creates extra sections in the output file so that no single
+output section in the file contains more than
+.I 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
+.I count
+relocations one output section will contain that many relocations.
+
+.TP
+.B \-split\-by\-file
+Similar to
+.B \-split\-by\-reloc
+but creates a new output section for each input file.
+
 .TP
 .BI "\-Tbss " "org"\c
 .TP
@@ -708,10 +839,7 @@ Use \c
 \& 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
@@ -745,9 +873,7 @@ For anything other than C++ programs, this option is equivalent to
 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
@@ -765,6 +891,9 @@ Display which input files can and can not be opened.
 Display the version number for \c
 .B ld\c
 \&.
+The
+.B \-V
+option also lists the supported emulations.
 
 .TP
 .B \-\-version
@@ -779,32 +908,60 @@ 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.
 
+.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 \-\-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
+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 
-If \c
-.B \-s\c
-\& or \c
-.B \-S\c
-\& is also specified, delete only local symbols
-beginning with `\|\c
+Delete all temporary local symbols.  For most targets, this is all local
+symbols whose names begin with `\|\c
 .B L\c
 \|'.
 
 .TP
 .B \-x
-If \c
-.B \-s\c
-\& or \c
-.B \-S\c
-\& is also specified, delete all local symbols,
-not just those beginning with `\|\c
-.B L\c
-\|'.
+Delete all local symbols.
 
 .PP