1 .\" Copyright (c) 1991, 1992 Free Software Foundation
2 .\" See section COPYING for conditions for redistribution
4 .TH gld 1 "23 January 1992" "cygnus support" "GNU Development Tools"
31 .RB "[\|" \-Bstatic "\|]"
35 .RB "[\|" \-d | \-dc | \-dp\c
38 .RB "[\|" "\-defsym\ "\c
50 .RB "[\|" "\-format\ "\c
61 .RB "[\|" \-M | \-m "\|]"
63 .RB "[\|" \-noinhibit-exec "\|]"
67 .RB "[\|" \-relax "\|]"
68 .RB "[\|" \-r | \-Ur "\|]"
74 .RB "[\|" "\-Ttext\ "\c
77 .RB "[\|" "\-Tdata\ "\c
80 .RB "[\|" "\-Tbss\ "\c
98 \& combines a number of object and archive files, relocates
99 their data and ties up symbol references. Often the last step in
100 building a new compiled program to run is a call to \c
106 \& accepts Linker Command Language files
107 to provide explicit and total control over the linking process.
108 This man page does not describe the command language; see the `\|\c
115 \&, for full details on the command language and on other aspects of
120 \& uses the general purpose BFD libraries
121 to operate on object files. This allows \c
123 \& to read, combine, and
124 write object files in many different formats\(em\&for example, COFF or
127 \&. Different formats may be linked together to produce any
128 available kind of object file. You can use `\|\c
130 \|' to get a list of formats supported on various architectures; see
133 Aside from its flexibility, the GNU linker is more helpful than other
134 linkers in providing diagnostic information. Many linkers abandon
135 execution immediately upon encountering an error; whenever possible,
138 \& continues executing, allowing you to identify other errors
139 (or, in some cases, to get an output file in spite of the error).
143 \& is meant to cover a broad range of situations,
144 and to be as compatible as possible with other linkers. As a result,
145 you have many choices to control its behavior through the command line,
146 and through environment variables.
149 The plethora of command-line options may seem intimidating, but in
150 actual practice few of them are used in any particular context.
151 For instance, a frequent use of \c
153 \& is to link standard Unix
154 object files on a standard, supported Unix system. On such a system, to
160 $\ gld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
165 \& to produce a file called \c
168 result of linking the file \c
175 \& which will come from the standard search
178 The command-line options to \c
180 \& may be specified in any order, and
181 may be repeated at will. For the most part, repeating an option with a
182 different argument will either have no further effect, or override prior
183 occurrences (those further to the left on the command line) of an
186 The exceptions\(em\&which may meaningfully be used more than once\(em\&are
191 \& (or its synonym \c
206 The list of object files to be linked together, shown as \c
209 may follow, precede, or be mixed in with command-line options; save that
212 \& argument may not be placed between an option flag and
215 Usually the linker is invoked with at least one object file, but other
216 forms of binary input files can also be specified with \c
221 \&, and the script command language. If \c
224 files at all are specified, the linker does not produce any output, and
225 issues the message `\|\c
229 Option arguments must either follow the option letter without intervening
230 whitespace, or be given as separate arguments immediately following the
231 option that requires them.
234 .IR "objfiles" .\|.\|.
240 .BI "-A" "architecture"\c
242 In the current release of \c
244 \&, this option is useful only for the
245 Intel 960 family of architectures. In that \c
247 \& configuration, the
250 \& argument is one of the two-letter names identifying
251 members of the 960 family; the option specifies the desired output
252 target, and warns of any incompatible instructions in the input files.
253 It also modifies the linker's search strategy for archive libraries, to
254 support the use of libraries specific to each particular
255 architecture, by including in the search loop names suffixed with the
256 string identifying the architecture.
258 For example, if your \c
260 \& command line included `\|\c
265 \|', the linker would look (in its built-in search
266 paths, and in any paths you specify with \c
268 \&) for a library with
282 The first two possibilities would be considered in any event; the last
283 two are due to the use of `\|\c
287 Future releases of \c
289 \& may support similar functionality for
290 other architecture families.
292 You can meaningfully use \c
294 \& more than once on a command line, if
295 an architecture family allows combination of target architectures; each
296 use will add another pair of name variants to search for when \c
302 .BI "-b " "input-format"\c
304 Specify the binary format for input object files that follow this option
305 on the command line. You don't usually need to specify this, as
308 \& is configured to expect as a default input format the most
309 usual format on each machine. \c
311 \& is a text string, the
312 name of a particular format supported by the BFD libraries.
317 \& has the same effect.
319 You may want to use this option if you are linking files with an unusual
320 binary format. You can also use \c
322 \& to switch formats explicitly (when
323 linking object files of different formats), by including
328 \& before each group of object files in a
331 The default format is taken from the environment variable
333 \&. You can also define the input
334 format from a script, using the command \c
340 This flag is accepted for command-line compatibility with the SunOS linker,
341 but has no effect on \c
346 .BI "-c " "commandfile"\c
350 \& to read link commands from the file
353 \&. These commands will completely override \c
356 default link format (rather than adding to it); \c
359 specify everything necessary to describe the target format.
362 You may also include a script of link commands directly in the command
363 line by bracketing it between `\|\c
375 These three options are equivalent; multiple forms are supported for
376 compatibility with other linkers. Use any of them to make \c
379 assign space to common symbols even if a relocatable output file is
382 \&). The script command
384 .B FORCE_COMMON_ALLOCATION\c
385 \& has the same effect.
388 .BI "-defsym " "symbol"\c
392 Create a global symbol in the output file, containing the absolute
395 \&. You may use this option as many
396 times as necessary to define multiple symbols in the command line. A
397 limited form of arithmetic is supported for the \c
400 context: you may give a hexadecimal constant or the name of an existing
405 \& to add or subtract hexadecimal
406 constants or symbols. If you need more elaborate expressions, consider
407 using the linker command language from a script.
414 \& as the explicit symbol for beginning execution of your
415 program, rather than the default entry point. for a
416 discussion of defaults and other ways of specifying the
424 Some older linkers used this option throughout a compilation toolchain
425 for specifying object-file format for both input and output object
428 \&'s mechanisms (the \c
433 for input files, the \c
435 \& command in linker scripts for output
438 \& environment variable) are more flexible, but
439 but it accepts (and ignores) the \c
441 \& option flag for compatibility
442 with scripts written to call the old linker.
445 .BI "-format " "input-format"\c
455 Accepted, but ignored; provided for compatibility with other tools.
459 Perform an incremental link (same as option \c
466 Add an archive file \c
468 \& to the list of files to link. This
469 option may be used any number of times. \c
472 path-list for occurrences of \c
482 .BI "-L" "searchdir"\c
484 This command adds path \c
486 \& to the list of paths that
489 \& will search for archive libraries. You may use this option
492 The default set of paths searched (without being specified with
495 \&) depends on what emulation mode \c
498 some cases also on how it was configured. The
499 paths can also be specified in a link script with the \c
508 Print (to the standard output file) a link map\(em\&diagnostic information
509 about where symbols are mapped by \c
511 \&, and information on global
512 common storage allocation.
516 sets the text segment to be read only, and \c
523 Normally, the linker will not produce an output file if it encounters
524 errors during the link process. With this flag, you can specify that
525 you wish the output file retained even after non-fatal errors.
534 \& is a name for the program produced by \c
537 option is not specified, the name `\|\c
539 \|' is used by default. The
542 \& can also specify the output file name.
545 .BI "-R " "filename"\c
549 Read symbol names and their addresses from \c
552 relocate it or include it in the output. This allows your output file
553 to refer symbolically to absolute locations of memory defined in other
558 An option with machine dependent effects. Currently this option is only
559 supported on the H8/300.
561 On some platforms, use this option to perform global optimizations that
562 become possible when the linker resolves addressing in your program, such
563 as relaxing address modes and synthesizing new instructions in the
566 On platforms where this is not supported, `\|\c
568 \&\|' is accepted, but has no effect.
572 Generates relocatable output\(em\&i.e., generate an output file that can in
573 turn serve as input to \c
575 \&. This is often called \c
578 \&. As a side effect, in environments that support standard Unix
579 magic numbers, this option also sets the output file's magic number to
583 If this option is not specified, an absolute file is produced. When
584 linking C++ programs, this option \c
586 \& resolve references to
589 \& is an alternative.
591 This option does the same as \c
597 Omits debugger symbol information (but not all symbols) from the output file.
601 Omits all symbol information from the output file.
604 .BI "{ " "script" " }"
605 You can, if you wish, include a script of linker commands directly in
606 the command line instead of referring to it via an input file. When the
609 \|' occurs on the command line, the linker switches to
610 interpreting the command language until the end of the list of commands
611 is reached\(em\&flagged with a closing brace `\|\c
613 \|'. Other command-line
614 options will not be recognized while parsing the script.
615 for a description of the command language.
620 .BI "-Tdata " "org"\c
622 .BI "-Ttext " "org"\c
625 \& as the starting address for\(em\&respectively\(em\&the
632 \& segment of the output file.
635 \& must be a hexadecimal integer.
638 .BI "-T " "commandfile"\c
641 .BI "-T" "commandfile"\c
646 \&; supported for compatibility with
651 Prints names of input files as \c
662 \& to be entered in the output file as an undefined symbol.
663 This may, for example, trigger linking of additional modules from
664 standard libraries. \c
666 \& may be repeated with different option
667 arguments to enter additional undefined symbols.
671 For anything other than C++ programs, this option is equivalent to
674 \&: it generates relocatable output\(em\&i.e., an output file that can in
675 turn serve as input to \c
677 \&. When linking C++ programs, \c
682 \& resolve references to constructors, unlike \c
688 Display the version number for \c
698 \& is also specified, delete only local symbols
709 \& is also specified, delete all local symbols,
710 not just those beginning with `\|\c
719 \& always consults two environment variables: \c
724 \&. Depending on the setting of the latter, other
725 environment variables may be used as well.
729 \& determines the input-file object format if you don't
732 \& (or its synonym \c
734 \&). Its value should be one
735 of the BFD names for an input format. If there is no
738 \& in the environment, \c
740 \& uses the natural format
745 \& then BFD attempts to discover the
746 input format by examining binary input files; this method often
747 succeeds, but there are potential ambiguities, since there is no method
748 of ensuring that the magic number used to flag object-file formats is
749 unique. However, the configuration procedure for BFD on each system
750 places the conventional format for that system first in the search-list,
751 so ambiguities are resolved in favor of convention.
755 \& controls some aspects of \c
758 personality. Although \c
760 \& is flexible enough to permit its use
761 in many contexts regardless of configuration, you can use this variable
762 to make it act more like one or another older linker by default.
764 In particular, the value of \c
766 \& controls what default
767 linker script is used (thereby controlling the default input and output
768 formats; ; what default paths are searched for
769 archive libraries; and in some cases whether additional linker script
770 commands are available.
772 Here is the current set of emulations available:
776 Emulate the older GNU linker. When this emulation is selected, the
777 default library search paths are
788 The default output format is set to \c
789 .B a.out-generic-big\c
791 default machine is the system's configured BFD default.
794 .B LDEMULATION=gld68k
797 \& emulation; only differs in specifically
798 setting the default BFD machine as \c
803 .B LDEMULATION=gld960
804 Emulate the Intel port of the older \c
807 architectures. The default library search paths are taken from two
808 other environment variables, \c
813 default architecture is \c
815 \&. The default output format is set
818 \&, and in fact the default output file name (if
821 \& is not specified) is \c
823 \&, to reflect this variant
824 format, for this emulation.
826 This emulation can behave slightly differently depending on the setting
829 \& compile-time switch \c
836 \& defined, then an additional environment
839 \&\(em\&is available; its value, if available,
840 specifies some other default output format than \c
845 .B LDEMULATION=gldm88kbcs
846 Sets the output format to \c
848 \& and the architecture to
851 \&. Default library search paths are
863 .B LDEMULATION=lnk960
864 Emulate the Intel linker \c
866 \&. The default output format is
869 \&. With this emulation, \c
872 supports the additional script commands \c
877 specification of library archives. This is the only emulation with
878 extensive support for the \c
880 \& (architecture) command-line option.
881 By default, the architecture \c
883 \& is assumed, but you can choose
884 additional features from the i960 architecture family by using one of
885 the following with \c
887 \& (or by using the \c
911 The default libraries are chosen with some attention to the architecture
912 selected; the core library `\|\c
914 \|' is always included, but the library
917 \& is also used if you've specified any of the architectures
928 \&, this emulation uses additional environment variables
929 to set the default library search paths. Also like \c
932 behavior of this emulation is slightly different depending on whether
935 \& itself was compiled with \c
941 \& was compiled with \c
943 \& defined, the default
944 paths are taken from all three of \c
951 \&. For the first two, paths you supply are automatically
954 \|'; for the last, your path is
955 automatically suffixed with `\|\c
966 the default paths are taken from \c
973 \& is undefined. In this case
976 \& is not used at all.
979 .B LDEMULATION=vanilla
980 This is the least specific setting for \c
984 .B LDEMULATION=vanilla\c
985 \& to disable emulation of other linkers. This
988 \& take the default machine from the BFD
989 configuration on your system; \c
990 .B a.out-generic-big\c
992 target. No other defaults are specified.
1001 .RB "`\|" ld "\|' and `\|" binutils "\|'"
1006 gld: the GNU linker\c
1007 , Steve Chamberlain and Roland Pesch;
1009 The GNU Binary Utilities\c
1013 Copyright (c) 1991, 1992 Free Software Foundation, Inc.
1015 Permission is granted to make and distribute verbatim copies of
1016 this manual provided the copyright notice and this permission notice
1017 are preserved on all copies.
1019 Permission is granted to copy and distribute modified versions of this
1020 manual under the conditions for verbatim copying, provided that the
1021 entire resulting derived work is distributed under the terms of a
1022 permission notice identical to this one.
1024 Permission is granted to copy and distribute translations of this
1025 manual into another language, under the above conditions for modified
1026 versions, except that this permission notice may be included in
1027 translations approved by the Free Software Foundation instead of in
1028 the original English.