4 @c @include configdoc.texi
12 * Ld:: The GNU linker.
18 This file documents the GNU linker LD.
20 Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
22 Permission is granted to make and distribute verbatim copies of
23 this manual provided the copyright notice and this permission notice
24 are preserved on all copies.
26 Permission is granted to copy and distribute modified versions of this
27 manual under the conditions for verbatim copying, provided also that
28 the entire resulting derived work is distributed under the terms of a
29 permission notice identical to this one.
31 Permission is granted to copy and distribute translations of this manual
32 into another language, under the above conditions for modified versions.
35 Permission is granted to process this file through Tex and print the
36 results, provided the printed document carries copying permission
37 notice identical to this one except for the removal of this paragraph
38 (this paragraph not being relevant to the printed manual).
44 @setchapternewpage odd
45 @settitle Using LD, the GNU linker
48 @subtitle The GNU linker
50 @subtitle @code{ld} version 2
52 @author Steve Chamberlain and Roland Pesch
53 @author Cygnus Support
58 \hfill Cygnus Support\par
59 \hfill steve\@cygnus.com, pesch\@cygnus.com\par
60 \hfill {\it Using LD, the GNU linker}\par
61 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com), March 1993.\par
63 \global\parindent=0pt % Steve likes it this way.
66 @vskip 0pt plus 1filll
67 Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
69 Permission is granted to make and distribute verbatim copies of
70 this manual provided the copyright notice and this permission notice
71 are preserved on all copies.
73 Permission is granted to copy and distribute modified versions of this
74 manual under the conditions for verbatim copying, provided also that
75 the entire resulting derived work is distributed under the terms of a
76 permission notice identical to this one.
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions.
82 @c FIXME: Talk about importance of *order* of args, cmds to linker!
87 This file documents the GNU linker ld.
91 * Invocation:: Invocation
92 * Commands:: Command Language
94 * Machine Dependent:: Machine Dependent Features
98 * H8/300:: ld and the H8/300
101 * i960:: ld and the Intel 960 family
104 @ifclear SingleFormat
107 @c Following blank line required for remaining bug in makeinfo conds/menus
109 * MRI:: MRI Compatible Script Files
118 @cindex what is this?
119 @code{ld} combines a number of object and archive files, relocates
120 their data and ties up symbol references. Usually the last step in
121 compiling a program is to run @code{ld}.
123 @code{ld} accepts Linker Command Language files written in
124 a superset of AT&T's Link Editor Command Language syntax,
125 to provide explicit and total control over the linking process.
127 @ifclear SingleFormat
128 This version of @code{ld} uses the general purpose BFD libraries
129 to operate on object files. This allows @code{ld} to read, combine, and
130 write object files in many different formats---for example, COFF or
131 @code{a.out}. Different formats may be linked together to produce any
132 available kind of object file. @xref{BFD} for a list of formats
133 supported on various architectures.
136 Aside from its flexibility, the GNU linker is more helpful than other
137 linkers in providing diagnostic information. Many linkers abandon
138 execution immediately upon encountering an error; whenever possible,
139 @code{ld} continues executing, allowing you to identify other errors
140 (or, in some cases, to get an output file in spite of the error).
145 The GNU linker @code{ld} is meant to cover a broad range of situations,
146 and to be as compatible as possible with other linkers. As a result,
147 you have many choices to control its behavior.
151 * Options:: Command Line Options
152 * Environment:: Environment Variables
156 @section Command Line Options
161 Here is a summary of the options you can use on the @code{ld} command
164 @c FIXME! -relax only avail h8/300, i960. Conditionals screwed in examples.
166 ld [-o @var{output} ] @var{objfile}@dots{}
167 [ -A@var{architecture} ] [ -b @var{input-format} ] [ -Bstatic ]
168 [ -c @var{MRI-commandfile} ] [ -d | -dc | -dp ]
169 [ -defsym @var{symbol}=@var{expression} ]
170 [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
171 [ -format @var{input-format} ] [ -g ] [ -G @var{size} ] [ -i ]
172 [ -l@var{ar} ] [ -L@var{searchdir} ] [ -M ] [ -Map @var{mapfile} ]
173 [ -m @var{emulation} ] [ -N | -n ] [ -noinhibit-exec ]
174 [ -R @var{filename} ] [ -relax ] [ -r | -Ur ] [ -S ] [ -s ]
175 [ -T @var{commandfile} ] [ -Ttext @var{textorg} ] [ -Tdata @var{dataorg} ]
176 [ -Tbss @var{bssorg} ] [ -t ] [ -u @var{sym}] [-V] [-v] [ -X ] [-x ]
177 [ -y@var{symbol} ] [ @{ @var{script} @} ]
180 This plethora of command-line options may seem intimidating, but in
181 actual practice few of them are used in any particular context.
182 @cindex standard Unix system
183 For instance, a frequent use of @code{ld} is to link standard Unix
184 object files on a standard, supported Unix system. On such a system, to
185 link a file @code{hello.o}:
188 ld -o @var{output} /lib/crt0.o hello.o -lc
191 This tells @code{ld} to produce a file called @var{output} as the
192 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
193 the library @code{libc.a}, which will come from the standard search
194 directories. (See the discussion of the @samp{-l} option below.)
196 The command-line options to @code{ld} may be specified in any order, and
197 may be repeated at will. Repeating most options with a
198 different argument will either have no further effect, or override prior
199 occurrences (those further to the left on the command line) of that
202 @ifclear SingleFormat
203 The exceptions---which may meaningfully be used more than once---are
204 @samp{-A}, @samp{-b} (or its synonym @samp{-format}), @samp{-defsym},
205 @samp{-L}, @samp{-l}, @samp{-R}, and @samp{-u}.
208 The exceptions---which may meaningfully be used more than once---are
209 @samp{-A}, @samp{-defsym}, @samp{-L}, @samp{-l}, @samp{-R}, and @samp{-u}.
213 The list of object files to be linked together, shown as @var{objfile}@dots{},
214 may follow, precede, or be mixed in with command-line options, except that
215 an @var{objfile} argument may not be placed between an option and
218 Usually the linker is invoked with at least one object file, but other
219 forms of binary input files can also be specified with @samp{-l},
220 @samp{-R}, and the script command language. If @emph{no} binary input
221 files at all are specified, the linker does not produce any output, and
222 issues the message @samp{No input files}.
224 Option arguments must either follow the option letter without intervening
225 whitespace, or be given as separate arguments immediately following the
226 option that requires them.
229 @item @var{objfile}@dots{}
230 The object files to be linked.
233 @cindex architectures
235 @item -A@var{architecture}
236 In the current release of @code{ld}, this option is useful only for the
237 Intel 960 family of architectures. In that @code{ld} configuration, the
238 @var{architecture} argument identifies the particular architecture in
239 the 960 family, enabling some safeguards and modifying the
240 archive-library search path. @xref{i960,,@code{ld} and the Intel 960
241 family}, for details.
243 Future releases of @code{ld} may support similar functionality for
244 other architecture families.
247 @ifclear SingleFormat
248 @cindex binary input format
249 @kindex -b @var{format}
251 @item -b @var{input-format}
253 Specify the binary format for input object files that follow this option
254 on the command line. You don't usually need to specify this, as
255 @code{ld} is configured to expect as a default input format the most
256 usual format on each machine. @var{input-format} is a text string, the
257 name of a particular format supported by the BFD libraries.
258 @w{@samp{-format @var{input-format}}} has the same effect. @xref{BFD}.
260 You may want to use this option if you are linking files with an unusual
261 binary format. You can also use @samp{-b} to switch formats explicitly (when
262 linking object files of different formats), by including
263 @samp{-b @var{input-format}} before each group of object files in a
266 The default format is taken from the environment variable
271 You can also define the input
272 format from a script, using the command @code{TARGET}; see @ref{Other
278 Ignored. This option is accepted for command-line compatibility with
281 @kindex -c @var{MRI-cmdfile}
282 @cindex compatibility, MRI
283 @item -c @var{MRI-commandfile}
284 For compatibility with linkers produced by MRI, @code{ld} accepts script
285 files written in an alternate, restricted command language, described in
286 @ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
287 the option @samp{-c}; use the @samp{-T} option to run linker
288 scripts written in the general-purpose @code{ld} scripting language.
289 If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
290 specified by any @samp{-L} options.
292 @cindex common allocation
299 These three options are equivalent; multiple forms are supported for
300 compatibility with other linkers. They
301 assign space to common symbols even if a relocatable output file is
302 specified (with @samp{-r}). The script command
303 @code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Other
306 @cindex symbols, from command line
307 @kindex -defsym @var{symbol}=@var{exp}
308 @item -defsym @var{symbol}=@var{expression}
309 Create a global symbol in the output file, containing the absolute
310 address given by @var{expression}. You may use this option as many
311 times as necessary to define multiple symbols in the command line. A
312 limited form of arithmetic is supported for the @var{expression} in this
313 context: you may give a hexadecimal constant or the name of an existing
314 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
315 constants or symbols. If you need more elaborate expressions, consider
316 using the linker command language from a script (@pxref{Assignment, ,
317 Assignment: Symbol Definitions}). @emph{Note:} there should be no
318 white space between @var{symbol}, the equals sign (``@key{=}''), and
321 @cindex entry point, from command line
322 @kindex -e @var{entry}
324 Use @var{entry} as the explicit symbol for beginning execution of your
325 program, rather than the default entry point. @xref{Entry Point}, for a
326 discussion of defaults and other ways of specifying the
329 @ifclear SingleFormat
332 @itemx -F@var{format}
333 Ignored. Some older linkers used this option throughout a compilation
334 toolchain for specifying object-file format for both input and output
335 object files. The mechanisms @code{ld} uses for this purpose (the
336 @samp{-b} or @samp{-format} options for input files, the @code{TARGET}
337 command in linker scripts for output files, the @code{GNUTARGET}
338 environment variable) are more flexible, but @code{ld} accepts the
339 @samp{-F} option for compatibility with scripts written to call the old
343 @item -format @var{input-format}
344 Synonym for @samp{-b @var{input-format}}.
349 Ignored. Provided for compatibility with other tools.
354 @itemx -G @var{value}
355 Set the maximum size of objects to be optimized using the GP register to
356 @var{size} under MIPS ECOFF. Ignored for other object file formats.
359 @cindex incremental link
361 Perform an incremental link (same as option @samp{-r}).
363 @cindex archive files, from cmd line
366 Add archive file @var{ar} to the list of files to link. This
367 option may be used any number of times. @code{ld} will search its
368 path-list for occurrences of @code{lib@var{ar}.a} for every @var{ar}
371 @cindex search directory, from cmd line
373 @item -L@var{searchdir}
374 Add path @var{searchdir} to the list of paths that @code{ld} will search
375 for archive libraries and @code{ld} control scripts. You may use this
376 option any number of times.
379 The default set of paths searched (without being specified with
380 @samp{-L}) depends on which emulation mode @code{ld} is using, and in
381 some cases also on how it was configured. @xref{Environment}.
384 The paths can also be specified in a link script with the
385 @code{SEARCH_DIR} command.
390 Print (to the standard output) a link map---diagnostic information
391 about where symbols are mapped by @code{ld}, and information on global
392 common storage allocation.
396 @item -Map @var{mapfile}
397 Print to the file @var{mapfile} a link map---diagnostic information
398 about where symbols are mapped by @code{ld}, and information on global
399 common storage allocation.
402 @kindex -m @var{emulation}
403 @item -m@var{emulation}
404 @itemx -m @var{emulation}
405 Emulate the @var{emulation} linker. You can list the available
406 emulations with the @samp{-V} option. The
407 default is the system for which you configured @code{ld}.
410 @cindex read/write from cmd line
413 Set the text and data sections to be readable and writable. Also, do
414 not page-align the data segment. If the output format supports Unix
415 style magic numbers, mark the output as @code{OMAGIC}.
419 @cindex read-only text
421 Set the text segment to be read only, and mark the output as
422 @code{NMAGIC} if possible.
424 @item -noinhibit-exec
425 @cindex output file after errors
426 @kindex -noinhibit-exec
427 Retain the executable output file whenever it is still usable.
428 Normally, the linker will not produce an output file if it encounters
429 errors during the link process; it exits without writing an output file
430 when it issues any error whatsoever.
432 @item -o @var{output}
433 @kindex -o @var{output}
434 @cindex naming the output file
435 Use @var{output} as the name for the program produced by @code{ld}; if this
436 option is not specified, the name @file{a.out} is used by default. The
437 script command @code{OUTPUT} can also specify the output file name.
439 @item -R @var{filename}
440 @kindex -R @var{file}
441 @cindex symbol-only input
442 On some platforms, this option performs global optimizations
443 that become possible when the linker resolves addressing in the
444 program, such as relaxing address modes and synthesizing new
445 instructions in the output object file.
449 @cindex synthesizing linker
450 @cindex relaxing addressing modes
451 An option with machine dependent effects. Currently this option is only
452 supported on the H8/300.
454 @xref{H8/300,,@code{ld} and the H8/300}.
457 On some platforms, use option performs global optimizations that
458 become possible when the linker resolves addressing in the program, such
459 as relaxing address modes and synthesizing new instructions in the
462 On platforms where this is not supported, @samp{-relax} is accepted, but
467 @cindex relocatable output
469 Generate relocatable output---i.e., generate an output file that can in
470 turn serve as input to @code{ld}. This is often called @dfn{partial
471 linking}. As a side effect, in environments that support standard Unix
472 magic numbers, this option also sets the output file's magic number to
475 If this option is not specified, an absolute file is produced. When
476 linking C++ programs, this option @emph{will not} resolve references to
477 constructors; to do that, use @samp{-Ur}.
479 This option does the same as @code{-i}.
483 @cindex strip debugger symbols
484 Omit debugger symbol information (but not all symbols) from the output file.
488 @cindex strip all symbols
489 Omit all symbol information from the output file.
491 @item @{ @var{script} @}
492 @kindex @{ @var{script} @}
493 @cindex scripts on command line
494 You can, if you wish, include a script of linker commands directly in
495 the command line instead of referring to it via an input file. When the
496 character @samp{@{} occurs on the command line, the linker switches to
497 interpreting the command language until the end of the list of commands
498 is reached; the end is indicated with a closing brace @samp{@}}.
499 @code{ld} does not recognize other command-line options while parsing
500 the script. @xref{Commands}, for a description of the command language.
502 @item -Tbss @var{bssorg}
503 @kindex -Tbss @var{bssorg}
504 @itemx -Tdata @var{dataorg}
505 @kindex -Tdata @var{dataorg}
506 @itemx -Ttext @var{textorg}
507 @kindex -Ttext @var{textorg}
508 @cindex segment origins, cmd line
509 Use @var{org} as the starting address for---respectively---the
510 @code{bss}, @code{data}, or the @code{text} segment of the output file.
511 @var{org} must be a single hexadecimal integer;
512 for compatibility with other linkers, you may omit the leading
513 @samp{0x} usually associated with hexadecimal values.
515 @item -T @var{commandfile}
516 @itemx -T@var{commandfile}
517 @kindex -T @var{script}
519 Read link commands from the file
520 @var{commandfile}. These commands completely override @code{ld}'s
521 default link format (rather than adding to it); @var{commandfile} must
522 specify everything necessary to describe the target format.
524 If @var{commandfile} does not exist, @code{ld} looks for it in the directories
525 specified by any @samp{-L} options.
527 You may also include a script of link commands directly in the command
528 line by bracketing it between @samp{@{} and @samp{@}}.
533 @cindex input files, displaying
534 Print the names of the input files as @code{ld} processes them.
538 @cindex undefined symbol
539 Force @var{sym} to be entered in the output file as an undefined symbol.
540 Doing this may, for example, trigger linking of additional modules from
541 standard libraries. @samp{-u} may be repeated with different option
542 arguments to enter additional undefined symbols.
543 @c Nice idea, but no such command: This option is equivalent
544 @c to the @code{EXTERN} linker command.
549 For anything other than C++ programs, this option is equivalent to
550 @samp{-r}: it generates relocatable output---i.e., an output file that can in
551 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
552 @emph{will} resolve references to constructors, unlike @samp{-r}.
557 Display the version number for @code{ld} and list the supported emulations.
558 Print which input files can and can not be opened.
563 Display the version number for @code{ld}.
564 Print which input files can and can not be opened.
568 @cindex local symbols, deleting
569 @cindex L, deleting symbols beginning
570 If @samp{-s} or @samp{-S} is also specified, delete only local symbols
571 beginning with @samp{L}.
575 @cindex deleting local symbols
576 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
577 not just those beginning with @samp{L}.
580 @kindex -y@var{symbol}
581 @cindex symbol tracing
582 Print the name of each linked file in which @var{symbol} appears. This
583 option may be given any number of times. On many systems it is necessary
584 to prepend an underscore.
586 This option is useful when you have an undefined symbol in your link but
587 don't know where the reference is coming from.
592 @section Environment Variables
594 You can change the behavior of @code{ld} with the environment
595 variable @code{GNUTARGET}.
598 @cindex default input format
599 @code{GNUTARGET} determines the input-file object format if you don't
600 use @samp{-b} (or its synonym @samp{-format}). Its value should be one
601 of the BFD names for an input format (@pxref{BFD}). If there is no
602 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
603 of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
604 input format by examining binary input files; this method often
605 succeeds, but there are potential ambiguities, since there is no method
606 of ensuring that the magic number used to specify object-file formats is
607 unique. However, the configuration procedure for BFD on each system
608 places the conventional format for that system first in the search-list,
609 so ambiguities are resolved in favor of convention.
613 @chapter Command Language
615 @cindex command files
616 The command language provides explicit control over the link process,
617 allowing complete specification of the mapping between the linker's
618 input files and its output. It controls:
627 addresses of sections
629 placement of common blocks
632 You may supply a command file (also known as a link script) to the
633 linker either explicitly through the @samp{-T} option, or implicitly as
634 an ordinary file. If the linker opens a file which it cannot recognize
635 as a supported object or archive format, it tries to interpret the file
638 You can also include a script directly on the @code{ld} command line,
639 delimited by the characters @samp{@{} and @samp{@}}.
642 * Scripts:: Linker Scripts
643 * Expressions:: Expressions
644 * MEMORY:: MEMORY Command
645 * SECTIONS:: SECTIONS Command
646 * Entry Point:: The Entry Point
647 * Other Commands:: Other Commands
651 @section Linker Scripts
652 The @code{ld} command language is a collection of statements; some are
653 simple keywords setting a particular option, some are used to select and
654 group input files or name output files; and two statement
655 types have a fundamental and pervasive impact on the linking process.
657 @cindex fundamental script commands
658 @cindex commands, fundamental
659 @cindex output file layout
660 @cindex layout of output file
661 The most fundamental command of the @code{ld} command language is the
662 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
663 script must have a @code{SECTIONS} command: it specifies a
664 ``picture'' of the output file's layout, in varying degrees of detail.
665 No other command is required in all cases.
667 The @code{MEMORY} command complements @code{SECTIONS} by describing the
668 available memory in the target architecture. This command is optional;
669 if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
670 memory is available in a contiguous block for all output.
674 You may include comments in linker scripts just as in C: delimited
675 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
676 equivalent to whitespace.
680 @cindex expression syntax
682 Many useful commands involve arithmetic expressions. The syntax for
683 expressions in the command language is identical to that of C
684 expressions, with the following features:
687 All expressions evaluated as integers and
688 are of ``long'' or ``unsigned long'' type.
690 All constants are integers.
692 All of the C arithmetic operators are provided.
694 You may reference, define, and create global variables.
696 You may call special purpose built-in functions.
700 * Integers:: Integers
701 * Symbols:: Symbol Names
702 * Location Counter:: The Location Counter
703 * Operators:: Operators
704 * Evaluation:: Evaluation
705 * Assignment:: Assignment: Defining Symbols
706 * Built-ins:: Built-In Functions
711 @cindex integer notation
712 @cindex octal integers
713 An octal integer is @samp{0} followed by zero or more of the octal
714 digits (@samp{01234567}).
719 @cindex decimal integers
720 A decimal integer starts with a non-zero digit followed by zero or
721 more digits (@samp{0123456789}).
726 @cindex hexadecimal integers
728 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
729 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
734 @cindex negative integers
735 To write a negative integer, use
736 the prefix operator @samp{-}; @pxref{Operators}.
741 @cindex scaled integers
742 @cindex K and M integer suffixes
743 @cindex M and K integer suffixes
744 @cindex suffixes for integers
745 @cindex integer suffixes
746 Additionally the suffixes @code{K} and @code{M} may be used to scale a
750 @c END TEXI2ROFF-KILL
751 @code{1024} or @code{1024*1024}
755 ${\rm 1024}$ or ${\rm 1024}^2$
757 @c END TEXI2ROFF-KILL
758 respectively. For example, the following all refer to the same quantity:
767 @subsection Symbol Names
770 @cindex quoted symbol names
772 Unless quoted, symbol names start with a letter, underscore, point or
773 hyphen and may include any letters, underscores, digits, points,
774 and minus signs. Unquoted symbol names must not conflict with any
775 keywords. You can specify a symbol which contains odd characters or has
776 the same name as a keyword, by surrounding the symbol name in double quotes:
779 "with a space" = "also with a space" + 10;
782 @node Location Counter
783 @subsection The Location Counter
786 @cindex location counter
787 @cindex current output location
788 The special linker variable @dfn{dot} @samp{.} always contains the
789 current output location counter. Since the @code{.} always refers to
790 a location in an output section, it must always appear in an
791 expression within a @code{SECTIONS} command. The @code{.} symbol
792 may appear anywhere that an ordinary symbol is allowed in an
793 expression, but its assignments have a side effect. Assigning a value
794 to the @code{.} symbol will cause the location counter to be moved.
796 This may be used to create holes in the output section. The location
797 counter may never be moved backwards.
812 In the previous example, @code{file1} is located at the beginning of the
813 output section, then there is a 1000 byte gap. Then @code{file2}
814 appears, also with a 1000 byte gap following before @code{file3} is
815 loaded. The notation @samp{= 0x1234} specifies what data to write in
816 the gaps (@pxref{Section Options}).
819 @subsection Operators
820 @cindex Operators for arithmetic
821 @cindex arithmetic operators
822 @cindex precedence in expressions
823 The linker recognizes the standard C set of arithmetic operators, with
824 the standard bindings and precedence levels:
827 @c END TEXI2ROFF-KILL
829 precedence associativity Operators Notes
835 5 left == != > < <= >=
841 11 right &= += -= *= /= (2)
846 (2) @xref{Assignment}
851 %"lispnarrowing" is the extra indent used generally for @example
852 \hskip\lispnarrowing\vbox{\offinterlineskip
855 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
856 height2pt&\omit&&\omit&&\omit&\cr
857 &Precedence&& Associativity &&{\rm Operators}&\cr
858 height2pt&\omit&&\omit&&\omit&\cr
860 height2pt&\omit&&\omit&&\omit&\cr
862 % '176 is tilde, '~' in tt font
863 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
867 &5&&left&&== != > < <= >=&\cr
873 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
875 height2pt&\omit&&\omit&&\omit&\cr}
880 @obeylines@parskip=0pt@parindent=0pt
881 @dag@quad Prefix operators.
882 @ddag@quad @xref{Assignment}.
885 @c END TEXI2ROFF-KILL
888 @subsection Evaluation
890 @cindex lazy evaluation
891 @cindex expression evaluation order
892 The linker uses ``lazy evaluation'' for expressions; it only calculates
893 an expression when absolutely necessary. The linker needs the value of
894 the start address, and the lengths of memory regions, in order to do any
895 linking at all; these values are computed as soon as possible when the
896 linker reads in the command file. However, other values (such as symbol
897 values) are not known or needed until after storage allocation. Such
898 values are evaluated later, when other information (such as the sizes of
899 output sections) is available for use in the symbol assignment
903 @subsection Assignment: Defining Symbols
904 @cindex assignment in scripts
905 @cindex symbol definition, scripts
906 @cindex variables, defining
907 You may create global symbols, and assign values (addresses) to global
908 symbols, using any of the C assignment operators:
911 @item @var{symbol} = @var{expression} ;
912 @itemx @var{symbol} &= @var{expression} ;
913 @itemx @var{symbol} += @var{expression} ;
914 @itemx @var{symbol} -= @var{expression} ;
915 @itemx @var{symbol} *= @var{expression} ;
916 @itemx @var{symbol} /= @var{expression} ;
919 Two things distinguish assignment from other operators in @code{ld}
923 Assignment may only be used at the root of an expression;
924 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
929 You must place a trailing semicolon (``@key{;}'') at the end of an
930 assignment statement.
933 Assignment statements may appear:
936 as commands in their own right in an @code{ld} script; or
938 as independent statements within a @code{SECTIONS} command; or
940 as part of the contents of a section definition in a
941 @code{SECTIONS} command.
944 The first two cases are equivalent in effect---both define a symbol with
945 an absolute address. The last case defines a symbol whose address is
946 relative to a particular section (@pxref{SECTIONS}).
948 @cindex absolute and relocatable symbols
949 @cindex relocatable and absolute symbols
950 @cindex symbols, relocatable and absolute
951 When a linker expression is evaluated and assigned to a variable, it is
952 given either an absolute or a relocatable type. An absolute expression
953 type is one in which the symbol contains the value that it will have in
954 the output file, a relocatable expression type is one in which the
955 value is expressed as a fixed offset from the base of a section.
957 The type of the expression is controlled by its position in the script
958 file. A symbol assigned within a section definition is created relative
959 to the base of the section; a symbol assigned in any other place is
960 created as an absolute symbol. Since a symbol created within a
961 section definition is relative to the base of the section, it
962 will remain relocatable if relocatable output is requested. A symbol
963 may be created with an absolute value even when assigned to within a
964 section definition by using the absolute assignment function
965 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
966 is the last byte of an output section named @code{.data}:
972 _edata = ABSOLUTE(.) ;
977 The linker tries to put off the evaluation of an assignment until all
978 the terms in the source expression are known (@pxref{Evaluation}). For
979 instance, the sizes of sections cannot be known until after allocation,
980 so assignments dependent upon these are not performed until after
981 allocation. Some expressions, such as those depending upon the location
982 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
983 result of an expression is required, but the value is not available,
984 then an error results. For example, a script like the following
987 text 9+this_isnt_constant :
992 @kindex Non constant expression
994 will cause the error message ``@code{Non constant expression for initial
998 @subsection Built-In Functions
999 @cindex functions in expression language
1000 The command language includes a number of built-in
1001 functions for use in link script expressions.
1003 @item ABSOLUTE(@var{exp})
1004 @kindex ABSOLUTE(@var{exp})
1005 @cindex expression, absolute
1006 Return the absolute (non-relocatable, as opposed to non-negative) value
1007 of the expression @var{exp}. Primarily useful to assign an absolute
1008 value to a symbol within a section definition, where symbol values are
1009 normally section-relative.
1011 @item ADDR(@var{section})
1012 @kindex ADDR(@var{section})
1013 @cindex section address
1014 Return the absolute address of the named @var{section}. Your script must
1015 previously have defined the location of that section. In the following
1016 example, @code{symbol_1} and @code{symbol_2} are assigned identical
1022 start_of_output_1 = ABSOLUTE(.);
1027 symbol_1 = ADDR(.output1);
1028 symbol_2 = start_of_output_1;
1033 @item ALIGN(@var{exp})
1034 @kindex ALIGN(@var{exp})
1035 @cindex rounding up location counter
1036 Return the result of the current location counter (@code{.}) aligned to
1037 the next @var{exp} boundary. @var{exp} must be an expression whose
1038 value is a power of two. This is equivalent to
1040 (. + @var{exp} - 1) & ~(@var{exp} - 1)
1043 @code{ALIGN} doesn't change the value of the location counter---it just
1044 does arithmetic on it. As an example, to align the output @code{.data}
1045 section to the next @code{0x2000} byte boundary after the preceding
1046 section and to set a variable within the section to the next
1047 @code{0x8000} boundary after the input sections:
1050 .data ALIGN(0x2000): @{
1052 variable = ALIGN(0x8000);
1057 The first use of @code{ALIGN} in this example specifies the location of
1058 a section because it is used as the optional @var{start} attribute of a
1059 section definition (@pxref{Section Options}). The second use simply
1060 defines the value of a variable.
1062 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1064 @item DEFINED(@var{symbol})
1065 @kindex DEFINED(@var{symbol})
1066 @cindex symbol defaults
1067 Return 1 if @var{symbol} is in the linker global symbol table and is
1068 defined, otherwise return 0. You can use this function to provide default
1069 values for symbols. For example, the following command-file fragment shows how
1070 to set a global symbol @code{begin} to the first location in the
1071 @code{.text} section---but if a symbol called @code{begin} already
1072 existed, its value is preserved:
1076 begin = DEFINED(begin) ? begin : . ;
1082 @item NEXT(@var{exp})
1083 @kindex NEXT(@var{exp})
1084 @cindex unallocated address, next
1085 Return the next unallocated address that is a multiple of @var{exp}.
1086 This function is closely related to @code{ALIGN(@var{exp})}; unless you
1087 use the @code{MEMORY} command to define discontinuous memory for the
1088 output file, the two functions are equivalent.
1090 @item SIZEOF(@var{section})
1091 @kindex SIZEOF(@var{section})
1092 @cindex section size
1093 Return the size in bytes of the named @var{section}, if that section has
1094 been allocated. In the following example, @code{symbol_1} and
1095 @code{symbol_2} are assigned identical values:
1096 @c What does it return if the section hasn't been allocated? 0?
1104 symbol_1 = .end - .start ;
1105 symbol_2 = SIZEOF(.output);
1110 @item SIZEOF_HEADERS
1111 @kindex SIZEOF_HEADERS
1113 @itemx sizeof_headers
1114 @kindex sizeof_headers
1115 Return the size in bytes of the output file's headers. You can use this number
1116 as the start address of the first section, if you choose, to facilitate
1122 @section MEMORY Command
1124 @cindex regions of memory
1125 @cindex discontinuous memory
1126 @cindex allocating memory
1127 The linker's default configuration permits allocation of all available memory.
1128 You can override this configuration by using the @code{MEMORY} command. The
1129 @code{MEMORY} command describes the location and size of blocks of
1130 memory in the target. By using it carefully, you can describe which
1131 memory regions may be used by the linker, and which memory regions it
1132 must avoid. The linker does not shuffle sections to fit into the
1133 available regions, but does move the requested sections into the correct
1134 regions and issue errors when the regions become too full.
1136 The command files may contain at most one use of the @code{MEMORY}
1137 command; however, you can define as many blocks of memory within it as
1138 you wish. The syntax is:
1143 @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
1149 @cindex naming memory regions
1150 is a name used internally by the linker to refer to the region. Any
1151 symbol name may be used. The region names are stored in a separate
1152 name space, and will not conflict with symbols, file names or section
1153 names. Use distinct names to specify multiple regions.
1155 @cindex memory region attributes
1156 is an optional list of attributes, permitted for compatibility with the
1157 AT&T linker but not used by @code{ld} beyond checking that the
1158 attribute list is valid. Valid attribute lists must be made up of the
1159 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1160 omit the parentheses around it as well.
1165 is the start address of the region in physical memory. It is
1166 an expression that must evaluate to a constant before
1167 memory allocation is performed. The keyword @code{ORIGIN} may be
1168 abbreviated to @code{org} or @code{o}.
1173 is the size in bytes of the region (an expression).
1174 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1177 For example, to specify that memory has two regions available for
1178 allocation---one starting at 0 for 256 kilobytes, and the other
1179 starting at @code{0x40000000} for four megabytes:
1184 rom : ORIGIN = 0, LENGTH = 256K
1185 ram : org = 0x40000000, l = 4M
1189 Once you have defined a region of memory named @var{mem}, you can direct
1190 specific output sections there by using a command ending in
1191 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1192 Options}). If the combined output sections directed to a region are too
1193 big for the region, the linker will issue an error message.
1196 @section SECTIONS Command
1198 The @code{SECTIONS} command controls exactly where input sections are
1199 placed into output sections, their order and to which output sections
1202 You may use at most one @code{SECTIONS} command in a commands file,
1203 but you can have as many statements within it as you wish. Statements
1204 within the @code{SECTIONS} command can do one of three things:
1207 define the entry point;
1209 assign a value to a symbol;
1211 describe the placement of a named output section, and what input
1212 sections make it up.
1215 The first two possibilities---defining the entry point, and defining
1216 symbols---can also be done outside the @code{SECTIONS} command:
1217 @pxref{Entry Point}, @pxref{Assignment}. They are permitted here as
1218 well for your convenience in reading the script, so that symbols or the
1219 entry point can be defined at meaningful points in your output-file
1222 When no @code{SECTIONS} command is specified, the default action
1223 of the linker is to place each input section into an identically named
1224 output section in the order that the sections are first encountered in
1225 the input files; if all input sections are present in the first file,
1226 for example, the order of sections in the output file will match the
1227 order in the first input file.
1230 * Section Definition:: Section Definitions
1231 * Section Contents:: Section Contents
1232 * Section Options:: Optional Section Attributes
1235 @node Section Definition
1236 @subsection Section Definitions
1237 @cindex section definition
1238 The most frequently used statement in the @code{SECTIONS} command is
1239 the @dfn{section definition}, which you can use to specify the
1240 properties of an output section: its location, alignment, contents,
1241 fill pattern, and target memory region. Most of
1242 these specifications are optional; the simplest form of a section
1251 @cindex naming output sections
1253 @var{secname} is the name of the output section, and @var{contents} a
1254 specification of what goes there---for example, a list of input files or
1255 sections of input files. As you might assume, the whitespace shown is
1256 optional. You do need the colon @samp{:} and the braces @samp{@{@}},
1259 @var{secname} must meet the constraints of your output format. In
1260 formats which only support a limited number of sections, such as
1261 @code{a.out}, the name must be one of the names supported by the format
1262 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1263 @code{.bss}). If the output format supports any number of sections, but
1264 with numbers and not names (as is the case for Oasys), the name should be
1265 supplied as a quoted numeric string. A section name may consist of any
1266 sequence characters, but any name which does not conform to the standard
1267 @code{ld} symbol name syntax must be quoted.
1268 @xref{Symbols, , Symbol Names}.
1270 @node Section Contents
1271 @subsection Section Contents
1272 @cindex contents of a section
1273 In a section definition, you can specify the contents of an output section by
1274 listing particular object files, by listing particular input-file
1275 sections, or by a combination of the two. You can also place arbitrary
1276 data in the section, and define symbols relative to the beginning of the
1279 The @var{contents} of a section definition may include any of the
1280 following kinds of statement. You can include as many of these as you
1281 like in a single section definition, separated from one another by
1285 @item @var{filename}
1286 @kindex @var{filename}
1287 @cindex input files, section defn
1288 @cindex files, including in output sections
1289 You may simply name a particular input file to be placed in the current
1290 output section; @emph{all} sections from that file are placed in the
1291 current section definition. To specify a list of particular files by
1294 .data : @{ afile.o bfile.o cfile.o @}
1297 The example also illustrates that multiple statements can be included in
1298 the contents of a section definition, since each file name is a separate
1301 If the file name has already been mentioned in another section
1302 definition, with an explicit section name list, then only those sections
1303 which have not yet been allocated are used.
1305 @item @var{filename}( @var{section} )
1306 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1307 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1308 @kindex @var{filename}(@var{section})
1309 @cindex files and sections, section defn
1310 You can name one or more sections from your input files, for
1311 insertion in the current output section. If you wish to specify a list
1312 of input-file sections inside the parentheses, you may separate the
1313 section names by either commas or whitespace.
1315 @item * (@var{section})
1316 @itemx * (@var{section}, @var{section}, @dots{})
1317 @itemx * (@var{section} @var{section} @dots{}
1318 @cindex input sections to output section
1319 @kindex *(@var{section})
1320 Instead of explicitly naming particular input files in a link control
1321 script, you can refer to @emph{all} files from the @code{ld} command
1322 line: use @samp{*} instead of a particular file name before the
1323 parenthesized input-file section list.
1325 For example, to copy sections @code{1} through @code{4} from an Oasys file
1326 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1327 and @code{14} into the @code{.data} section:
1340 If you have already explicitly included some files by name, @samp{*}
1341 refers to all @emph{remaining} files---those whose places in the output
1342 file have not yet been defined.
1344 @item [ @var{section} ]
1345 @itemx [ @var{section}, @var{section}, @dots{} ]
1346 @itemx [ @var{section} @var{section} @dots{} ]
1347 @kindex [ @var{sections} ]
1348 This is an alternate notation to specify named sections from all
1349 unallocated input files; its effect is exactly the same as that of
1350 @samp{* (@var{section}@dots{})}
1352 @item @var{filename}@code{( COMMON )}
1355 @cindex uninitialized data
1356 @cindex commons in output
1357 Specify where in your output file to place uninitialized data
1358 with this notation. @code{*(COMMON)} by itself refers to all
1359 uninitialized data from all input files (so far as it is not yet
1360 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1361 from a particular file. Both are special cases of the general
1362 mechanisms for specifying where to place input-file sections:
1363 @code{ld} permits you to refer to uninitialized data as if it
1364 were in an input-file section named @code{COMMON}, regardless of the
1365 input file's format.
1368 For example, the following command script arranges the output file into
1369 three consecutive sections, named @code{.text}, @code{.data}, and
1370 @code{.bss}, taking the input for each from the correspondingly named
1371 sections of all the input files:
1374 .text : @{ *(.text) @}
1375 .data : @{ *(.data) @}
1376 .bss : @{ *(.bss) *(COMMON) @}
1380 The following example reads all of the sections from file @code{all.o}
1381 and places them at the start of output section @code{outputa} which
1382 starts at location @code{0x10000}. All of section @code{.input1} from
1383 file @code{foo.o} follows immediately, in the same output section. All
1384 of section @code{.input2} from @code{foo.o} goes into output section
1385 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1386 All of the remaining @code{.input1} and @code{.input2} sections from any
1387 files are written to output section @code{outputc}.
1409 There are still more kinds of statements permitted in the contents of
1410 output section definitions. The foregoing statements permitted you to
1411 arrange, in your output file, data originating from your input files.
1412 You can also place data directly in an output section from the link
1413 command script. Most of these additional statements involve
1414 expressions; @pxref{Expressions}. Although these statements are shown
1415 separately here for ease of presentation, no such segregation is needed
1416 within a section definition in the @code{SECTIONS} command; you can
1417 intermix them freely with any of the statements we've just described.
1420 @item CREATE_OBJECT_SYMBOLS
1421 @kindex CREATE_OBJECT_SYMBOLS
1422 @cindex input filename symbols
1423 @cindex filename symbols
1424 Create a symbol for each input file
1425 in the current section, set to the address of the first byte of
1426 data written from the input file. For instance, with @code{a.out}
1427 files it is conventional to have a symbol for each input file. You can
1428 accomplish this by defining the output @code{.text} section as follows:
1433 CREATE_OBJECT_SYMBOLS
1435 _etext = ALIGN(0x2000);
1441 If @code{objsym} is a file containing this script, and @code{a.o},
1442 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1443 contents like the following---
1453 @samp{ld -M sample a.o b.o c.o d.o} would create a map like this,
1454 containing symbols matching the object file names:
1456 00000000 A __DYNAMIC
1459 00002020 T _afunction
1462 00002038 T _bfunction
1465 00002050 T _cfunction
1468 00002068 T _dfunction
1478 @item @var{symbol} = @var{expression} ;
1479 @kindex @var{symbol} = @var{expression} ;
1480 @itemx @var{symbol} @var{f}= @var{expression} ;
1481 @kindex @var{symbol} @var{f}= @var{expression} ;
1482 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1483 refers to any of the operators @code{&= += -= *= /=} which combine
1484 arithmetic and assignment.
1486 @cindex assignment, in section defn
1487 When you assign a value to a symbol within a particular section
1488 definition, the value is relative to the beginning of the section
1489 (@pxref{Assignment}). If you write
1494 .data : @{ @dots{} rel = 14 ; @dots{} @}
1495 abs2 = 14 + ADDR(.data);
1499 @c FIXME: Try above example!
1501 @code{abs} and @code{rel} do not have the same value; @code{rel} has the
1502 same value as @code{abs2}.
1504 @item BYTE(@var{expression})
1505 @kindex BYTE(@var{expression})
1506 @itemx SHORT(@var{expression})
1507 @kindex SHORT(@var{expression})
1508 @itemx LONG(@var{expression})
1509 @kindex LONG(@var{expression})
1510 @cindex direct output
1511 By including one of these three statements in a section definition, you
1512 can explicitly place one, two, or four bytes (respectively) at the
1513 current address of that section.
1515 @ifclear SingleFormat
1516 Multiple-byte quantities are represented in whatever byte order is
1517 appropriate for the output file format (@pxref{BFD}).
1520 @item FILL(@var{expression})
1521 @kindex FILL(@var{expression})
1522 @cindex holes, filling
1523 @cindex unspecified memory
1524 Specifies the ``fill pattern'' for the current section. Any otherwise
1525 unspecified regions of memory within the section (for example, regions
1526 you skip over by assigning a new value to the location counter @samp{.})
1527 are filled with the two least significant bytes from the
1528 @var{expression} argument. A @code{FILL} statement covers memory
1529 locations @emph{after} the point it occurs in the section definition; by
1530 including more than one @code{FILL} statement, you can have different
1531 fill patterns in different parts of an output section.
1534 @node Section Options
1535 @subsection Optional Section Attributes
1536 @cindex section defn, full syntax
1537 Here is the full syntax of a section definition, including all the
1543 @var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : @{ @var{contents} @} =@var{fill} >@var{region}
1548 @var{secname} and @var{contents} are required. @xref{Section
1549 Definition}, and @pxref{Section Contents} for details on @var{contents}.
1550 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1551 @code{(NOLOAD)} @code{=@var{fill}}, and @code{>@var{region}}---are all
1556 @cindex start address, section
1557 @cindex section start
1558 @cindex section address
1559 You can force the output section to be loaded at a specified address by
1560 specifying @var{start} immediately following the section name.
1561 @var{start} can be represented as any expression. The following
1562 example generates section @var{output} at location
1567 output 0x40000000: @{
1574 @item BLOCK(@var{align})
1575 @kindex BLOCK(@var{align})
1576 @cindex section alignment
1577 @cindex aligning sections
1578 You can include @code{BLOCK()} specification to advance
1579 the location counter @code{.} prior to the beginning of the section, so
1580 that the section will begin at the specified alignment. @var{align} is
1585 @cindex prevent unnecessary loading
1586 Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
1587 each time it is accessed. For example, in the script sample below, the
1588 @code{ROM} segment is addressed at memory location @samp{0} and does not
1589 need to be loaded into each object file:
1592 ROM 0 (NOLOAD) : @{ @dots{} @}
1599 @cindex section fill pattern
1600 @cindex fill pattern, entire section
1602 @code{=@var{fill}} in a section definition specifies the initial fill
1603 value for that section.
1604 You may use any expression to specify @var{fill}.
1605 Any unallocated holes in the current output
1606 section when written to the output file will be filled with the two
1607 least significant bytes of the value, repeated as necessary. You can
1608 also change the fill value with a @code{FILL} statement in the
1609 @var{contents} of a section definition.
1612 @kindex >@var{region}
1613 @cindex section, assigning to memory region
1614 @cindex memory regions and sections
1615 Assign this section to a previously defined region of memory.
1621 @section The Entry Point
1622 @kindex ENTRY(@var{symbol})
1623 @cindex start of execution
1624 @cindex first instruction
1625 The linker command language includes a command specifically for
1626 defining the first executable instruction in an output file (its
1627 @dfn{entry point}). Its argument is a symbol name:
1632 Like symbol assignments, the @code{ENTRY} command may be placed either
1633 as an independent command in the command file, or among the section
1634 definitions within the @code{SECTIONS} command---whatever makes the most
1635 sense for your layout.
1637 @cindex entry point, defaults
1638 @code{ENTRY} is only one of several ways of choosing the entry point.
1639 You may indicate it in any of the following ways (shown in descending
1640 order of priority: methods higher in the list override methods lower down).
1643 the @samp{-e} @var{entry} command-line option;
1645 the @code{ENTRY(@var{symbol}} command in a linker control script;
1647 the value of the symbol @code{start}, if present;
1649 the value of the symbol @code{_main}, if present;
1651 the address of the first byte of the @code{.text} section, if present;
1653 The address @code{0}.
1656 For example, you can use these rules to generate an entry point with an
1657 assignment statement: if no symbol @code{start} is defined within your
1658 input files, you can simply define it, assigning it an appropriate
1665 The example shows an absolute address, but you can use any expression.
1666 For example, if your input object files use some other symbol-name
1667 convention for the entry point, you can just assign the value of
1668 whatever symbol contains the start address to @code{start}:
1670 start = other_symbol ;
1673 @node Other Commands
1674 @section Other Commands
1675 The command language includes a number of other commands that you can
1676 use for specialized purposes. They are similar in purpose to
1677 command-line options.
1684 These keywords were used in some older linkers to request a particular
1685 math subroutine library. @code{ld} doesn't use the keywords, assuming
1686 instead that any necessary subroutines are in libraries specified using
1687 the general mechanisms for linking to archives; but to permit the use of
1688 scripts that were written for the older linkers, the keywords
1689 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1691 @item FORCE_COMMON_ALLOCATION
1692 @kindex FORCE_COMMON_ALLOCATION
1693 @cindex common allocation
1694 This command has the same effect as the @samp{-d} command-line option:
1695 to make @code{ld} assign space to common symbols even if a relocatable
1696 output file is specified (@samp{-r}).
1698 @item INPUT ( @var{file}, @var{file}, @dots{} )
1699 @kindex INPUT ( @var{files} )
1700 @itemx INPUT ( @var{file} @var{file} @dots{} )
1701 @cindex binary input files
1702 Use this command to include binary input files in the link, without
1703 including them in a particular section definition. Files specified this
1704 way are treated identically to object files listed on the command line.
1707 @item MAP ( @var{name} )
1708 @kindex MAP ( @var{name} )
1709 @c MAP(...) appears to look for an F in the arg, ignoring all other
1710 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1711 @c checks map_option_f. Apparently a stub for the future...
1714 @item OUTPUT ( @var{filename} )
1715 @kindex OUTPUT ( @var{filename} )
1716 @cindex naming the output file
1717 Use this command to name the link output file @var{filename}. The
1718 effect of @code{OUTPUT(@var{filename})} is identical to the effect of
1719 @w{@samp{-o @var{filename}}}, and whichever is encountered last will
1720 control the name actually used to name the output file. In particular,
1721 you can use this command to supply a default output-file name other than
1724 @ifclear SingleFormat
1725 @item OUTPUT_ARCH ( @var{bfdname} )
1726 @kindex OUTPUT_ARCH ( @var{bfdname} )
1727 @cindex machine architecture, output
1728 Specify a particular output machine architecture, with one of the names
1729 used by the BFD back-end routines (@pxref{BFD}). This command is often
1730 unnecessary; the architecture is most often set implicitly by either the
1731 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1734 @item OUTPUT_FORMAT ( @var{bfdname} )
1735 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1736 @cindex format, output file
1737 Specify a particular output format, with one of the names used by the
1738 BFD back-end routines (@pxref{BFD}). This selection will only affect
1739 the output file; the related command @code{TARGET} affects primarily
1743 @item SEARCH_DIR ( @var{path} )
1744 @kindex SEARCH_DIR ( @var{path} )
1745 @cindex path for libraries
1746 @cindex search path, libraries
1747 Add @var{path} to the list of paths where @code{ld} looks for
1748 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1749 effect as @samp{-L@var{path}} on the command line.
1751 @item STARTUP ( @var{filename} )
1752 @kindex STARTUP ( @var{filename} )
1753 @cindex first input file
1754 Ensure that @var{filename} is the first input file used in the link
1757 @ifclear SingleFormat
1758 @item TARGET ( @var{format} )
1759 @cindex input file format
1760 @kindex TARGET ( @var{format} )
1761 Change the input-file object code format (like the command-line option
1762 @samp{-b} or its synonym @samp{-format}). The argument @var{format} is
1763 one of the strings used by BFD to name binary formats. In the current
1764 @code{ld} implementation, if @code{TARGET} is specified but
1765 @code{OUTPUT_FORMAT} is not, the last @code{TARGET} argument is also
1766 used as the default format for the @code{ld} output file.
1770 If you don't use the @code{TARGET} command, @code{ld} uses the value of
1771 the environment variable @code{GNUTARGET}, if available, to select the
1772 output file format. If that variable is also absent, @code{ld} uses
1773 the default format configured for your machine in the BFD libraries.
1778 @node Machine Dependent
1779 @chapter Machine Dependent Features
1781 @cindex machine dependencies
1782 @code{ld} has additional features on some platforms; the following
1783 sections describe them. Machines where @code{ld} has no additional
1784 functionality are not listed.
1787 * H8/300:: @code{ld} and the H8/300
1788 * i960:: @code{ld} and the Intel 960 family
1792 @c FIXME! This could use @up/@down, but there seems to be a conflict
1793 @c between those and node-defaulting.
1799 @section @code{ld} and the H8/300
1801 @cindex H8/300 support
1802 For the H8/300, @code{ld} can perform these global optimizations when
1803 you specify the @samp{-relax} command-line option.
1806 @item relaxing address modes
1807 @cindex relaxing on H8/300
1808 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
1809 targets are within eight bits, and turns them into eight-bit
1810 program-counter relative @code{bsr} and @code{bra} instructions,
1813 @item synthesizing instructions
1814 @cindex synthesizing on H8/300
1815 @c FIXME: specifically mov.b, or any mov instructions really?
1816 @code{ld} finds all @code{mov.b} instructions which use the
1817 sixteen-bit absolute address form, but refer to the top
1818 page of memory, and changes them to use the eight-bit address form.
1819 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1820 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1821 top page of memory).
1833 @section @code{ld} and the Intel 960 family
1835 @cindex i960 support
1837 You can use the @samp{-A@var{architecture}} command line option to
1838 specify one of the two-letter names identifying members of the 960
1839 family; the option specifies the desired output target, and warns of any
1840 incompatible instructions in the input files. It also modifies the
1841 linker's search strategy for archive libraries, to support the use of
1842 libraries specific to each particular architecture, by including in the
1843 search loop names suffixed with the string identifying the architecture.
1845 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
1846 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1847 paths, and in any paths you specify with @samp{-L}) for a library with
1858 The first two possibilities would be considered in any event; the last
1859 two are due to the use of @w{@samp{-ACA}}.
1861 You can meaningfully use @samp{-A} more than once on a command line, since
1862 the 960 architecture family allows combination of target architectures; each
1863 use will add another pair of name variants to search for when @w{@samp{-l}}
1864 specifies a library.
1870 @ifclear SingleFormat
1875 @cindex object file management
1876 The linker accesses object and archive files using the BFD libraries.
1877 These libraries allow the linker to use the same routines to operate on
1878 object files whatever the object file format. A different object file
1879 format can be supported simply by creating a new BFD back end and adding
1880 it to the library. You can use @code{objdump -i}
1881 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
1882 list all the formats available for each architecture under BFD. This
1883 was the list of formats, and of architectures supported for each format,
1884 as of the time this manual was prepared:
1885 @cindex formats available
1886 @cindex architectures available
1888 BFD header file version 0.18
1890 (header big endian, data big endian)
1896 (header big endian, data big endian)
1902 (header big endian, data little endian)
1905 (header little endian, data little endian)
1908 (header big endian, data big endian)
1911 (header big endian, data big endian)
1914 (header little endian, data little endian)
1917 (header big endian, data little endian)
1920 (header little endian, data little endian)
1923 (header big endian, data big endian)
1926 (header big endian, data big endian)
1929 (header big endian, data big endian)
1932 (header little endian, data little endian)
1935 (header big endian, data big endian)
1947 (header little endian, data little endian)
1959 (header big endian, data big endian)
1971 (header big endian, data big endian)
1984 @cindex BFD requirements
1985 @cindex requirements for BFD
1986 As with most implementations, BFD is a compromise between
1987 several conflicting requirements. The major factor influencing
1988 BFD design was efficiency: any time used converting between
1989 formats is time which would not have been spent had BFD not
1990 been involved. This is partly offset by abstraction payback; since
1991 BFD simplifies applications and back ends, more time and care
1992 may be spent optimizing algorithms for a greater speed.
1994 One minor artifact of the BFD solution which you should bear in
1995 mind is the potential for information loss. There are two places where
1996 useful information can be lost using the BFD mechanism: during
1997 conversion and during output. @xref{BFD information loss}.
2000 * BFD outline:: How it works: an outline of BFD
2001 * BFD information loss:: Information Loss
2002 * Mechanism:: Mechanism
2006 @section How it works: an outline of BFD
2007 @cindex opening object files
2008 When an object file is opened, BFD subroutines automatically
2009 determine the format of the input object file, and build a descriptor in
2010 memory with pointers to routines that will be used to access elements of
2011 the object file's data structures.
2013 As different information from the the object files is required,
2014 BFD reads from different sections of the file and processes them.
2015 For example, a very common operation for the linker is processing symbol
2016 tables. Each BFD back end provides a routine for converting
2017 between the object file's representation of symbols and an internal
2018 canonical format. When the linker asks for the symbol table of an object
2019 file, it calls through the memory pointer to the BFD
2020 back end routine which reads and converts the table into a canonical
2021 form. The linker then operates upon the common form. When the link is
2022 finished and the linker writes the symbol table of the output file,
2023 another BFD back end routine is called which takes the newly
2024 created symbol table and converts it into the chosen output format.
2026 @node BFD information loss
2027 @section Information Loss
2028 @emph{Information can be lost during output.} The output formats
2029 supported by BFD do not provide identical facilities, and
2030 information which may be described in one form has nowhere to go in
2031 another format. One example of this is alignment information in
2032 @code{b.out}. There is nowhere in an @code{a.out} format file to store
2033 alignment information on the contained data, so when a file is linked
2034 from @code{b.out} and an @code{a.out} image is produced, alignment
2035 information will not propagate to the output file. (The linker will
2036 still use the alignment information internally, so the link is performed
2039 Another example is COFF section names. COFF files may contain an
2040 unlimited number of sections, each one with a textual section name. If
2041 the target of the link is a format which does not have many sections (e.g.,
2042 @code{a.out}) or has sections without names (e.g., the Oasys format) the
2043 link cannot be done simply. You can circumvent this problem by
2044 describing the desired input-to-output section mapping with the command
2047 @emph{Information can be lost during canonicalization.} The BFD
2048 internal canonical form of the external formats is not exhaustive; there
2049 are structures in input formats for which there is no direct
2050 representation internally. This means that the BFD back ends
2051 cannot maintain all possible data richness through the transformation
2052 between external to internal and back to external formats.
2054 This limitation is only a problem when using the linker to read one
2055 format and write another. Each BFD back end is responsible for
2056 maintaining as much data as possible, and the internal BFD
2057 canonical form has structures which are opaque to the BFD core,
2058 and exported only to the back ends. When a file is read in one format,
2059 the canonical form is generated for BFD and the linker. At the
2060 same time, the back end saves away any information which would otherwise
2061 be lost. If the data is then written back in the same format, the back
2062 end routine will be able to use the canonical form provided by the
2063 BFD core as well as the information it prepared earlier. Since
2064 there is a great deal of commonality between back ends,
2065 there is no information lost when
2066 linking big endian COFF to little endian COFF, or from @code{a.out} to
2067 @code{b.out}. When a mixture of formats is linked, the information is
2068 only lost from the files whose format differs from the destination.
2072 The greatest potential for loss of information occurs when there is the least
2073 overlap between the information provided by the source format, that
2074 stored by the canonical format, and that needed by the
2075 destination format. A brief description of the canonical form may help
2076 you understand which kinds of data you can count on preserving across
2078 @cindex BFD canonical format
2079 @cindex internal object-file format
2083 Information on target machine architecture, particular implementation,
2084 and format type are stored on a per-file basis. Other information
2085 includes a demand pagable bit and a write protected bit.
2086 Information like Unix magic numbers is not stored here---only the magic
2087 numbers' meaning, so a @code{ZMAGIC} file would have both the demand pagable
2088 bit and the write protected text bit set.
2090 The byte order of the target is stored on a per-file basis, so that big-
2091 and little-endian object files may be linked with one another.
2094 Each section in the input file contains the name of the section, the
2095 original address in the object file, various options, size and alignment
2096 information and pointers into other BFD data structures.
2099 Each symbol contains a pointer to the object file which originally
2100 defined it, its name, its value, and various option bits. When a
2101 BFD back end reads in a symbol table, the back end relocates all
2102 symbols to make them relative to the base of the section where they were
2103 defined. Doing this ensures that each symbol points to its containing
2104 section. Each symbol also has a varying amount of hidden
2105 private data for the BFD back end. Since the symbol points to the
2106 original file, the private data format for that symbol is accessible.
2107 @code{ld} can operate on a collection of symbols of wildly different
2108 formats without problems.
2110 Normal global and simple local symbols are maintained on output, so an
2111 output file (no matter its format) will retain symbols pointing to
2112 functions and to global, static, and common variables. Some symbol
2113 information is not worth retaining; in @code{a.out}, type information is
2114 stored in the symbol table as long symbol names. This information would
2115 be useless to most COFF debuggers and may be thrown away with
2116 appropriate command line switches. (The GNU debugger @code{gdb} does
2117 support @code{a.out} style debugging information in COFF).
2119 There is one word of type information within the symbol, so if the
2120 format supports symbol type information within symbols (for example, COFF,
2121 IEEE, Oasys) and the type is simple enough to fit within one word
2122 (nearly everything but aggregates), the information will be preserved.
2124 @item relocation level
2125 Each canonical BFD relocation record contains a pointer to the symbol to
2126 relocate to, the offset of the data to relocate, the section the data
2127 is in, and a pointer to a relocation type descriptor. Relocation is
2128 performed by passing messages through the relocation type
2129 descriptor and the symbol pointer. Therefore, relocations can be performed
2130 on output data using a relocation method that is only available in one of the
2131 input formats. For instance, Oasys provides a byte relocation format.
2132 A relocation record requesting this relocation type would point
2133 indirectly to a routine to perform this, so the relocation may be
2134 performed on a byte being written to a COFF file, even though 68k COFF
2135 has no such relocation type.
2136 @c FIXME why specific reference to 68K above?
2139 Object formats can contain, for debugging purposes, some form of mapping
2140 between symbols, source line numbers, and addresses in the output file.
2141 These addresses have to be relocated along with the symbol information.
2142 Each symbol with an associated list of line number records points to the
2143 first record of the list. The head of a line number list consists of a
2144 pointer to the symbol, which allows finding out the address of the
2145 function whose line number is being described. The rest of the list is
2146 made up of pairs: offsets into the section and line numbers. Any format
2147 which can simply derive this information can pass it successfully
2148 between formats (COFF, IEEE and Oasys).
2153 @appendix MRI Compatible Script Files
2154 @cindex MRI compatibility
2155 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
2156 linker, @code{ld} can use MRI compatible linker scripts as an
2157 alternative to the more general-purpose linker scripting language
2158 described in @ref{Commands,,Command Language}. MRI compatible linker
2159 scripts have a much simpler command set than the scripting language
2160 otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
2161 commonly used MRI linker commands; these commands are described here.
2163 You can specify a file containing an MRI-compatible script using the
2164 @samp{-c} command-line option.
2166 Each command in an MRI-compatible script occupies its own line; each
2167 command line starts with the keyword that identifies the command (though
2168 blank lines are also allowed for punctuation). If a line of an
2169 MRI-compatible script begins with an unrecognized keyword, @code{ld}
2170 issues a warning message, but continues processing the script.
2172 Lines beginning with @samp{*} are comments.
2174 You can write these commands using all upper-case letters, or all
2175 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
2176 The following list shows only the upper-case form of each command.
2179 @item ABSOLUTE @var{secname}
2180 @item ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
2181 @cindex @code{ABSOLUTE} (MRI)
2182 Normally, @code{ld} includes in the output file all sections from all
2183 the input files. However, in an MRI-compatible script, you can use the
2184 @code{ABSOLUTE} command to restrict the sections that will be present in
2185 your output program. If the @code{ABSOLUTE} command is used at all in a
2186 script, then only the sections named explicitly in @code{ABSOLUTE}
2187 commands will appear in the linker output. You can still use other
2188 input sections (whatever you select on the command line, or using
2189 @code{LOAD}) to resolve addresses in the output file.
2191 @item ALIAS @var{out-secname}, @var{in-secname}
2192 @cindex @code{ALIAS} (MRI)
2193 Use this command to place the data from input section @var{in-secname}
2194 in a section called @var{out-secname} in the linker output file.
2196 @var{in-secname} may be an integer.
2198 @item BASE @var{expression}
2199 @cindex @code{BASE} (MRI)
2200 Use the value of @var{expression} as the lowest address (other than
2201 absolute addresses) in the output file.
2203 @item CHIP @var{expression}
2204 @itemx CHIP @var{expression}, @var{expression}
2205 @cindex @code{CHIP} (MRI)
2206 This command does nothing; it is accepted only for compatibility.
2209 @cindex @code{END} (MRI)
2210 This command does nothing whatever; it's only accepted for compatibility.
2212 @item FORMAT @var{output-format}
2213 @cindex @code{FORMAT} (MRI)
2214 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
2215 language, but restricted to one of these output formats:
2218 S-records, if @var{output-format} is @samp{S}
2221 IEEE, if @var{output-format} is @samp{IEEE}
2224 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
2228 @item LIST @var{anything}@dots{}
2229 @cindex @code{LIST} (MRI)
2230 Print (to the standard output file) a link map, as produced by the
2231 @code{ld} command-line option @samp{-M}.
2233 The keyword @code{LIST} may be followed by anything on the
2234 same line, with no change in its effect.
2236 @item LOAD @var{filename}
2237 @item LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
2238 @cindex @code{LOAD} (MRI)
2239 Include one or more object file @var{filename} in the link; this has the
2240 same effect as specifying @var{filename} directly on the @code{ld}
2243 @item NAME @var{output-name}
2244 @cindex @code{NAME} (MRI)
2245 @var{output-name} is the name for the program produced by @code{ld}; the
2246 MRI-compatible command @code{NAME} is equivalent to the command-line
2247 option @samp{-o} or the general script language command @code{OUTPUT}.
2249 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
2250 @itemx ORDER @var{secname} @var{secname} @var{secname}
2251 @cindex @code{ORDER} (MRI)
2252 Normally, @code{ld} orders the sections in its output file in the
2253 order in which they first appear in the input files. In an MRI-compatible
2254 script, you can override this ordering with the @code{ORDER} command. The
2255 sections you list with @code{ORDER} will appear first in your output
2256 file, in the order specified.
2258 @item PUBLIC @var{name}=@var{expression}
2259 @itemx PUBLIC @var{name},@var{expression}
2260 @itemx PUBLIC @var{name} @var{expression}
2261 @cindex @code{PUBLIC} (MRI)
2262 Supply a value (@var{expression}) for external symbol
2263 @var{name} used in the linker input files.
2265 @item SECT @var{secname}, @var{expression}
2266 @itemx SECT @var{secname}=@var{expression}
2267 @itemx SECT @var{secname} @var{expression}
2268 @cindex @code{SECT} (MRI)
2269 You can use any of these three forms of the @code{SECT} command to
2270 specify the start address (@var{expression}) for section @var{secname}.
2271 If you have more than one @code{SECT} statement for the same
2272 @var{secname}, only the @emph{first} sets the start address.
2282 % I think something like @colophon should be in texinfo. In the
2284 \long\def\colophon{\hbox to0pt{}\vfill
2285 \centerline{The body of this manual is set in}
2286 \centerline{\fontname\tenrm,}
2287 \centerline{with headings in {\bf\fontname\tenbf}}
2288 \centerline{and examples in {\tt\fontname\tentt}.}
2289 \centerline{{\it\fontname\tenit\/} and}
2290 \centerline{{\sl\fontname\tensl\/}}
2291 \centerline{are used for emphasis.}\vfill}
2293 % Blame: pesch@cygnus.com, 28mar91.