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} ] [ --help ] [ -i ]
172 [ -l@var{archive} ] [ -L@var{searchdir} ] [ -M ] [ -Map @var{mapfile} ]
173 [ -m @var{emulation} ] [ -N | -n ] [ -noinhibit-exec ]
174 [ -oformat @var{output-format} ] [ -R @var{filename} ] [ -relax ]
175 [ -r | -Ur ] [ -S ] [ -s ] [ -T @var{commandfile} ]
176 [ -Ttext @var{textorg} ] [ -Tdata @var{dataorg} ]
177 [ -Tbss @var{bssorg} ] [ -t ] [ -u @var{symbol}] [-V] [-v] [ --version ]
178 [ -y@var{symbol} ] [ -X ] [-x ]
181 This plethora of command-line options may seem intimidating, but in
182 actual practice few of them are used in any particular context.
183 @cindex standard Unix system
184 For instance, a frequent use of @code{ld} is to link standard Unix
185 object files on a standard, supported Unix system. On such a system, to
186 link a file @code{hello.o}:
189 ld -o @var{output} /lib/crt0.o hello.o -lc
192 This tells @code{ld} to produce a file called @var{output} as the
193 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
194 the library @code{libc.a}, which will come from the standard search
195 directories. (See the discussion of the @samp{-l} option below.)
197 The command-line options to @code{ld} may be specified in any order, and
198 may be repeated at will. Repeating most options with a
199 different argument will either have no further effect, or override prior
200 occurrences (those further to the left on the command line) of that
203 @ifclear SingleFormat
204 The exceptions---which may meaningfully be used more than once---are
205 @samp{-A}, @samp{-b} (or its synonym @samp{-format}), @samp{-defsym},
206 @samp{-L}, @samp{-l}, @samp{-R}, and @samp{-u}.
209 The exceptions---which may meaningfully be used more than once---are
210 @samp{-A}, @samp{-defsym}, @samp{-L}, @samp{-l}, @samp{-R}, and @samp{-u}.
214 The list of object files to be linked together, shown as @var{objfile}@dots{},
215 may follow, precede, or be mixed in with command-line options, except that
216 an @var{objfile} argument may not be placed between an option and
219 Usually the linker is invoked with at least one object file, but other
220 forms of binary input files can also be specified with @samp{-l},
221 @samp{-R}, and the script command language. If @emph{no} binary input
222 files at all are specified, the linker does not produce any output, and
223 issues the message @samp{No input files}.
225 Option arguments must either follow the option letter without intervening
226 whitespace, or be given as separate arguments immediately following the
227 option that requires them.
230 @item @var{objfile}@dots{}
231 The object files to be linked.
234 @cindex architectures
236 @item -A@var{architecture}
237 In the current release of @code{ld}, this option is useful only for the
238 Intel 960 family of architectures. In that @code{ld} configuration, the
239 @var{architecture} argument identifies the particular architecture in
240 the 960 family, enabling some safeguards and modifying the
241 archive-library search path. @xref{i960,,@code{ld} and the Intel 960
242 family}, for details.
244 Future releases of @code{ld} may support similar functionality for
245 other architecture families.
248 @ifclear SingleFormat
249 @cindex binary input format
250 @kindex -b @var{format}
252 @item -b @var{input-format}
254 Specify the binary format for input object files that follow this option
255 on the command line. You don't usually need to specify this, as
256 @code{ld} is configured to expect as a default input format the most
257 usual format on each machine. @var{input-format} is a text string, the
258 name of a particular format supported by the BFD libraries.
259 (You can list the available binary formats with @samp{objdump -i}.)
260 @w{@samp{-format @var{input-format}}} has the same effect, as does the
261 script command @code{TARGET}. @xref{BFD}.
263 You may want to use this option if you are linking files with an unusual
264 binary format. You can also use @samp{-b} to switch formats explicitly (when
265 linking object files of different formats), by including
266 @samp{-b @var{input-format}} before each group of object files in a
269 The default format is taken from the environment variable
274 You can also define the input
275 format from a script, using the command @code{TARGET}; see @ref{Other
281 Ignored. This option is accepted for command-line compatibility with
284 @kindex -c @var{MRI-cmdfile}
285 @cindex compatibility, MRI
286 @item -c @var{MRI-commandfile}
287 For compatibility with linkers produced by MRI, @code{ld} accepts script
288 files written in an alternate, restricted command language, described in
289 @ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
290 the option @samp{-c}; use the @samp{-T} option to run linker
291 scripts written in the general-purpose @code{ld} scripting language.
292 If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
293 specified by any @samp{-L} options.
295 @cindex common allocation
302 These three options are equivalent; multiple forms are supported for
303 compatibility with other linkers. They
304 assign space to common symbols even if a relocatable output file is
305 specified (with @samp{-r}). The script command
306 @code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Other
309 @cindex symbols, from command line
310 @kindex -defsym @var{symbol}=@var{exp}
311 @item -defsym @var{symbol}=@var{expression}
312 Create a global symbol in the output file, containing the absolute
313 address given by @var{expression}. You may use this option as many
314 times as necessary to define multiple symbols in the command line. A
315 limited form of arithmetic is supported for the @var{expression} in this
316 context: you may give a hexadecimal constant or the name of an existing
317 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
318 constants or symbols. If you need more elaborate expressions, consider
319 using the linker command language from a script (@pxref{Assignment, ,
320 Assignment: Symbol Definitions}). @emph{Note:} there should be no
321 white space between @var{symbol}, the equals sign (``@key{=}''), and
324 @cindex entry point, from command line
325 @kindex -e @var{entry}
327 Use @var{entry} as the explicit symbol for beginning execution of your
328 program, rather than the default entry point. @xref{Entry Point}, for a
329 discussion of defaults and other ways of specifying the
332 @ifclear SingleFormat
335 @itemx -F@var{format}
336 Ignored. Some older linkers used this option throughout a compilation
337 toolchain for specifying object-file format for both input and output
338 object files. The mechanisms @code{ld} uses for this purpose (the
339 @samp{-b} or @samp{-format} options for input files, the @code{TARGET}
340 command in linker scripts for output files, the @code{GNUTARGET}
341 environment variable) are more flexible, but @code{ld} accepts the
342 @samp{-F} option for compatibility with scripts written to call the old
346 @item -format @var{input-format}
347 Synonym for @samp{-b @var{input-format}}.
352 Ignored. Provided for compatibility with other tools.
357 @itemx -G @var{value}
358 Set the maximum size of objects to be optimized using the GP register to
359 @var{size} under MIPS ECOFF. Ignored for other object file formats.
365 Print a summary of the command-line options on the standard output and exit.
366 This option and @samp{--version} begin with two dashes instead of one
367 for compatibility with other GNU programs. The other options start with
368 only one dash for compatibility with other linkers.
371 @cindex incremental link
373 Perform an incremental link (same as option @samp{-r}).
375 @cindex archive files, from cmd line
376 @kindex -l@var{archive}
378 Add archive file @var{archive} to the list of files to link. This
379 option may be used any number of times. @code{ld} will search its
380 path-list for occurrences of @code{lib@var{ar}.a} for every @var{archive}
383 @cindex search directory, from cmd line
385 @item -L@var{searchdir}
386 Add path @var{searchdir} to the list of paths that @code{ld} will search
387 for archive libraries and @code{ld} control scripts. You may use this
388 option any number of times.
391 The default set of paths searched (without being specified with
392 @samp{-L}) depends on which emulation mode @code{ld} is using, and in
393 some cases also on how it was configured. @xref{Environment}.
396 The paths can also be specified in a link script with the
397 @code{SEARCH_DIR} command.
402 Print (to the standard output) a link map---diagnostic information
403 about where symbols are mapped by @code{ld}, and information on global
404 common storage allocation.
408 @item -Map @var{mapfile}
409 Print to the file @var{mapfile} a link map---diagnostic information
410 about where symbols are mapped by @code{ld}, and information on global
411 common storage allocation.
414 @kindex -m @var{emulation}
415 @item -m@var{emulation}
416 @itemx -m @var{emulation}
417 Emulate the @var{emulation} linker. You can list the available
418 emulations with the @samp{-V} option. The
419 default is the system for which you configured @code{ld}.
422 @cindex read/write from cmd line
425 Set the text and data sections to be readable and writable. Also, do
426 not page-align the data segment. If the output format supports Unix
427 style magic numbers, mark the output as @code{OMAGIC}.
431 @cindex read-only text
433 Set the text segment to be read only, and mark the output as
434 @code{NMAGIC} if possible.
436 @item -noinhibit-exec
437 @cindex output file after errors
438 @kindex -noinhibit-exec
439 Retain the executable output file whenever it is still usable.
440 Normally, the linker will not produce an output file if it encounters
441 errors during the link process; it exits without writing an output file
442 when it issues any error whatsoever.
444 @item -o @var{output}
445 @kindex -o @var{output}
446 @cindex naming the output file
447 Use @var{output} as the name for the program produced by @code{ld}; if this
448 option is not specified, the name @file{a.out} is used by default. The
449 script command @code{OUTPUT} can also specify the output file name.
452 @item -oformat @var{output-format}
453 Specify the binary format for the output object file. You don't usually
454 need to specify this, as @code{ld} is configured to produce as a default
455 output format the most usual format on each machine.
456 @var{output-format} is a text string, the name of a particular format
457 supported by the BFD libraries. (You can list the available binary
458 formats with @samp{objdump -i}.) The script command
459 @code{OUTPUT_FORMAT} can also specify the output format, but this option
460 overrides it. @xref{BFD}.
462 @item -R @var{filename}
463 @kindex -R @var{file}
464 @cindex symbol-only input
465 On some platforms, this option performs global optimizations
466 that become possible when the linker resolves addressing in the
467 program, such as relaxing address modes and synthesizing new
468 instructions in the output object file.
472 @cindex synthesizing linker
473 @cindex relaxing addressing modes
474 An option with machine dependent effects. Currently this option is only
475 supported on the H8/300.
477 @xref{H8/300,,@code{ld} and the H8/300}.
480 On some platforms, use option performs global optimizations that
481 become possible when the linker resolves addressing in the program, such
482 as relaxing address modes and synthesizing new instructions in the
485 On platforms where this is not supported, @samp{-relax} is accepted, but
490 @cindex relocatable output
492 Generate relocatable output---i.e., generate an output file that can in
493 turn serve as input to @code{ld}. This is often called @dfn{partial
494 linking}. As a side effect, in environments that support standard Unix
495 magic numbers, this option also sets the output file's magic number to
498 If this option is not specified, an absolute file is produced. When
499 linking C++ programs, this option @emph{will not} resolve references to
500 constructors; to do that, use @samp{-Ur}.
502 This option does the same as @code{-i}.
506 @cindex strip debugger symbols
507 Omit debugger symbol information (but not all symbols) from the output file.
511 @cindex strip all symbols
512 Omit all symbol information from the output file.
514 @item -Tbss @var{bssorg}
515 @kindex -Tbss @var{bssorg}
516 @itemx -Tdata @var{dataorg}
517 @kindex -Tdata @var{dataorg}
518 @itemx -Ttext @var{textorg}
519 @kindex -Ttext @var{textorg}
520 @cindex segment origins, cmd line
521 Use @var{org} as the starting address for---respectively---the
522 @code{bss}, @code{data}, or the @code{text} segment of the output file.
523 @var{org} must be a single hexadecimal integer;
524 for compatibility with other linkers, you may omit the leading
525 @samp{0x} usually associated with hexadecimal values.
527 @item -T @var{commandfile}
528 @itemx -T@var{commandfile}
529 @kindex -T @var{script}
531 Read link commands from the file @var{commandfile}. These commands
532 completely override @code{ld}'s default link format (rather than adding
533 to it); @var{commandfile} must specify everything necessary to describe
534 the target format. @xref{Commands}. If @var{commandfile} does not
535 exist, @code{ld} looks for it in the directories specified by any
536 preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
541 @cindex input files, displaying
542 Print the names of the input files as @code{ld} processes them.
544 @item -u @var{symbol}
545 @kindex -u @var{symbol}
546 @cindex undefined symbol
547 Force @var{symbol} to be entered in the output file as an undefined symbol.
548 Doing this may, for example, trigger linking of additional modules from
549 standard libraries. @samp{-u} may be repeated with different option
550 arguments to enter additional undefined symbols.
551 @c Nice idea, but no such command: This option is equivalent
552 @c to the @code{EXTERN} linker command.
557 For anything other than C++ programs, this option is equivalent to
558 @samp{-r}: it generates relocatable output---i.e., an output file that can in
559 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
560 @emph{will} resolve references to constructors, unlike @samp{-r}.
565 Display the version number for @code{ld} and list the supported emulations.
566 Display which input files can and can not be opened.
571 Display the version number for @code{ld}.
575 Display the version number for @code{ld} and exit.
579 @cindex local symbols, deleting
580 @cindex L, deleting symbols beginning
581 If @samp{-s} or @samp{-S} is also specified, delete only local symbols
582 beginning with @samp{L}.
586 @cindex deleting local symbols
587 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
588 not just those beginning with @samp{L}.
591 @kindex -y@var{symbol}
592 @cindex symbol tracing
593 Print the name of each linked file in which @var{symbol} appears. This
594 option may be given any number of times. On many systems it is necessary
595 to prepend an underscore.
597 This option is useful when you have an undefined symbol in your link but
598 don't know where the reference is coming from.
603 @section Environment Variables
605 You can change the behavior of @code{ld} with the environment
606 variable @code{GNUTARGET}.
609 @cindex default input format
610 @code{GNUTARGET} determines the input-file object format if you don't
611 use @samp{-b} (or its synonym @samp{-format}). Its value should be one
612 of the BFD names for an input format (@pxref{BFD}). If there is no
613 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
614 of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
615 input format by examining binary input files; this method often
616 succeeds, but there are potential ambiguities, since there is no method
617 of ensuring that the magic number used to specify object-file formats is
618 unique. However, the configuration procedure for BFD on each system
619 places the conventional format for that system first in the search-list,
620 so ambiguities are resolved in favor of convention.
624 @chapter Command Language
626 @cindex command files
627 The command language provides explicit control over the link process,
628 allowing complete specification of the mapping between the linker's
629 input files and its output. It controls:
638 addresses of sections
640 placement of common blocks
643 You may supply a command file (also known as a link script) to the
644 linker either explicitly through the @samp{-T} option, or implicitly as
645 an ordinary file. If the linker opens a file which it cannot recognize
646 as a supported object or archive format, it tries to interpret the file
650 * Scripts:: Linker Scripts
651 * Expressions:: Expressions
652 * MEMORY:: MEMORY Command
653 * SECTIONS:: SECTIONS Command
654 * Entry Point:: The Entry Point
655 * Other Commands:: Other Commands
659 @section Linker Scripts
660 The @code{ld} command language is a collection of statements; some are
661 simple keywords setting a particular option, some are used to select and
662 group input files or name output files; and two statement
663 types have a fundamental and pervasive impact on the linking process.
665 @cindex fundamental script commands
666 @cindex commands, fundamental
667 @cindex output file layout
668 @cindex layout of output file
669 The most fundamental command of the @code{ld} command language is the
670 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
671 script must have a @code{SECTIONS} command: it specifies a
672 ``picture'' of the output file's layout, in varying degrees of detail.
673 No other command is required in all cases.
675 The @code{MEMORY} command complements @code{SECTIONS} by describing the
676 available memory in the target architecture. This command is optional;
677 if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
678 memory is available in a contiguous block for all output.
682 You may include comments in linker scripts just as in C: delimited
683 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
684 equivalent to whitespace.
688 @cindex expression syntax
690 Many useful commands involve arithmetic expressions. The syntax for
691 expressions in the command language is identical to that of C
692 expressions, with the following features:
695 All expressions evaluated as integers and
696 are of ``long'' or ``unsigned long'' type.
698 All constants are integers.
700 All of the C arithmetic operators are provided.
702 You may reference, define, and create global variables.
704 You may call special purpose built-in functions.
708 * Integers:: Integers
709 * Symbols:: Symbol Names
710 * Location Counter:: The Location Counter
711 * Operators:: Operators
712 * Evaluation:: Evaluation
713 * Assignment:: Assignment: Defining Symbols
714 * Built-ins:: Built-In Functions
719 @cindex integer notation
720 @cindex octal integers
721 An octal integer is @samp{0} followed by zero or more of the octal
722 digits (@samp{01234567}).
727 @cindex decimal integers
728 A decimal integer starts with a non-zero digit followed by zero or
729 more digits (@samp{0123456789}).
734 @cindex hexadecimal integers
736 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
737 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
742 @cindex negative integers
743 To write a negative integer, use
744 the prefix operator @samp{-}; @pxref{Operators}.
749 @cindex scaled integers
750 @cindex K and M integer suffixes
751 @cindex M and K integer suffixes
752 @cindex suffixes for integers
753 @cindex integer suffixes
754 Additionally the suffixes @code{K} and @code{M} may be used to scale a
758 @c END TEXI2ROFF-KILL
759 @code{1024} or @code{1024*1024}
763 ${\rm 1024}$ or ${\rm 1024}^2$
765 @c END TEXI2ROFF-KILL
766 respectively. For example, the following all refer to the same quantity:
775 @subsection Symbol Names
778 @cindex quoted symbol names
780 Unless quoted, symbol names start with a letter, underscore, point or
781 hyphen and may include any letters, underscores, digits, points,
782 and minus signs. Unquoted symbol names must not conflict with any
783 keywords. You can specify a symbol which contains odd characters or has
784 the same name as a keyword, by surrounding the symbol name in double quotes:
787 "with a space" = "also with a space" + 10;
790 @node Location Counter
791 @subsection The Location Counter
794 @cindex location counter
795 @cindex current output location
796 The special linker variable @dfn{dot} @samp{.} always contains the
797 current output location counter. Since the @code{.} always refers to
798 a location in an output section, it must always appear in an
799 expression within a @code{SECTIONS} command. The @code{.} symbol
800 may appear anywhere that an ordinary symbol is allowed in an
801 expression, but its assignments have a side effect. Assigning a value
802 to the @code{.} symbol will cause the location counter to be moved.
804 This may be used to create holes in the output section. The location
805 counter may never be moved backwards.
820 In the previous example, @code{file1} is located at the beginning of the
821 output section, then there is a 1000 byte gap. Then @code{file2}
822 appears, also with a 1000 byte gap following before @code{file3} is
823 loaded. The notation @samp{= 0x1234} specifies what data to write in
824 the gaps (@pxref{Section Options}).
827 @subsection Operators
828 @cindex Operators for arithmetic
829 @cindex arithmetic operators
830 @cindex precedence in expressions
831 The linker recognizes the standard C set of arithmetic operators, with
832 the standard bindings and precedence levels:
835 @c END TEXI2ROFF-KILL
837 precedence associativity Operators Notes
843 5 left == != > < <= >=
849 11 right &= += -= *= /= (2)
854 (2) @xref{Assignment}
859 %"lispnarrowing" is the extra indent used generally for @example
860 \hskip\lispnarrowing\vbox{\offinterlineskip
863 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
864 height2pt&\omit&&\omit&&\omit&\cr
865 &Precedence&& Associativity &&{\rm Operators}&\cr
866 height2pt&\omit&&\omit&&\omit&\cr
868 height2pt&\omit&&\omit&&\omit&\cr
870 % '176 is tilde, '~' in tt font
871 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
875 &5&&left&&== != > < <= >=&\cr
881 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
883 height2pt&\omit&&\omit&&\omit&\cr}
888 @obeylines@parskip=0pt@parindent=0pt
889 @dag@quad Prefix operators.
890 @ddag@quad @xref{Assignment}.
893 @c END TEXI2ROFF-KILL
896 @subsection Evaluation
898 @cindex lazy evaluation
899 @cindex expression evaluation order
900 The linker uses ``lazy evaluation'' for expressions; it only calculates
901 an expression when absolutely necessary. The linker needs the value of
902 the start address, and the lengths of memory regions, in order to do any
903 linking at all; these values are computed as soon as possible when the
904 linker reads in the command file. However, other values (such as symbol
905 values) are not known or needed until after storage allocation. Such
906 values are evaluated later, when other information (such as the sizes of
907 output sections) is available for use in the symbol assignment
911 @subsection Assignment: Defining Symbols
912 @cindex assignment in scripts
913 @cindex symbol definition, scripts
914 @cindex variables, defining
915 You may create global symbols, and assign values (addresses) to global
916 symbols, using any of the C assignment operators:
919 @item @var{symbol} = @var{expression} ;
920 @itemx @var{symbol} &= @var{expression} ;
921 @itemx @var{symbol} += @var{expression} ;
922 @itemx @var{symbol} -= @var{expression} ;
923 @itemx @var{symbol} *= @var{expression} ;
924 @itemx @var{symbol} /= @var{expression} ;
927 Two things distinguish assignment from other operators in @code{ld}
931 Assignment may only be used at the root of an expression;
932 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
937 You must place a trailing semicolon (``@key{;}'') at the end of an
938 assignment statement.
941 Assignment statements may appear:
944 as commands in their own right in an @code{ld} script; or
946 as independent statements within a @code{SECTIONS} command; or
948 as part of the contents of a section definition in a
949 @code{SECTIONS} command.
952 The first two cases are equivalent in effect---both define a symbol with
953 an absolute address. The last case defines a symbol whose address is
954 relative to a particular section (@pxref{SECTIONS}).
956 @cindex absolute and relocatable symbols
957 @cindex relocatable and absolute symbols
958 @cindex symbols, relocatable and absolute
959 When a linker expression is evaluated and assigned to a variable, it is
960 given either an absolute or a relocatable type. An absolute expression
961 type is one in which the symbol contains the value that it will have in
962 the output file, a relocatable expression type is one in which the
963 value is expressed as a fixed offset from the base of a section.
965 The type of the expression is controlled by its position in the script
966 file. A symbol assigned within a section definition is created relative
967 to the base of the section; a symbol assigned in any other place is
968 created as an absolute symbol. Since a symbol created within a
969 section definition is relative to the base of the section, it
970 will remain relocatable if relocatable output is requested. A symbol
971 may be created with an absolute value even when assigned to within a
972 section definition by using the absolute assignment function
973 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
974 is the last byte of an output section named @code{.data}:
980 _edata = ABSOLUTE(.) ;
985 The linker tries to put off the evaluation of an assignment until all
986 the terms in the source expression are known (@pxref{Evaluation}). For
987 instance, the sizes of sections cannot be known until after allocation,
988 so assignments dependent upon these are not performed until after
989 allocation. Some expressions, such as those depending upon the location
990 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
991 result of an expression is required, but the value is not available,
992 then an error results. For example, a script like the following
995 text 9+this_isnt_constant :
1000 @kindex Non constant expression
1002 will cause the error message ``@code{Non constant expression for initial
1006 @subsection Built-In Functions
1007 @cindex functions in expression language
1008 The command language includes a number of built-in
1009 functions for use in link script expressions.
1011 @item ABSOLUTE(@var{exp})
1012 @kindex ABSOLUTE(@var{exp})
1013 @cindex expression, absolute
1014 Return the absolute (non-relocatable, as opposed to non-negative) value
1015 of the expression @var{exp}. Primarily useful to assign an absolute
1016 value to a symbol within a section definition, where symbol values are
1017 normally section-relative.
1019 @item ADDR(@var{section})
1020 @kindex ADDR(@var{section})
1021 @cindex section address
1022 Return the absolute address of the named @var{section}. Your script must
1023 previously have defined the location of that section. In the following
1024 example, @code{symbol_1} and @code{symbol_2} are assigned identical
1030 start_of_output_1 = ABSOLUTE(.);
1035 symbol_1 = ADDR(.output1);
1036 symbol_2 = start_of_output_1;
1041 @item ALIGN(@var{exp})
1042 @kindex ALIGN(@var{exp})
1043 @cindex rounding up location counter
1044 Return the result of the current location counter (@code{.}) aligned to
1045 the next @var{exp} boundary. @var{exp} must be an expression whose
1046 value is a power of two. This is equivalent to
1048 (. + @var{exp} - 1) & ~(@var{exp} - 1)
1051 @code{ALIGN} doesn't change the value of the location counter---it just
1052 does arithmetic on it. As an example, to align the output @code{.data}
1053 section to the next @code{0x2000} byte boundary after the preceding
1054 section and to set a variable within the section to the next
1055 @code{0x8000} boundary after the input sections:
1058 .data ALIGN(0x2000): @{
1060 variable = ALIGN(0x8000);
1065 The first use of @code{ALIGN} in this example specifies the location of
1066 a section because it is used as the optional @var{start} attribute of a
1067 section definition (@pxref{Section Options}). The second use simply
1068 defines the value of a variable.
1070 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1072 @item DEFINED(@var{symbol})
1073 @kindex DEFINED(@var{symbol})
1074 @cindex symbol defaults
1075 Return 1 if @var{symbol} is in the linker global symbol table and is
1076 defined, otherwise return 0. You can use this function to provide default
1077 values for symbols. For example, the following command-file fragment shows how
1078 to set a global symbol @code{begin} to the first location in the
1079 @code{.text} section---but if a symbol called @code{begin} already
1080 existed, its value is preserved:
1084 begin = DEFINED(begin) ? begin : . ;
1090 @item NEXT(@var{exp})
1091 @kindex NEXT(@var{exp})
1092 @cindex unallocated address, next
1093 Return the next unallocated address that is a multiple of @var{exp}.
1094 This function is closely related to @code{ALIGN(@var{exp})}; unless you
1095 use the @code{MEMORY} command to define discontinuous memory for the
1096 output file, the two functions are equivalent.
1098 @item SIZEOF(@var{section})
1099 @kindex SIZEOF(@var{section})
1100 @cindex section size
1101 Return the size in bytes of the named @var{section}, if that section has
1102 been allocated. In the following example, @code{symbol_1} and
1103 @code{symbol_2} are assigned identical values:
1104 @c What does it return if the section hasn't been allocated? 0?
1112 symbol_1 = .end - .start ;
1113 symbol_2 = SIZEOF(.output);
1118 @item SIZEOF_HEADERS
1119 @kindex SIZEOF_HEADERS
1121 @itemx sizeof_headers
1122 @kindex sizeof_headers
1123 Return the size in bytes of the output file's headers. You can use this number
1124 as the start address of the first section, if you choose, to facilitate
1130 @section MEMORY Command
1132 @cindex regions of memory
1133 @cindex discontinuous memory
1134 @cindex allocating memory
1135 The linker's default configuration permits allocation of all available memory.
1136 You can override this configuration by using the @code{MEMORY} command. The
1137 @code{MEMORY} command describes the location and size of blocks of
1138 memory in the target. By using it carefully, you can describe which
1139 memory regions may be used by the linker, and which memory regions it
1140 must avoid. The linker does not shuffle sections to fit into the
1141 available regions, but does move the requested sections into the correct
1142 regions and issue errors when the regions become too full.
1144 The command files may contain at most one use of the @code{MEMORY}
1145 command; however, you can define as many blocks of memory within it as
1146 you wish. The syntax is:
1151 @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
1157 @cindex naming memory regions
1158 is a name used internally by the linker to refer to the region. Any
1159 symbol name may be used. The region names are stored in a separate
1160 name space, and will not conflict with symbols, file names or section
1161 names. Use distinct names to specify multiple regions.
1163 @cindex memory region attributes
1164 is an optional list of attributes, permitted for compatibility with the
1165 AT&T linker but not used by @code{ld} beyond checking that the
1166 attribute list is valid. Valid attribute lists must be made up of the
1167 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1168 omit the parentheses around it as well.
1173 is the start address of the region in physical memory. It is
1174 an expression that must evaluate to a constant before
1175 memory allocation is performed. The keyword @code{ORIGIN} may be
1176 abbreviated to @code{org} or @code{o}.
1181 is the size in bytes of the region (an expression).
1182 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1185 For example, to specify that memory has two regions available for
1186 allocation---one starting at 0 for 256 kilobytes, and the other
1187 starting at @code{0x40000000} for four megabytes:
1192 rom : ORIGIN = 0, LENGTH = 256K
1193 ram : org = 0x40000000, l = 4M
1197 Once you have defined a region of memory named @var{mem}, you can direct
1198 specific output sections there by using a command ending in
1199 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1200 Options}). If the combined output sections directed to a region are too
1201 big for the region, the linker will issue an error message.
1204 @section SECTIONS Command
1206 The @code{SECTIONS} command controls exactly where input sections are
1207 placed into output sections, their order and to which output sections
1210 You may use at most one @code{SECTIONS} command in a commands file,
1211 but you can have as many statements within it as you wish. Statements
1212 within the @code{SECTIONS} command can do one of three things:
1215 define the entry point;
1217 assign a value to a symbol;
1219 describe the placement of a named output section, and what input
1220 sections make it up.
1223 The first two possibilities---defining the entry point, and defining
1224 symbols---can also be done outside the @code{SECTIONS} command:
1225 @pxref{Entry Point}, @pxref{Assignment}. They are permitted here as
1226 well for your convenience in reading the script, so that symbols or the
1227 entry point can be defined at meaningful points in your output-file
1230 When no @code{SECTIONS} command is specified, the default action
1231 of the linker is to place each input section into an identically named
1232 output section in the order that the sections are first encountered in
1233 the input files; if all input sections are present in the first file,
1234 for example, the order of sections in the output file will match the
1235 order in the first input file.
1238 * Section Definition:: Section Definitions
1239 * Section Contents:: Section Contents
1240 * Section Options:: Optional Section Attributes
1243 @node Section Definition
1244 @subsection Section Definitions
1245 @cindex section definition
1246 The most frequently used statement in the @code{SECTIONS} command is
1247 the @dfn{section definition}, which you can use to specify the
1248 properties of an output section: its location, alignment, contents,
1249 fill pattern, and target memory region. Most of
1250 these specifications are optional; the simplest form of a section
1259 @cindex naming output sections
1261 @var{secname} is the name of the output section, and @var{contents} a
1262 specification of what goes there---for example, a list of input files or
1263 sections of input files. As you might assume, the whitespace shown is
1264 optional. You do need the colon @samp{:} and the braces @samp{@{@}},
1267 @var{secname} must meet the constraints of your output format. In
1268 formats which only support a limited number of sections, such as
1269 @code{a.out}, the name must be one of the names supported by the format
1270 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1271 @code{.bss}). If the output format supports any number of sections, but
1272 with numbers and not names (as is the case for Oasys), the name should be
1273 supplied as a quoted numeric string. A section name may consist of any
1274 sequence characters, but any name which does not conform to the standard
1275 @code{ld} symbol name syntax must be quoted.
1276 @xref{Symbols, , Symbol Names}.
1278 @node Section Contents
1279 @subsection Section Contents
1280 @cindex contents of a section
1281 In a section definition, you can specify the contents of an output section by
1282 listing particular object files, by listing particular input-file
1283 sections, or by a combination of the two. You can also place arbitrary
1284 data in the section, and define symbols relative to the beginning of the
1287 The @var{contents} of a section definition may include any of the
1288 following kinds of statement. You can include as many of these as you
1289 like in a single section definition, separated from one another by
1293 @item @var{filename}
1294 @kindex @var{filename}
1295 @cindex input files, section defn
1296 @cindex files, including in output sections
1297 You may simply name a particular input file to be placed in the current
1298 output section; @emph{all} sections from that file are placed in the
1299 current section definition. To specify a list of particular files by
1302 .data : @{ afile.o bfile.o cfile.o @}
1305 The example also illustrates that multiple statements can be included in
1306 the contents of a section definition, since each file name is a separate
1309 If the file name has already been mentioned in another section
1310 definition, with an explicit section name list, then only those sections
1311 which have not yet been allocated are used.
1313 @item @var{filename}( @var{section} )
1314 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1315 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1316 @kindex @var{filename}(@var{section})
1317 @cindex files and sections, section defn
1318 You can name one or more sections from your input files, for
1319 insertion in the current output section. If you wish to specify a list
1320 of input-file sections inside the parentheses, you may separate the
1321 section names by either commas or whitespace.
1323 @item * (@var{section})
1324 @itemx * (@var{section}, @var{section}, @dots{})
1325 @itemx * (@var{section} @var{section} @dots{}
1326 @cindex input sections to output section
1327 @kindex *(@var{section})
1328 Instead of explicitly naming particular input files in a link control
1329 script, you can refer to @emph{all} files from the @code{ld} command
1330 line: use @samp{*} instead of a particular file name before the
1331 parenthesized input-file section list.
1333 For example, to copy sections @code{1} through @code{4} from an Oasys file
1334 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1335 and @code{14} into the @code{.data} section:
1348 If you have already explicitly included some files by name, @samp{*}
1349 refers to all @emph{remaining} files---those whose places in the output
1350 file have not yet been defined.
1352 @item [ @var{section} ]
1353 @itemx [ @var{section}, @var{section}, @dots{} ]
1354 @itemx [ @var{section} @var{section} @dots{} ]
1355 @kindex [ @var{sections} ]
1356 This is an alternate notation to specify named sections from all
1357 unallocated input files; its effect is exactly the same as that of
1358 @samp{* (@var{section}@dots{})}
1360 @item @var{filename}@code{( COMMON )}
1363 @cindex uninitialized data
1364 @cindex commons in output
1365 Specify where in your output file to place uninitialized data
1366 with this notation. @code{*(COMMON)} by itself refers to all
1367 uninitialized data from all input files (so far as it is not yet
1368 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1369 from a particular file. Both are special cases of the general
1370 mechanisms for specifying where to place input-file sections:
1371 @code{ld} permits you to refer to uninitialized data as if it
1372 were in an input-file section named @code{COMMON}, regardless of the
1373 input file's format.
1376 For example, the following command script arranges the output file into
1377 three consecutive sections, named @code{.text}, @code{.data}, and
1378 @code{.bss}, taking the input for each from the correspondingly named
1379 sections of all the input files:
1382 .text : @{ *(.text) @}
1383 .data : @{ *(.data) @}
1384 .bss : @{ *(.bss) *(COMMON) @}
1388 The following example reads all of the sections from file @code{all.o}
1389 and places them at the start of output section @code{outputa} which
1390 starts at location @code{0x10000}. All of section @code{.input1} from
1391 file @code{foo.o} follows immediately, in the same output section. All
1392 of section @code{.input2} from @code{foo.o} goes into output section
1393 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1394 All of the remaining @code{.input1} and @code{.input2} sections from any
1395 files are written to output section @code{outputc}.
1417 There are still more kinds of statements permitted in the contents of
1418 output section definitions. The foregoing statements permitted you to
1419 arrange, in your output file, data originating from your input files.
1420 You can also place data directly in an output section from the link
1421 command script. Most of these additional statements involve
1422 expressions; @pxref{Expressions}. Although these statements are shown
1423 separately here for ease of presentation, no such segregation is needed
1424 within a section definition in the @code{SECTIONS} command; you can
1425 intermix them freely with any of the statements we've just described.
1428 @item CREATE_OBJECT_SYMBOLS
1429 @kindex CREATE_OBJECT_SYMBOLS
1430 @cindex input filename symbols
1431 @cindex filename symbols
1432 Create a symbol for each input file
1433 in the current section, set to the address of the first byte of
1434 data written from the input file. For instance, with @code{a.out}
1435 files it is conventional to have a symbol for each input file. You can
1436 accomplish this by defining the output @code{.text} section as follows:
1441 CREATE_OBJECT_SYMBOLS
1443 _etext = ALIGN(0x2000);
1449 If @code{objsym} is a file containing this script, and @code{a.o},
1450 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1451 contents like the following---
1461 @samp{ld -M sample a.o b.o c.o d.o} would create a map like this,
1462 containing symbols matching the object file names:
1464 00000000 A __DYNAMIC
1467 00002020 T _afunction
1470 00002038 T _bfunction
1473 00002050 T _cfunction
1476 00002068 T _dfunction
1486 @item @var{symbol} = @var{expression} ;
1487 @kindex @var{symbol} = @var{expression} ;
1488 @itemx @var{symbol} @var{f}= @var{expression} ;
1489 @kindex @var{symbol} @var{f}= @var{expression} ;
1490 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1491 refers to any of the operators @code{&= += -= *= /=} which combine
1492 arithmetic and assignment.
1494 @cindex assignment, in section defn
1495 When you assign a value to a symbol within a particular section
1496 definition, the value is relative to the beginning of the section
1497 (@pxref{Assignment}). If you write
1502 .data : @{ @dots{} rel = 14 ; @dots{} @}
1503 abs2 = 14 + ADDR(.data);
1507 @c FIXME: Try above example!
1509 @code{abs} and @code{rel} do not have the same value; @code{rel} has the
1510 same value as @code{abs2}.
1512 @item BYTE(@var{expression})
1513 @kindex BYTE(@var{expression})
1514 @itemx SHORT(@var{expression})
1515 @kindex SHORT(@var{expression})
1516 @itemx LONG(@var{expression})
1517 @kindex LONG(@var{expression})
1518 @cindex direct output
1519 By including one of these three statements in a section definition, you
1520 can explicitly place one, two, or four bytes (respectively) at the
1521 current address of that section.
1523 @ifclear SingleFormat
1524 Multiple-byte quantities are represented in whatever byte order is
1525 appropriate for the output file format (@pxref{BFD}).
1528 @item FILL(@var{expression})
1529 @kindex FILL(@var{expression})
1530 @cindex holes, filling
1531 @cindex unspecified memory
1532 Specifies the ``fill pattern'' for the current section. Any otherwise
1533 unspecified regions of memory within the section (for example, regions
1534 you skip over by assigning a new value to the location counter @samp{.})
1535 are filled with the two least significant bytes from the
1536 @var{expression} argument. A @code{FILL} statement covers memory
1537 locations @emph{after} the point it occurs in the section definition; by
1538 including more than one @code{FILL} statement, you can have different
1539 fill patterns in different parts of an output section.
1542 @node Section Options
1543 @subsection Optional Section Attributes
1544 @cindex section defn, full syntax
1545 Here is the full syntax of a section definition, including all the
1551 @var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : @{ @var{contents} @} =@var{fill} >@var{region}
1556 @var{secname} and @var{contents} are required. @xref{Section
1557 Definition}, and @pxref{Section Contents} for details on @var{contents}.
1558 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1559 @code{(NOLOAD)} @code{=@var{fill}}, and @code{>@var{region}}---are all
1564 @cindex start address, section
1565 @cindex section start
1566 @cindex section address
1567 You can force the output section to be loaded at a specified address by
1568 specifying @var{start} immediately following the section name.
1569 @var{start} can be represented as any expression. The following
1570 example generates section @var{output} at location
1575 output 0x40000000: @{
1582 @item BLOCK(@var{align})
1583 @kindex BLOCK(@var{align})
1584 @cindex section alignment
1585 @cindex aligning sections
1586 You can include @code{BLOCK()} specification to advance
1587 the location counter @code{.} prior to the beginning of the section, so
1588 that the section will begin at the specified alignment. @var{align} is
1593 @cindex prevent unnecessary loading
1594 Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
1595 each time it is accessed. For example, in the script sample below, the
1596 @code{ROM} segment is addressed at memory location @samp{0} and does not
1597 need to be loaded into each object file:
1600 ROM 0 (NOLOAD) : @{ @dots{} @}
1607 @cindex section fill pattern
1608 @cindex fill pattern, entire section
1610 @code{=@var{fill}} in a section definition specifies the initial fill
1611 value for that section.
1612 You may use any expression to specify @var{fill}.
1613 Any unallocated holes in the current output
1614 section when written to the output file will be filled with the two
1615 least significant bytes of the value, repeated as necessary. You can
1616 also change the fill value with a @code{FILL} statement in the
1617 @var{contents} of a section definition.
1620 @kindex >@var{region}
1621 @cindex section, assigning to memory region
1622 @cindex memory regions and sections
1623 Assign this section to a previously defined region of memory.
1629 @section The Entry Point
1630 @kindex ENTRY(@var{symbol})
1631 @cindex start of execution
1632 @cindex first instruction
1633 The linker command language includes a command specifically for
1634 defining the first executable instruction in an output file (its
1635 @dfn{entry point}). Its argument is a symbol name:
1640 Like symbol assignments, the @code{ENTRY} command may be placed either
1641 as an independent command in the command file, or among the section
1642 definitions within the @code{SECTIONS} command---whatever makes the most
1643 sense for your layout.
1645 @cindex entry point, defaults
1646 @code{ENTRY} is only one of several ways of choosing the entry point.
1647 You may indicate it in any of the following ways (shown in descending
1648 order of priority: methods higher in the list override methods lower down).
1651 the @samp{-e} @var{entry} command-line option;
1653 the @code{ENTRY(@var{symbol}} command in a linker control script;
1655 the value of the symbol @code{start}, if present;
1657 the value of the symbol @code{_main}, if present;
1659 the address of the first byte of the @code{.text} section, if present;
1661 The address @code{0}.
1664 For example, you can use these rules to generate an entry point with an
1665 assignment statement: if no symbol @code{start} is defined within your
1666 input files, you can simply define it, assigning it an appropriate
1673 The example shows an absolute address, but you can use any expression.
1674 For example, if your input object files use some other symbol-name
1675 convention for the entry point, you can just assign the value of
1676 whatever symbol contains the start address to @code{start}:
1678 start = other_symbol ;
1681 @node Other Commands
1682 @section Other Commands
1683 The command language includes a number of other commands that you can
1684 use for specialized purposes. They are similar in purpose to
1685 command-line options.
1692 These keywords were used in some older linkers to request a particular
1693 math subroutine library. @code{ld} doesn't use the keywords, assuming
1694 instead that any necessary subroutines are in libraries specified using
1695 the general mechanisms for linking to archives; but to permit the use of
1696 scripts that were written for the older linkers, the keywords
1697 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1699 @item FORCE_COMMON_ALLOCATION
1700 @kindex FORCE_COMMON_ALLOCATION
1701 @cindex common allocation
1702 This command has the same effect as the @samp{-d} command-line option:
1703 to make @code{ld} assign space to common symbols even if a relocatable
1704 output file is specified (@samp{-r}).
1706 @item INPUT ( @var{file}, @var{file}, @dots{} )
1707 @kindex INPUT ( @var{files} )
1708 @itemx INPUT ( @var{file} @var{file} @dots{} )
1709 @cindex binary input files
1710 Use this command to include binary input files in the link, without
1711 including them in a particular section definition. Files specified this
1712 way are treated identically to object files listed on the command line.
1715 @item MAP ( @var{name} )
1716 @kindex MAP ( @var{name} )
1717 @c MAP(...) appears to look for an F in the arg, ignoring all other
1718 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1719 @c checks map_option_f. Apparently a stub for the future...
1722 @item OUTPUT ( @var{filename} )
1723 @kindex OUTPUT ( @var{filename} )
1724 @cindex naming the output file
1725 Use this command to name the link output file @var{filename}. The
1726 effect of @code{OUTPUT(@var{filename})} is identical to the effect of
1727 @w{@samp{-o @var{filename}}}, and whichever is encountered last will
1728 control the name actually used to name the output file. In particular,
1729 you can use this command to supply a default output-file name other than
1732 @ifclear SingleFormat
1733 @item OUTPUT_ARCH ( @var{bfdname} )
1734 @kindex OUTPUT_ARCH ( @var{bfdname} )
1735 @cindex machine architecture, output
1736 Specify a particular output machine architecture, with one of the names
1737 used by the BFD back-end routines (@pxref{BFD}). This command is often
1738 unnecessary; the architecture is most often set implicitly by either the
1739 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1742 @item OUTPUT_FORMAT ( @var{bfdname} )
1743 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1744 @cindex format, output file
1745 Specify a particular output format, with one of the names used by the
1746 BFD back-end routines (@pxref{BFD}). This selection will only affect
1747 the output file; the related command @code{TARGET} affects primarily
1751 @item SEARCH_DIR ( @var{path} )
1752 @kindex SEARCH_DIR ( @var{path} )
1753 @cindex path for libraries
1754 @cindex search path, libraries
1755 Add @var{path} to the list of paths where @code{ld} looks for
1756 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1757 effect as @samp{-L@var{path}} on the command line.
1759 @item STARTUP ( @var{filename} )
1760 @kindex STARTUP ( @var{filename} )
1761 @cindex first input file
1762 Ensure that @var{filename} is the first input file used in the link
1765 @ifclear SingleFormat
1766 @item TARGET ( @var{format} )
1767 @cindex input file format
1768 @kindex TARGET ( @var{format} )
1769 Change the input-file object code format (like the command-line option
1770 @samp{-b} or its synonym @samp{-format}). The argument @var{format} is
1771 one of the strings used by BFD to name binary formats. In the current
1772 @code{ld} implementation, if @code{TARGET} is specified but
1773 @code{OUTPUT_FORMAT} is not, the last @code{TARGET} argument is also
1774 used as the default format for the @code{ld} output file.
1778 If you don't use the @code{TARGET} command, @code{ld} uses the value of
1779 the environment variable @code{GNUTARGET}, if available, to select the
1780 output file format. If that variable is also absent, @code{ld} uses
1781 the default format configured for your machine in the BFD libraries.
1786 @node Machine Dependent
1787 @chapter Machine Dependent Features
1789 @cindex machine dependencies
1790 @code{ld} has additional features on some platforms; the following
1791 sections describe them. Machines where @code{ld} has no additional
1792 functionality are not listed.
1795 * H8/300:: @code{ld} and the H8/300
1796 * i960:: @code{ld} and the Intel 960 family
1800 @c FIXME! This could use @up/@down, but there seems to be a conflict
1801 @c between those and node-defaulting.
1807 @section @code{ld} and the H8/300
1809 @cindex H8/300 support
1810 For the H8/300, @code{ld} can perform these global optimizations when
1811 you specify the @samp{-relax} command-line option.
1814 @item relaxing address modes
1815 @cindex relaxing on H8/300
1816 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
1817 targets are within eight bits, and turns them into eight-bit
1818 program-counter relative @code{bsr} and @code{bra} instructions,
1821 @item synthesizing instructions
1822 @cindex synthesizing on H8/300
1823 @c FIXME: specifically mov.b, or any mov instructions really?
1824 @code{ld} finds all @code{mov.b} instructions which use the
1825 sixteen-bit absolute address form, but refer to the top
1826 page of memory, and changes them to use the eight-bit address form.
1827 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1828 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1829 top page of memory).
1841 @section @code{ld} and the Intel 960 family
1843 @cindex i960 support
1845 You can use the @samp{-A@var{architecture}} command line option to
1846 specify one of the two-letter names identifying members of the 960
1847 family; the option specifies the desired output target, and warns of any
1848 incompatible instructions in the input files. It also modifies the
1849 linker's search strategy for archive libraries, to support the use of
1850 libraries specific to each particular architecture, by including in the
1851 search loop names suffixed with the string identifying the architecture.
1853 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
1854 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1855 paths, and in any paths you specify with @samp{-L}) for a library with
1866 The first two possibilities would be considered in any event; the last
1867 two are due to the use of @w{@samp{-ACA}}.
1869 You can meaningfully use @samp{-A} more than once on a command line, since
1870 the 960 architecture family allows combination of target architectures; each
1871 use will add another pair of name variants to search for when @w{@samp{-l}}
1872 specifies a library.
1878 @ifclear SingleFormat
1883 @cindex object file management
1884 The linker accesses object and archive files using the BFD libraries.
1885 These libraries allow the linker to use the same routines to operate on
1886 object files whatever the object file format. A different object file
1887 format can be supported simply by creating a new BFD back end and adding
1888 it to the library. You can use @code{objdump -i}
1889 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
1890 list all the formats available for each architecture under BFD. This
1891 was the list of formats, and of architectures supported for each format,
1892 as of the time this manual was prepared:
1893 @cindex formats available
1894 @cindex architectures available
1896 BFD header file version 0.18
1898 (header big endian, data big endian)
1904 (header big endian, data big endian)
1910 (header big endian, data little endian)
1913 (header little endian, data little endian)
1916 (header big endian, data big endian)
1919 (header big endian, data big endian)
1922 (header little endian, data little endian)
1925 (header big endian, data little endian)
1928 (header little endian, data little endian)
1931 (header big endian, data big endian)
1934 (header big endian, data big endian)
1937 (header big endian, data big endian)
1940 (header little endian, data little endian)
1943 (header big endian, data big endian)
1955 (header little endian, data little endian)
1967 (header big endian, data big endian)
1979 (header big endian, data big endian)
1992 @cindex BFD requirements
1993 @cindex requirements for BFD
1994 As with most implementations, BFD is a compromise between
1995 several conflicting requirements. The major factor influencing
1996 BFD design was efficiency: any time used converting between
1997 formats is time which would not have been spent had BFD not
1998 been involved. This is partly offset by abstraction payback; since
1999 BFD simplifies applications and back ends, more time and care
2000 may be spent optimizing algorithms for a greater speed.
2002 One minor artifact of the BFD solution which you should bear in
2003 mind is the potential for information loss. There are two places where
2004 useful information can be lost using the BFD mechanism: during
2005 conversion and during output. @xref{BFD information loss}.
2008 * BFD outline:: How it works: an outline of BFD
2009 * BFD information loss:: Information Loss
2010 * Mechanism:: Mechanism
2014 @section How it works: an outline of BFD
2015 @cindex opening object files
2016 @include ../bfd/doc/bfdsumm.texi
2020 @appendix MRI Compatible Script Files
2021 @cindex MRI compatibility
2022 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
2023 linker, @code{ld} can use MRI compatible linker scripts as an
2024 alternative to the more general-purpose linker scripting language
2025 described in @ref{Commands,,Command Language}. MRI compatible linker
2026 scripts have a much simpler command set than the scripting language
2027 otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
2028 commonly used MRI linker commands; these commands are described here.
2030 You can specify a file containing an MRI-compatible script using the
2031 @samp{-c} command-line option.
2033 Each command in an MRI-compatible script occupies its own line; each
2034 command line starts with the keyword that identifies the command (though
2035 blank lines are also allowed for punctuation). If a line of an
2036 MRI-compatible script begins with an unrecognized keyword, @code{ld}
2037 issues a warning message, but continues processing the script.
2039 Lines beginning with @samp{*} are comments.
2041 You can write these commands using all upper-case letters, or all
2042 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
2043 The following list shows only the upper-case form of each command.
2046 @item ABSOLUTE @var{secname}
2047 @item ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
2048 @cindex @code{ABSOLUTE} (MRI)
2049 Normally, @code{ld} includes in the output file all sections from all
2050 the input files. However, in an MRI-compatible script, you can use the
2051 @code{ABSOLUTE} command to restrict the sections that will be present in
2052 your output program. If the @code{ABSOLUTE} command is used at all in a
2053 script, then only the sections named explicitly in @code{ABSOLUTE}
2054 commands will appear in the linker output. You can still use other
2055 input sections (whatever you select on the command line, or using
2056 @code{LOAD}) to resolve addresses in the output file.
2058 @item ALIAS @var{out-secname}, @var{in-secname}
2059 @cindex @code{ALIAS} (MRI)
2060 Use this command to place the data from input section @var{in-secname}
2061 in a section called @var{out-secname} in the linker output file.
2063 @var{in-secname} may be an integer.
2065 @item BASE @var{expression}
2066 @cindex @code{BASE} (MRI)
2067 Use the value of @var{expression} as the lowest address (other than
2068 absolute addresses) in the output file.
2070 @item CHIP @var{expression}
2071 @itemx CHIP @var{expression}, @var{expression}
2072 @cindex @code{CHIP} (MRI)
2073 This command does nothing; it is accepted only for compatibility.
2076 @cindex @code{END} (MRI)
2077 This command does nothing whatever; it's only accepted for compatibility.
2079 @item FORMAT @var{output-format}
2080 @cindex @code{FORMAT} (MRI)
2081 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
2082 language, but restricted to one of these output formats:
2085 S-records, if @var{output-format} is @samp{S}
2088 IEEE, if @var{output-format} is @samp{IEEE}
2091 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
2095 @item LIST @var{anything}@dots{}
2096 @cindex @code{LIST} (MRI)
2097 Print (to the standard output file) a link map, as produced by the
2098 @code{ld} command-line option @samp{-M}.
2100 The keyword @code{LIST} may be followed by anything on the
2101 same line, with no change in its effect.
2103 @item LOAD @var{filename}
2104 @item LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
2105 @cindex @code{LOAD} (MRI)
2106 Include one or more object file @var{filename} in the link; this has the
2107 same effect as specifying @var{filename} directly on the @code{ld}
2110 @item NAME @var{output-name}
2111 @cindex @code{NAME} (MRI)
2112 @var{output-name} is the name for the program produced by @code{ld}; the
2113 MRI-compatible command @code{NAME} is equivalent to the command-line
2114 option @samp{-o} or the general script language command @code{OUTPUT}.
2116 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
2117 @itemx ORDER @var{secname} @var{secname} @var{secname}
2118 @cindex @code{ORDER} (MRI)
2119 Normally, @code{ld} orders the sections in its output file in the
2120 order in which they first appear in the input files. In an MRI-compatible
2121 script, you can override this ordering with the @code{ORDER} command. The
2122 sections you list with @code{ORDER} will appear first in your output
2123 file, in the order specified.
2125 @item PUBLIC @var{name}=@var{expression}
2126 @itemx PUBLIC @var{name},@var{expression}
2127 @itemx PUBLIC @var{name} @var{expression}
2128 @cindex @code{PUBLIC} (MRI)
2129 Supply a value (@var{expression}) for external symbol
2130 @var{name} used in the linker input files.
2132 @item SECT @var{secname}, @var{expression}
2133 @itemx SECT @var{secname}=@var{expression}
2134 @itemx SECT @var{secname} @var{expression}
2135 @cindex @code{SECT} (MRI)
2136 You can use any of these three forms of the @code{SECT} command to
2137 specify the start address (@var{expression}) for section @var{secname}.
2138 If you have more than one @code{SECT} statement for the same
2139 @var{secname}, only the @emph{first} sets the start address.
2149 % I think something like @colophon should be in texinfo. In the
2151 \long\def\colophon{\hbox to0pt{}\vfill
2152 \centerline{The body of this manual is set in}
2153 \centerline{\fontname\tenrm,}
2154 \centerline{with headings in {\bf\fontname\tenbf}}
2155 \centerline{and examples in {\tt\fontname\tentt}.}
2156 \centerline{{\it\fontname\tenit\/} and}
2157 \centerline{{\sl\fontname\tensl\/}}
2158 \centerline{are used for emphasis.}\vfill}
2160 % Blame: pesch@cygnus.com, 28mar91.