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 "[\|" \-\-cref "\|]"
37 .RB "[\|" \-d | \-dc | \-dp\c
40 .RB "[\|" "\-defsym\ "\c
48 .RB "[\|" \-embedded\-relocs "\|]"
50 .RB "[\|" \-export\-dynamic "\|]"
55 .RB "[\|" "\-format\ "\c
62 .RB "[\|" \-\-help "\|]"
77 .RB "[\|" \-n | \-N "\|]"
78 .RB "[\|" \-noinhibit-exec "\|]"
79 .RB "[\|" \-no\-keep\-memory "\|]"
80 .RB "[\|" "\-oformat\ "\c
86 .RB "[\|" \-relax "\|]"
87 .RB "[\|" \-r | \-Ur "\|]"
88 .RB "[\|" "\-rpath\ "\c
91 .RB "[\|" "\-rpath\-link\ "\c
96 .RB "[\|" \-shared "\|]"
97 .RB "[\|" \-sort\-common "\|]"
98 .RB "[\|" "\-split\-by\-reloc\ "\c
101 .RB "[\|" \-split\-by\-file "\|]"
105 .RB "[\|" "\-Ttext\ "\c
108 .RB "[\|" "\-Tdata\ "\c
111 .RB "[\|" "\-Tbss\ "\c
120 .RB "[\|" \-\-verbose "\|]"
121 .RB "[\|" \-\-version "\|]"
122 .RB "[\|" \-warn\-common "\|]"
123 .RB "[\|" \-warn\-constructors "\|]"
124 .RB "[\|" \-warn\-multiple\-gp "\|]"
125 .RB "[\|" \-warn\-once "\|]"
126 .RB "[\|" \-warn\-section\-align "\|]"
127 .RB "[\|" \-\-whole\-archive "\|]"
128 .RB "[\|" \-\-no\-whole\-archive "\|]"
129 .RB "[\|" "\-\-wrap\ "\c
139 \& combines a number of object and archive files, relocates
140 their data and ties up symbol references. Often the last step in
141 building a new compiled program to run is a call to \c
147 \& accepts Linker Command Language files
148 to provide explicit and total control over the linking process.
149 This man page does not describe the command language; see the `\|\c
156 \&, for full details on the command language and on other aspects of
161 \& uses the general purpose BFD libraries
162 to operate on object files. This allows \c
164 \& to read, combine, and
165 write object files in many different formats\(em\&for example, COFF or
168 \&. Different formats may be linked together to produce any
169 available kind of object file. You can use `\|\c
171 \|' to get a list of formats supported on various architectures; see
174 Aside from its flexibility, the GNU linker is more helpful than other
175 linkers in providing diagnostic information. Many linkers abandon
176 execution immediately upon encountering an error; whenever possible,
179 \& continues executing, allowing you to identify other errors
180 (or, in some cases, to get an output file in spite of the error).
184 \& is meant to cover a broad range of situations,
185 and to be as compatible as possible with other linkers. As a result,
186 you have many choices to control its behavior through the command line,
187 and through environment variables.
190 The plethora of command-line options may seem intimidating, but in
191 actual practice few of them are used in any particular context.
192 For instance, a frequent use of \c
194 \& is to link standard Unix
195 object files on a standard, supported Unix system. On such a system, to
201 $\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
206 \& to produce a file called \c
209 result of linking the file \c
216 \& which will come from the standard search
219 The command-line options to \c
221 \& may be specified in any order, and
222 may be repeated at will. For the most part, repeating an option with a
223 different argument will either have no further effect, or override prior
224 occurrences (those further to the left on the command line) of an
227 The exceptions\(em\&which may meaningfully be used more than once\(em\&are
232 \& (or its synonym \c
247 The list of object files to be linked together, shown as \c
250 may follow, precede, or be mixed in with command-line options; save that
253 \& argument may not be placed between an option flag and
256 Usually the linker is invoked with at least one object file, but other
257 forms of binary input files can also be specified with \c
262 \&, and the script command language. If \c
265 files at all are specified, the linker does not produce any output, and
266 issues the message `\|\c
270 Option arguments must either follow the option letter without intervening
271 whitespace, or be given as separate arguments immediately following the
272 option that requires them.
275 .BI "-A" "architecture"
276 In the current release of \c
278 \&, this option is useful only for the
279 Intel 960 family of architectures. In that \c
281 \& configuration, the
284 \& argument is one of the two-letter names identifying
285 members of the 960 family; the option specifies the desired output
286 target, and warns of any incompatible instructions in the input files.
287 It also modifies the linker's search strategy for archive libraries, to
288 support the use of libraries specific to each particular
289 architecture, by including in the search loop names suffixed with the
290 string identifying the architecture.
292 For example, if your \c
294 \& command line included `\|\c
299 \|', the linker would look (in its built-in search
300 paths, and in any paths you specify with \c
302 \&) for a library with
316 The first two possibilities would be considered in any event; the last
317 two are due to the use of `\|\c
321 Future releases of \c
323 \& may support similar functionality for
324 other architecture families.
326 You can meaningfully use \c
328 \& more than once on a command line, if
329 an architecture family allows combination of target architectures; each
330 use will add another pair of name variants to search for when \c
335 .BI "\-b " "input-format"
336 Specify the binary format for input object files that follow this option
337 on the command line. You don't usually need to specify this, as
340 \& is configured to expect as a default input format the most
341 usual format on each machine. \c
343 \& is a text string, the
344 name of a particular format supported by the BFD libraries.
349 \& has the same effect, as does the script command
352 You may want to use this option if you are linking files with an unusual
353 binary format. You can also use \c
355 \& to switch formats explicitly (when
356 linking object files of different formats), by including
361 \& before each group of object files in a
364 The default format is taken from the environment variable
366 \&. You can also define the input
367 format from a script, using the command \c
373 Do not link against shared libraries. This is only meaningful on
374 platforms for which shared libraries are supported.
378 Link against dynamic libraries. This is only meaningful on platforms
379 for which shared libraries are supported. This option is normally the
380 default on such platforms.
384 When creating a shared library, bind references to global symbols to
385 the definition within the shared library, if any. Normally, it is
386 possible for a program linked against a shared library to override the
387 definition within the shared library. This option is only meaningful
388 on ELF platforms which support shared libraries.
391 .BI "\-c " "commandfile"
394 \& to read link commands from the file
397 \&. These commands will completely override \c
400 default link format (rather than adding to it); \c
403 specify everything necessary to describe the target format.
406 You may also include a script of link commands directly in the command
407 line by bracketing it between `\|\c
415 Output a cross reference table. If a linker map file is being
416 generated, the cross reference table is printed to the map file.
417 Otherwise, it is printed on the standard output.
425 These three options are equivalent; multiple forms are supported for
426 compatibility with other linkers. Use any of them to make \c
428 assign space to common symbols even if a relocatable output file is
431 \&). The script command
433 .B FORCE_COMMON_ALLOCATION\c
434 \& has the same effect.
437 .BI "-defsym " "symbol" "\fR = \fP" expression
438 Create a global symbol in the output file, containing the absolute
441 \&. You may use this option as many
442 times as necessary to define multiple symbols in the command line. A
443 limited form of arithmetic is supported for the \c
446 context: you may give a hexadecimal constant or the name of an existing
451 \& to add or subtract hexadecimal
452 constants or symbols. If you need more elaborate expressions, consider
453 using the linker command language from a script.
460 \& as the explicit symbol for beginning execution of your
461 program, rather than the default entry point. for a
462 discussion of defaults and other ways of specifying the
466 .B \-embedded\-relocs
467 This option is only meaningful when linking MIPS embedded PIC code,
470 option to the GNU compiler and assembler. It causes the linker to
471 create a table which may be used at runtime to relocate any data which
472 was statically initialized to pointer values. See the code in
473 testsuite/ld-empic for details.
479 When creating an ELF file, add all symbols to the dynamic symbol table.
480 Normally, the dynamic symbol table contains only symbols which are used
481 by a dynamic object. This option is needed for some uses of
488 Some older linkers used this option throughout a compilation toolchain
489 for specifying object-file format for both input and output object
492 \&'s mechanisms (the \c
497 for input files, the \c
499 \& command in linker scripts for output
502 \& environment variable) are more flexible, but
503 but it accepts (and ignores) the \c
505 \& option flag for compatibility
506 with scripts written to call the old linker.
509 .BI "\-format " "input\-format"
518 Accepted, but ignored; provided for compatibility with other tools.
522 Set the maximum size of objects to be optimized using the GP register
525 under MIPS ECOFF. Ignored for other object file formats.
529 Print a summary of the command-line options on the standard output and exit.
532 begin with two dashes instead of one
533 for compatibility with other GNU programs. The other options start with
534 only one dash for compatibility with other linkers.
538 Perform an incremental link (same as option \c
545 Add an archive file \c
547 \& to the list of files to link. This
548 option may be used any number of times. \c
551 path-list for occurrences of \c
560 .BI "\-L" "searchdir"
561 This command adds path \c
563 \& to the list of paths that
566 \& will search for archive libraries. You may use this option
569 The default set of paths searched (without being specified with
572 \&) depends on what emulation mode \c
575 some cases also on how it was configured. The
576 paths can also be specified in a link script with the \c
582 Print (to the standard output file) a link map\(em\&diagnostic information
583 about where symbols are mapped by \c
585 \&, and information on global
586 common storage allocation.
589 .BI "\-Map " "mapfile"\c
592 a link map\(em\&diagnostic information
593 about where symbols are mapped by \c
595 \&, and information on global
596 common storage allocation.
599 .BI "\-m " "emulation"\c
602 linker. You can list the available emulations with the
606 options. This option overrides the compiled-in default, which is the
607 system for which you configured
612 specifies readable and writable \c
617 the output format supports Unix style magic numbers, the output is
622 When you use the `\|\c
624 \&\|' option, the linker does not page-align the
629 sets the text segment to be read only, and \c
636 Normally, the linker will not produce an output file if it encounters
637 errors during the link process. With this flag, you can specify that
638 you wish the output file retained even after non-fatal errors.
641 .B \-no\-keep\-memory
642 The linker normally optimizes for speed over memory usage by caching
643 the symbol tables of input files in memory. This option tells the
644 linker to instead optimize for memory usage, by rereading the symbol
645 tables as necessary. This may be required if the linker runs out of
646 memory space while linking a large executable.
651 \& is a name for the program produced by \c
654 option is not specified, the name `\|\c
656 \|' is used by default. The
659 \& can also specify the output file name.
662 .BI "\-oformat " "output\-format"
663 Specify the binary format for the output object file.
664 You don't usually need to specify this, as
667 \& is configured to produce as a default output format the most
668 usual format on each machine. \c
670 \& is a text string, the
671 name of a particular format supported by the BFD libraries.
674 can also specify the output format, but this option overrides it.
677 .BI "\-R " "filename"
678 Read symbol names and their addresses from \c
681 relocate it or include it in the output. This allows your output file
682 to refer symbolically to absolute locations of memory defined in other
687 An option with machine dependent effects. Currently this option is only
688 supported on the H8/300.
690 On some platforms, use this option to perform global optimizations that
691 become possible when the linker resolves addressing in your program, such
692 as relaxing address modes and synthesizing new instructions in the
695 On platforms where this is not supported, `\|\c
697 \&\|' is accepted, but has no effect.
701 Generates relocatable output\(em\&i.e., generate an output file that can in
702 turn serve as input to \c
704 \&. This is often called \c
707 \&. As a side effect, in environments that support standard Unix
708 magic numbers, this option also sets the output file's magic number to
712 If this option is not specified, an absolute file is produced. When
713 linking C++ programs, this option \c
715 \& resolve references to
718 \& is an alternative.
720 This option does the same as \c
725 .B \-rpath\ \fIdirectory
726 Add a directory to the runtime library search path. This is used when
727 linking an ELF executable with shared objects. All
729 arguments are concatenated and passed to the runtime linker, which uses
730 them to locate shared objects at runtime. The
732 option is also used when locating shared objects which are needed by
733 shared objects explicitly included in the link; see the description of
738 is not used when linking an ELF executable, the contents of the
741 will be used if it is defined.
745 option may also be used on SunOS. By default, on SunOS, the linker
746 will form a runtime search patch out of all the
748 options it is given. If a
750 option is used, the runtime search path will be formed exclusively
756 options. This can be useful when using gcc, which adds many
758 options which may be on NFS mounted filesystems.
761 .B \-rpath\-link\ \fIdirectory
762 When using ELF or SunOS, one shared library may require another. This
765 link includes a shared library as one of the input files.
767 When the linker encounters such a dependency when doing a non-shared,
768 non-relocateable link, it will automatically try to locate the required
769 shared library and include it in the link, if it is not included
770 explicitly. In such a case, the
772 option specifies the first set of directories to search. The
774 option may specify a sequence of directory names either by specifying
775 a list of names separated by colons, or by appearing multiple times.
777 If the required shared library is not found, the linker will issue a
778 warning and continue with the link.
782 Omits debugger symbol information (but not all symbols) from the output file.
786 Omits all symbol information from the output file.
790 Create a shared library. This is currently only supported on ELF and
791 SunOS platforms (on SunOS it is not required, as the linker will
792 automatically create a shared library when there are undefined symbols
801 places the global common symbols in the appropriate output sections,
802 it sorts them by size. First come all the one byte symbols, then all
803 the two bytes, then all the four bytes, and then everything else.
804 This is to prevent gaps between symbols due to
805 alignment constraints. This option disables that sorting.
808 .B \-split\-by\-reloc\ \fIcount
809 Trys to creates extra sections in the output file so that no single
810 output section in the file contains more than
813 This is useful when generating huge relocatable for downloading into
814 certain real time kernels with the COFF object file format; since COFF
815 cannot represent more than 65535 relocations in a single section.
816 Note that this will fail to work with object file formats which do not
817 support arbitrary sections. The linker will not split up individual
818 input sections for redistribution, so if a single input section
821 relocations one output section will contain that many relocations.
826 .B \-split\-by\-reloc
827 but creates a new output section for each input file.
830 .BI "\-Tbss " "org"\c
832 .BI "\-Tdata " "org"\c
834 .BI "\-Ttext " "org"\c
837 \& as the starting address for\(em\&respectively\(em\&the
844 \& segment of the output file.
847 \& must be a hexadecimal integer.
850 .BI "\-T " "commandfile"
855 \&; supported for compatibility with
860 Prints names of input files as \c
868 \& to be entered in the output file as an undefined symbol.
869 This may, for example, trigger linking of additional modules from
870 standard libraries. \c
872 \& may be repeated with different option
873 arguments to enter additional undefined symbols.
877 For anything other than C++ programs, this option is equivalent to
880 \&: it generates relocatable output\(em\&i.e., an output file that can in
881 turn serve as input to \c
883 \&. When linking C++ programs, \c
886 \& resolve references to constructors, unlike \c
892 Display the version number for \c
894 and list the supported emulations.
895 Display which input files can and can not be opened.
899 Display the version number for \c
904 option also lists the supported emulations.
908 Display the version number for \c
914 Warn when a common symbol is combined with another common symbol or with
915 a symbol definition. Unix linkers allow this somewhat sloppy practice,
916 but linkers on some other operating systems do not. This option allows
917 you to find potential problems from combining global symbols.
920 .B \-warn\-constructors
921 Warn if any global constructors are used. This is only useful for a
922 few object file formats. For formats like COFF or ELF, the linker can
923 not detect the use of global constructors.
926 .B \-warn\-multiple\-gp
927 Warn if the output file requires multiple global-pointer values. This
928 option is only meaningful for certain processors, such as the Alpha.
932 Only warn once for each undefined symbol, rather than once per module
936 .B \-warn\-section\-align
937 Warn if the address of an output section is changed because of
938 alignment. Typically, the alignment will be set by an input section.
939 The address will only be changed if it not explicitly specified; that
940 is, if the SECTIONS command does not specify a start address for the
944 .B \-\-whole\-archive
945 For each archive mentioned on the command line after the
946 .B \-\-whole\-archive
947 option, include every object file in the archive in the link, rather
948 than searching the archive for the required object files. This is
949 normally used to turn an archive file into a shared library, forcing
950 every object to be included in the resulting shared library.
953 .B \-\-no\-whole\-archive
954 Turn off the effect of the
955 .B \-\-whole\-archive
956 option for archives which appear later on the command line.
959 .BI "--wrap " "symbol"
960 Use a wrapper function for
962 Any undefined reference to
965 .BI "__wrap_" "symbol".
966 Any undefined reference to
967 .BI "__real_" "symbol"
973 Delete all temporary local symbols. For most targets, this is all local
974 symbols whose names begin with `\|\c
980 Delete all local symbols.
986 You can change the behavior of
988 \& with the environment variable \c
994 \& determines the input-file object format if you don't
997 \& (or its synonym \c
999 \&). Its value should be one
1000 of the BFD names for an input format. If there is no
1003 \& in the environment, \c
1005 \& uses the natural format
1010 \& then BFD attempts to discover the
1011 input format by examining binary input files; this method often
1012 succeeds, but there are potential ambiguities, since there is no method
1013 of ensuring that the magic number used to flag object-file formats is
1014 unique. However, the configuration procedure for BFD on each system
1015 places the conventional format for that system first in the search-list,
1016 so ambiguities are resolved in favor of convention.
1025 .RB "`\|" ld "\|' and `\|" binutils "\|'"
1030 ld: the GNU linker\c
1031 , Steve Chamberlain and Roland Pesch;
1033 The GNU Binary Utilities\c
1037 Copyright (c) 1991, 1992 Free Software Foundation, Inc.
1039 Permission is granted to make and distribute verbatim copies of
1040 this manual provided the copyright notice and this permission notice
1041 are preserved on all copies.
1043 Permission is granted to copy and distribute modified versions of this
1044 manual under the conditions for verbatim copying, provided that the
1045 entire resulting derived work is distributed under the terms of a
1046 permission notice identical to this one.
1048 Permission is granted to copy and distribute translations of this
1049 manual into another language, under the above conditions for modified
1050 versions, except that this permission notice may be included in
1051 translations approved by the Free Software Foundation instead of in
1052 the original English.