1 .\" Copyright (c) 1991, 92, 93, 94, 95, 1996 Free Software Foundation
2 .\" See section COPYING for conditions for redistribution
3 .TH ld 1 "17 August 1992" "cygnus support" "GNU Development Tools"
30 .RB "[\|" \-Bstatic "\|]"
31 .RB "[\|" \-Bdynamic "\|]"
32 .RB "[\|" \-Bsymbolic "\|]"
36 .RB "[\|" \-d | \-dc | \-dp\c
39 .RB "[\|" "\-defsym\ "\c
47 .RB "[\|" \-embedded\-relocs "\|]"
49 .RB "[\|" \-export\-dynamic "\|]"
54 .RB "[\|" "\-format\ "\c
61 .RB "[\|" \-\-help "\|]"
76 .RB "[\|" \-n | \-N "\|]"
77 .RB "[\|" \-noinhibit-exec "\|]"
78 .RB "[\|" \-no\-keep\-memory "\|]"
79 .RB "[\|" "\-oformat\ "\c
85 .RB "[\|" \-relax "\|]"
86 .RB "[\|" \-r | \-Ur "\|]"
87 .RB "[\|" "\-rpath\ "\c
90 .RB "[\|" "\-rpath\-link\ "\c
95 .RB "[\|" \-shared "\|]"
96 .RB "[\|" \-sort\-common "\|]"
97 .RB "[\|" "\-split\-by\-reloc\ "\c
100 .RB "[\|" \-split\-by\-file "\|]"
104 .RB "[\|" "\-Ttext\ "\c
107 .RB "[\|" "\-Tdata\ "\c
110 .RB "[\|" "\-Tbss\ "\c
119 .RB "[\|" \-\-verbose "\|]"
120 .RB "[\|" \-\-version "\|]"
121 .RB "[\|" \-warn\-common "\|]"
122 .RB "[\|" \-warn\-constructors "\|]"
123 .RB "[\|" \-warn\-multiple\-gp "\|]"
124 .RB "[\|" \-warn\-once "\|]"
125 .RB "[\|" \-\-whole\-archive "\|]"
126 .RB "[\|" \-\-no\-whole\-archive "\|]"
127 .RB "[\|" "\-\-wrap\ "\c
137 \& combines a number of object and archive files, relocates
138 their data and ties up symbol references. Often the last step in
139 building a new compiled program to run is a call to \c
145 \& accepts Linker Command Language files
146 to provide explicit and total control over the linking process.
147 This man page does not describe the command language; see the `\|\c
154 \&, for full details on the command language and on other aspects of
159 \& uses the general purpose BFD libraries
160 to operate on object files. This allows \c
162 \& to read, combine, and
163 write object files in many different formats\(em\&for example, COFF or
166 \&. Different formats may be linked together to produce any
167 available kind of object file. You can use `\|\c
169 \|' to get a list of formats supported on various architectures; see
172 Aside from its flexibility, the GNU linker is more helpful than other
173 linkers in providing diagnostic information. Many linkers abandon
174 execution immediately upon encountering an error; whenever possible,
177 \& continues executing, allowing you to identify other errors
178 (or, in some cases, to get an output file in spite of the error).
182 \& is meant to cover a broad range of situations,
183 and to be as compatible as possible with other linkers. As a result,
184 you have many choices to control its behavior through the command line,
185 and through environment variables.
188 The plethora of command-line options may seem intimidating, but in
189 actual practice few of them are used in any particular context.
190 For instance, a frequent use of \c
192 \& is to link standard Unix
193 object files on a standard, supported Unix system. On such a system, to
199 $\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
204 \& to produce a file called \c
207 result of linking the file \c
214 \& which will come from the standard search
217 The command-line options to \c
219 \& may be specified in any order, and
220 may be repeated at will. For the most part, repeating an option with a
221 different argument will either have no further effect, or override prior
222 occurrences (those further to the left on the command line) of an
225 The exceptions\(em\&which may meaningfully be used more than once\(em\&are
230 \& (or its synonym \c
245 The list of object files to be linked together, shown as \c
248 may follow, precede, or be mixed in with command-line options; save that
251 \& argument may not be placed between an option flag and
254 Usually the linker is invoked with at least one object file, but other
255 forms of binary input files can also be specified with \c
260 \&, and the script command language. If \c
263 files at all are specified, the linker does not produce any output, and
264 issues the message `\|\c
268 Option arguments must either follow the option letter without intervening
269 whitespace, or be given as separate arguments immediately following the
270 option that requires them.
273 .BI "-A" "architecture"
274 In the current release of \c
276 \&, this option is useful only for the
277 Intel 960 family of architectures. In that \c
279 \& configuration, the
282 \& argument is one of the two-letter names identifying
283 members of the 960 family; the option specifies the desired output
284 target, and warns of any incompatible instructions in the input files.
285 It also modifies the linker's search strategy for archive libraries, to
286 support the use of libraries specific to each particular
287 architecture, by including in the search loop names suffixed with the
288 string identifying the architecture.
290 For example, if your \c
292 \& command line included `\|\c
297 \|', the linker would look (in its built-in search
298 paths, and in any paths you specify with \c
300 \&) for a library with
314 The first two possibilities would be considered in any event; the last
315 two are due to the use of `\|\c
319 Future releases of \c
321 \& may support similar functionality for
322 other architecture families.
324 You can meaningfully use \c
326 \& more than once on a command line, if
327 an architecture family allows combination of target architectures; each
328 use will add another pair of name variants to search for when \c
333 .BI "\-b " "input-format"
334 Specify the binary format for input object files that follow this option
335 on the command line. You don't usually need to specify this, as
338 \& is configured to expect as a default input format the most
339 usual format on each machine. \c
341 \& is a text string, the
342 name of a particular format supported by the BFD libraries.
347 \& has the same effect, as does the script command
350 You may want to use this option if you are linking files with an unusual
351 binary format. You can also use \c
353 \& to switch formats explicitly (when
354 linking object files of different formats), by including
359 \& before each group of object files in a
362 The default format is taken from the environment variable
364 \&. You can also define the input
365 format from a script, using the command \c
371 Do not link against shared libraries. This is only meaningful on
372 platforms for which shared libraries are supported.
376 Link against dynamic libraries. This is only meaningful on platforms
377 for which shared libraries are supported. This option is normally the
378 default on such platforms.
382 When creating a shared library, bind references to global symbols to
383 the definition within the shared library, if any. Normally, it is
384 possible for a program linked against a shared library to override the
385 definition within the shared library. This option is only meaningful
386 on ELF platforms which support shared libraries.
389 .BI "\-c " "commandfile"
392 \& to read link commands from the file
395 \&. These commands will completely override \c
398 default link format (rather than adding to it); \c
401 specify everything necessary to describe the target format.
404 You may also include a script of link commands directly in the command
405 line by bracketing it between `\|\c
417 These three options are equivalent; multiple forms are supported for
418 compatibility with other linkers. Use any of them to make \c
420 assign space to common symbols even if a relocatable output file is
423 \&). The script command
425 .B FORCE_COMMON_ALLOCATION\c
426 \& has the same effect.
429 .BI "-defsym " "symbol" "\fR = \fP" expression
430 Create a global symbol in the output file, containing the absolute
433 \&. You may use this option as many
434 times as necessary to define multiple symbols in the command line. A
435 limited form of arithmetic is supported for the \c
438 context: you may give a hexadecimal constant or the name of an existing
443 \& to add or subtract hexadecimal
444 constants or symbols. If you need more elaborate expressions, consider
445 using the linker command language from a script.
452 \& as the explicit symbol for beginning execution of your
453 program, rather than the default entry point. for a
454 discussion of defaults and other ways of specifying the
458 .B \-embedded\-relocs
459 This option is only meaningful when linking MIPS embedded PIC code,
462 option to the GNU compiler and assembler. It causes the linker to
463 create a table which may be used at runtime to relocate any data which
464 was statically initialized to pointer values. See the code in
465 testsuite/ld-empic for details.
471 When creating an ELF file, add all symbols to the dynamic symbol table.
472 Normally, the dynamic symbol table contains only symbols which are used
473 by a dynamic object. This option is needed for some uses of
480 Some older linkers used this option throughout a compilation toolchain
481 for specifying object-file format for both input and output object
484 \&'s mechanisms (the \c
489 for input files, the \c
491 \& command in linker scripts for output
494 \& environment variable) are more flexible, but
495 but it accepts (and ignores) the \c
497 \& option flag for compatibility
498 with scripts written to call the old linker.
501 .BI "\-format " "input\-format"
510 Accepted, but ignored; provided for compatibility with other tools.
514 Set the maximum size of objects to be optimized using the GP register
517 under MIPS ECOFF. Ignored for other object file formats.
521 Print a summary of the command-line options on the standard output and exit.
524 begin with two dashes instead of one
525 for compatibility with other GNU programs. The other options start with
526 only one dash for compatibility with other linkers.
530 Perform an incremental link (same as option \c
537 Add an archive file \c
539 \& to the list of files to link. This
540 option may be used any number of times. \c
543 path-list for occurrences of \c
552 .BI "\-L" "searchdir"
553 This command adds path \c
555 \& to the list of paths that
558 \& will search for archive libraries. You may use this option
561 The default set of paths searched (without being specified with
564 \&) depends on what emulation mode \c
567 some cases also on how it was configured. The
568 paths can also be specified in a link script with the \c
574 Print (to the standard output file) a link map\(em\&diagnostic information
575 about where symbols are mapped by \c
577 \&, and information on global
578 common storage allocation.
581 .BI "\-Map " "mapfile"\c
584 a link map\(em\&diagnostic information
585 about where symbols are mapped by \c
587 \&, and information on global
588 common storage allocation.
591 .BI "\-m " "emulation"\c
594 linker. You can list the available emulations with the
598 options. This option overrides the compiled-in default, which is the
599 system for which you configured
604 specifies readable and writable \c
609 the output format supports Unix style magic numbers, the output is
614 When you use the `\|\c
616 \&\|' option, the linker does not page-align the
621 sets the text segment to be read only, and \c
628 Normally, the linker will not produce an output file if it encounters
629 errors during the link process. With this flag, you can specify that
630 you wish the output file retained even after non-fatal errors.
633 .B \-no\-keep\-memory
634 The linker normally optimizes for speed over memory usage by caching
635 the symbol tables of input files in memory. This option tells the
636 linker to instead optimize for memory usage, by rereading the symbol
637 tables as necessary. This may be required if the linker runs out of
638 memory space while linking a large executable.
643 \& is a name for the program produced by \c
646 option is not specified, the name `\|\c
648 \|' is used by default. The
651 \& can also specify the output file name.
654 .BI "\-oformat " "output\-format"
655 Specify the binary format for the output object file.
656 You don't usually need to specify this, as
659 \& is configured to produce as a default output format the most
660 usual format on each machine. \c
662 \& is a text string, the
663 name of a particular format supported by the BFD libraries.
666 can also specify the output format, but this option overrides it.
669 .BI "\-R " "filename"
670 Read symbol names and their addresses from \c
673 relocate it or include it in the output. This allows your output file
674 to refer symbolically to absolute locations of memory defined in other
679 An option with machine dependent effects. Currently this option is only
680 supported on the H8/300.
682 On some platforms, use this option to perform global optimizations that
683 become possible when the linker resolves addressing in your program, such
684 as relaxing address modes and synthesizing new instructions in the
687 On platforms where this is not supported, `\|\c
689 \&\|' is accepted, but has no effect.
693 Generates relocatable output\(em\&i.e., generate an output file that can in
694 turn serve as input to \c
696 \&. This is often called \c
699 \&. As a side effect, in environments that support standard Unix
700 magic numbers, this option also sets the output file's magic number to
704 If this option is not specified, an absolute file is produced. When
705 linking C++ programs, this option \c
707 \& resolve references to
710 \& is an alternative.
712 This option does the same as \c
717 .B \-rpath\ \fIdirectory
718 Add a directory to the runtime library search path. This is used when
719 linking an ELF executable with shared objects. All
721 arguments are concatenated and passed to the runtime linker, which uses
722 them to locate shared objects at runtime. The
724 option is also used when locating shared objects which are needed by
725 shared objects explicitly included in the link; see the description of
730 is not used when linking an ELF executable, the contents of the
733 will be used if it is defined.
737 option may also be used on SunOS. By default, on SunOS, the linker
738 will form a runtime search patch out of all the
740 options it is given. If a
742 option is used, the runtime search path will be formed exclusively
748 options. This can be useful when using gcc, which adds many
750 options which may be on NFS mounted filesystems.
753 .B \-rpath\-link\ \fIdirectory
754 When using ELF or SunOS, one shared library may require another. This
757 link includes a shared library as one of the input files.
759 When the linker encounters such a dependency when doing a non-shared,
760 non-relocateable link, it will automatically try to locate the required
761 shared library and include it in the link, if it is not included
762 explicitly. In such a case, the
764 option specifies the first set of directories to search. The
766 option may specify a sequence of directory names either by specifying
767 a list of names separated by colons, or by appearing multiple times.
769 If the required shared library is not found, the linker will issue a
770 warning and continue with the link.
774 Omits debugger symbol information (but not all symbols) from the output file.
778 Omits all symbol information from the output file.
782 Create a shared library. This is currently only supported on ELF and
783 SunOS platforms (on SunOS it is not required, as the linker will
784 automatically create a shared library when there are undefined symbols
793 places the global common symbols in the appropriate output sections,
794 it sorts them by size. First come all the one byte symbols, then all
795 the two bytes, then all the four bytes, and then everything else.
796 This is to prevent gaps between symbols due to
797 alignment constraints. This option disables that sorting.
800 .B \-split\-by\-reloc\ \fIcount
801 Trys to creates extra sections in the output file so that no single
802 output section in the file contains more than
805 This is useful when generating huge relocatable for downloading into
806 certain real time kernels with the COFF object file format; since COFF
807 cannot represent more than 65535 relocations in a single section.
808 Note that this will fail to work with object file formats which do not
809 support arbitrary sections. The linker will not split up individual
810 input sections for redistribution, so if a single input section
813 relocations one output section will contain that many relocations.
818 .B \-split\-by\-reloc
819 but creates a new output section for each input file.
822 .BI "\-Tbss " "org"\c
824 .BI "\-Tdata " "org"\c
826 .BI "\-Ttext " "org"\c
829 \& as the starting address for\(em\&respectively\(em\&the
836 \& segment of the output file.
839 \& must be a hexadecimal integer.
842 .BI "\-T " "commandfile"
847 \&; supported for compatibility with
852 Prints names of input files as \c
860 \& to be entered in the output file as an undefined symbol.
861 This may, for example, trigger linking of additional modules from
862 standard libraries. \c
864 \& may be repeated with different option
865 arguments to enter additional undefined symbols.
869 For anything other than C++ programs, this option is equivalent to
872 \&: it generates relocatable output\(em\&i.e., an output file that can in
873 turn serve as input to \c
875 \&. When linking C++ programs, \c
878 \& resolve references to constructors, unlike \c
884 Display the version number for \c
886 and list the supported emulations.
887 Display which input files can and can not be opened.
891 Display the version number for \c
896 option also lists the supported emulations.
900 Display the version number for \c
906 Warn when a common symbol is combined with another common symbol or with
907 a symbol definition. Unix linkers allow this somewhat sloppy practice,
908 but linkers on some other operating systems do not. This option allows
909 you to find potential problems from combining global symbols.
912 .B \-warn\-constructors
913 Warn if any global constructors are used. This is only useful for a
914 few object file formats. For formats like COFF or ELF, the linker can
915 not detect the use of global constructors.
918 .B \-warn\-multiple\-gp
919 Warn if the output file requires multiple global-pointer values. This
920 option is only meaningful for certain processors, such as the Alpha.
924 Only warn once for each undefined symbol, rather than once per module
928 .B \-\-whole\-archive
929 For each archive mentioned on the command line after the
930 .B \-\-whole\-archive
931 option, include every object file in the archive in the link, rather
932 than searching the archive for the required object files. This is
933 normally used to turn an archive file into a shared library, forcing
934 every object to be included in the resulting shared library.
937 .B \-\-no\-whole\-archive
938 Turn off the effect of the
939 .B \-\-whole\-archive
940 option for archives which appear later on the command line.
943 .BI "--wrap " "symbol"
944 Use a wrapper function for
946 Any undefined reference to
949 .BI "__wrap_" "symbol".
950 Any undefined reference to
951 .BI "__real_" "symbol"
957 Delete all temporary local symbols. For most targets, this is all local
958 symbols whose names begin with `\|\c
964 Delete all local symbols.
970 You can change the behavior of
972 \& with the environment variable \c
978 \& determines the input-file object format if you don't
981 \& (or its synonym \c
983 \&). Its value should be one
984 of the BFD names for an input format. If there is no
987 \& in the environment, \c
989 \& uses the natural format
994 \& then BFD attempts to discover the
995 input format by examining binary input files; this method often
996 succeeds, but there are potential ambiguities, since there is no method
997 of ensuring that the magic number used to flag object-file formats is
998 unique. However, the configuration procedure for BFD on each system
999 places the conventional format for that system first in the search-list,
1000 so ambiguities are resolved in favor of convention.
1009 .RB "`\|" ld "\|' and `\|" binutils "\|'"
1014 ld: the GNU linker\c
1015 , Steve Chamberlain and Roland Pesch;
1017 The GNU Binary Utilities\c
1021 Copyright (c) 1991, 1992 Free Software Foundation, Inc.
1023 Permission is granted to make and distribute verbatim copies of
1024 this manual provided the copyright notice and this permission notice
1025 are preserved on all copies.
1027 Permission is granted to copy and distribute modified versions of this
1028 manual under the conditions for verbatim copying, provided that the
1029 entire resulting derived work is distributed under the terms of a
1030 permission notice identical to this one.
1032 Permission is granted to copy and distribute translations of this
1033 manual into another language, under the above conditions for modified
1034 versions, except that this permission notice may be included in
1035 translations approved by the Free Software Foundation instead of in
1036 the original English.