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.
231 @cindex architectures
233 @item -A@var{architecture}
234 In the current release of @code{ld}, this option is useful only for the
235 Intel 960 family of architectures. In that @code{ld} configuration, the
236 @var{architecture} argument identifies the particular architecture in
237 the 960 family, enabling some safeguards and modifying the
238 archive-library search path. @xref{i960,,@code{ld} and the Intel 960
239 family}, for details.
241 Future releases of @code{ld} may support similar functionality for
242 other architecture families.
245 @ifclear SingleFormat
246 @cindex binary input format
247 @kindex -b @var{format}
249 @item -b @var{input-format}
251 Specify the binary format for input object files that follow this option
252 on the command line. You don't usually need to specify this, as
253 @code{ld} is configured to expect as a default input format the most
254 usual format on each machine. @var{input-format} is a text string, the
255 name of a particular format supported by the BFD libraries.
256 (You can list the available binary formats with @samp{objdump -i}.)
257 @w{@samp{-format @var{input-format}}} has the same effect, as does the
258 script command @code{TARGET}. @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.
362 Print a summary of the command-line options on the standard output and exit.
363 This option and @samp{--version} begin with two dashes instead of one
364 for compatibility with other GNU programs. The other options start with
365 only one dash for compatibility with other linkers.
368 @cindex incremental link
370 Perform an incremental link (same as option @samp{-r}).
372 @cindex archive files, from cmd line
373 @kindex -l@var{archive}
375 Add archive file @var{archive} to the list of files to link. This
376 option may be used any number of times. @code{ld} will search its
377 path-list for occurrences of @code{lib@var{ar}.a} for every @var{archive}
380 @cindex search directory, from cmd line
382 @item -L@var{searchdir}
383 Add path @var{searchdir} to the list of paths that @code{ld} will search
384 for archive libraries and @code{ld} control scripts. You may use this
385 option any number of times.
388 The default set of paths searched (without being specified with
389 @samp{-L}) depends on which emulation mode @code{ld} is using, and in
390 some cases also on how it was configured. @xref{Environment}.
393 The paths can also be specified in a link script with the
394 @code{SEARCH_DIR} command.
399 Print (to the standard output) a link map---diagnostic information
400 about where symbols are mapped by @code{ld}, and information on global
401 common storage allocation.
405 @item -Map @var{mapfile}
406 Print to the file @var{mapfile} a link map---diagnostic information
407 about where symbols are mapped by @code{ld}, and information on global
408 common storage allocation.
411 @kindex -m @var{emulation}
412 @item -m@var{emulation}
413 @itemx -m @var{emulation}
414 Emulate the @var{emulation} linker. You can list the available
415 emulations with the @samp{-V} option. The
416 default is the system for which you configured @code{ld}.
419 @cindex read/write from cmd line
422 Set the text and data sections to be readable and writable. Also, do
423 not page-align the data segment. If the output format supports Unix
424 style magic numbers, mark the output as @code{OMAGIC}.
428 @cindex read-only text
430 Set the text segment to be read only, and mark the output as
431 @code{NMAGIC} if possible.
433 @item -noinhibit-exec
434 @cindex output file after errors
435 @kindex -noinhibit-exec
436 Retain the executable output file whenever it is still usable.
437 Normally, the linker will not produce an output file if it encounters
438 errors during the link process; it exits without writing an output file
439 when it issues any error whatsoever.
441 @item -o @var{output}
442 @kindex -o @var{output}
443 @cindex naming the output file
444 Use @var{output} as the name for the program produced by @code{ld}; if this
445 option is not specified, the name @file{a.out} is used by default. The
446 script command @code{OUTPUT} can also specify the output file name.
449 @item -oformat @var{output-format}
450 Specify the binary format for the output object file. You don't usually
451 need to specify this, as @code{ld} is configured to produce as a default
452 output format the most usual format on each machine.
453 @var{output-format} is a text string, the name of a particular format
454 supported by the BFD libraries. (You can list the available binary
455 formats with @samp{objdump -i}.) The script command
456 @code{OUTPUT_FORMAT} can also specify the output format, but this option
457 overrides it. @xref{BFD}.
459 @item -R @var{filename}
460 @kindex -R @var{file}
461 @cindex symbol-only input
462 On some platforms, this option performs global optimizations
463 that become possible when the linker resolves addressing in the
464 program, such as relaxing address modes and synthesizing new
465 instructions in the output object file.
469 @cindex synthesizing linker
470 @cindex relaxing addressing modes
471 An option with machine dependent effects. Currently this option is only
472 supported on the H8/300.
474 @xref{H8/300,,@code{ld} and the H8/300}.
477 On some platforms, use option performs global optimizations that
478 become possible when the linker resolves addressing in the program, such
479 as relaxing address modes and synthesizing new instructions in the
482 On platforms where this is not supported, @samp{-relax} is accepted, but
487 @cindex relocatable output
489 Generate relocatable output---i.e., generate an output file that can in
490 turn serve as input to @code{ld}. This is often called @dfn{partial
491 linking}. As a side effect, in environments that support standard Unix
492 magic numbers, this option also sets the output file's magic number to
495 If this option is not specified, an absolute file is produced. When
496 linking C++ programs, this option @emph{will not} resolve references to
497 constructors; to do that, use @samp{-Ur}.
499 This option does the same as @code{-i}.
503 @cindex strip debugger symbols
504 Omit debugger symbol information (but not all symbols) from the output file.
508 @cindex strip all symbols
509 Omit all symbol information from the output file.
511 @item -Tbss @var{bssorg}
512 @kindex -Tbss @var{bssorg}
513 @itemx -Tdata @var{dataorg}
514 @kindex -Tdata @var{dataorg}
515 @itemx -Ttext @var{textorg}
516 @kindex -Ttext @var{textorg}
517 @cindex segment origins, cmd line
518 Use @var{org} as the starting address for---respectively---the
519 @code{bss}, @code{data}, or the @code{text} segment of the output file.
520 @var{org} must be a single hexadecimal integer;
521 for compatibility with other linkers, you may omit the leading
522 @samp{0x} usually associated with hexadecimal values.
524 @item -T @var{commandfile}
525 @itemx -T@var{commandfile}
526 @kindex -T @var{script}
528 Read link commands from the file @var{commandfile}. These commands
529 completely override @code{ld}'s default link format (rather than adding
530 to it); @var{commandfile} must specify everything necessary to describe
531 the target format. @xref{Commands}. If @var{commandfile} does not
532 exist, @code{ld} looks for it in the directories specified by any
533 preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
538 @cindex input files, displaying
539 Print the names of the input files as @code{ld} processes them.
541 @item -u @var{symbol}
542 @kindex -u @var{symbol}
543 @cindex undefined symbol
544 Force @var{symbol} to be entered in the output file as an undefined symbol.
545 Doing this may, for example, trigger linking of additional modules from
546 standard libraries. @samp{-u} may be repeated with different option
547 arguments to enter additional undefined symbols.
548 @c Nice idea, but no such command: This option is equivalent
549 @c to the @code{EXTERN} linker command.
554 For anything other than C++ programs, this option is equivalent to
555 @samp{-r}: it generates relocatable output---i.e., an output file that can in
556 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
557 @emph{will} resolve references to constructors, unlike @samp{-r}.
558 It does not work to use @samp{-Ur} on files that were themselves linked
559 with @samp{-Ur}; once the constructor table has been built, it can not
560 be added to. Use @samp{-Ur} only for the last partial link, and
561 @samp{-r} for the others.
566 Display the version number for @code{ld} and list the supported emulations.
567 Display which input files can and can not be opened.
572 Display the version number for @code{ld}.
576 Display the version number for @code{ld} and exit.
580 @cindex local symbols, deleting
581 @cindex L, deleting symbols beginning
582 If @samp{-s} or @samp{-S} is also specified, delete only local symbols
583 beginning with @samp{L}.
587 @cindex deleting local symbols
588 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
589 not just those beginning with @samp{L}.
592 @kindex -y@var{symbol}
593 @cindex symbol tracing
594 Print the name of each linked file in which @var{symbol} appears. This
595 option may be given any number of times. On many systems it is necessary
596 to prepend an underscore.
598 This option is useful when you have an undefined symbol in your link but
599 don't know where the reference is coming from.
604 @section Environment Variables
606 You can change the behavior of @code{ld} with the environment
607 variable @code{GNUTARGET}.
610 @cindex default input format
611 @code{GNUTARGET} determines the input-file object format if you don't
612 use @samp{-b} (or its synonym @samp{-format}). Its value should be one
613 of the BFD names for an input format (@pxref{BFD}). If there is no
614 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
615 of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
616 input format by examining binary input files; this method often
617 succeeds, but there are potential ambiguities, since there is no method
618 of ensuring that the magic number used to specify object-file formats is
619 unique. However, the configuration procedure for BFD on each system
620 places the conventional format for that system first in the search-list,
621 so ambiguities are resolved in favor of convention.
625 @chapter Command Language
627 @cindex command files
628 The command language provides explicit control over the link process,
629 allowing complete specification of the mapping between the linker's
630 input files and its output. It controls:
639 addresses of sections
641 placement of common blocks
644 You may supply a command file (also known as a link script) to the
645 linker either explicitly through the @samp{-T} option, or implicitly as
646 an ordinary file. If the linker opens a file which it cannot recognize
647 as a supported object or archive format, it tries to interpret the file
651 * Scripts:: Linker Scripts
652 * Expressions:: Expressions
653 * MEMORY:: MEMORY Command
654 * SECTIONS:: SECTIONS Command
655 * Entry Point:: The Entry Point
656 * Other Commands:: Other Commands
660 @section Linker Scripts
661 The @code{ld} command language is a collection of statements; some are
662 simple keywords setting a particular option, some are used to select and
663 group input files or name output files; and two statement
664 types have a fundamental and pervasive impact on the linking process.
666 @cindex fundamental script commands
667 @cindex commands, fundamental
668 @cindex output file layout
669 @cindex layout of output file
670 The most fundamental command of the @code{ld} command language is the
671 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
672 script must have a @code{SECTIONS} command: it specifies a
673 ``picture'' of the output file's layout, in varying degrees of detail.
674 No other command is required in all cases.
676 The @code{MEMORY} command complements @code{SECTIONS} by describing the
677 available memory in the target architecture. This command is optional;
678 if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
679 memory is available in a contiguous block for all output.
683 You may include comments in linker scripts just as in C: delimited
684 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
685 equivalent to whitespace.
689 @cindex expression syntax
691 Many useful commands involve arithmetic expressions. The syntax for
692 expressions in the command language is identical to that of C
693 expressions, with the following features:
696 All expressions evaluated as integers and
697 are of ``long'' or ``unsigned long'' type.
699 All constants are integers.
701 All of the C arithmetic operators are provided.
703 You may reference, define, and create global variables.
705 You may call special purpose built-in functions.
709 * Integers:: Integers
710 * Symbols:: Symbol Names
711 * Location Counter:: The Location Counter
712 * Operators:: Operators
713 * Evaluation:: Evaluation
714 * Assignment:: Assignment: Defining Symbols
715 * Built-ins:: Built-In Functions
720 @cindex integer notation
721 @cindex octal integers
722 An octal integer is @samp{0} followed by zero or more of the octal
723 digits (@samp{01234567}).
728 @cindex decimal integers
729 A decimal integer starts with a non-zero digit followed by zero or
730 more digits (@samp{0123456789}).
735 @cindex hexadecimal integers
737 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
738 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
743 @cindex negative integers
744 To write a negative integer, use
745 the prefix operator @samp{-}; @pxref{Operators}.
750 @cindex scaled integers
751 @cindex K and M integer suffixes
752 @cindex M and K integer suffixes
753 @cindex suffixes for integers
754 @cindex integer suffixes
755 Additionally the suffixes @code{K} and @code{M} may be used to scale a
759 @c END TEXI2ROFF-KILL
760 @code{1024} or @code{1024*1024}
764 ${\rm 1024}$ or ${\rm 1024}^2$
766 @c END TEXI2ROFF-KILL
767 respectively. For example, the following all refer to the same quantity:
776 @subsection Symbol Names
779 @cindex quoted symbol names
781 Unless quoted, symbol names start with a letter, underscore, point or
782 hyphen and may include any letters, underscores, digits, points,
783 and minus signs. Unquoted symbol names must not conflict with any
784 keywords. You can specify a symbol which contains odd characters or has
785 the same name as a keyword, by surrounding the symbol name in double quotes:
788 "with a space" = "also with a space" + 10;
791 @node Location Counter
792 @subsection The Location Counter
795 @cindex location counter
796 @cindex current output location
797 The special linker variable @dfn{dot} @samp{.} always contains the
798 current output location counter. Since the @code{.} always refers to
799 a location in an output section, it must always appear in an
800 expression within a @code{SECTIONS} command. The @code{.} symbol
801 may appear anywhere that an ordinary symbol is allowed in an
802 expression, but its assignments have a side effect. Assigning a value
803 to the @code{.} symbol will cause the location counter to be moved.
805 This may be used to create holes in the output section. The location
806 counter may never be moved backwards.
821 In the previous example, @code{file1} is located at the beginning of the
822 output section, then there is a 1000 byte gap. Then @code{file2}
823 appears, also with a 1000 byte gap following before @code{file3} is
824 loaded. The notation @samp{= 0x1234} specifies what data to write in
825 the gaps (@pxref{Section Options}).
828 @subsection Operators
829 @cindex Operators for arithmetic
830 @cindex arithmetic operators
831 @cindex precedence in expressions
832 The linker recognizes the standard C set of arithmetic operators, with
833 the standard bindings and precedence levels:
836 @c END TEXI2ROFF-KILL
838 precedence associativity Operators Notes
844 5 left == != > < <= >=
850 11 right &= += -= *= /= (2)
855 (2) @xref{Assignment}
860 %"lispnarrowing" is the extra indent used generally for @example
861 \hskip\lispnarrowing\vbox{\offinterlineskip
864 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
865 height2pt&\omit&&\omit&&\omit&\cr
866 &Precedence&& Associativity &&{\rm Operators}&\cr
867 height2pt&\omit&&\omit&&\omit&\cr
869 height2pt&\omit&&\omit&&\omit&\cr
871 % '176 is tilde, '~' in tt font
872 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
876 &5&&left&&== != > < <= >=&\cr
882 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
884 height2pt&\omit&&\omit&&\omit&\cr}
889 @obeylines@parskip=0pt@parindent=0pt
890 @dag@quad Prefix operators.
891 @ddag@quad @xref{Assignment}.
894 @c END TEXI2ROFF-KILL
897 @subsection Evaluation
899 @cindex lazy evaluation
900 @cindex expression evaluation order
901 The linker uses ``lazy evaluation'' for expressions; it only calculates
902 an expression when absolutely necessary. The linker needs the value of
903 the start address, and the lengths of memory regions, in order to do any
904 linking at all; these values are computed as soon as possible when the
905 linker reads in the command file. However, other values (such as symbol
906 values) are not known or needed until after storage allocation. Such
907 values are evaluated later, when other information (such as the sizes of
908 output sections) is available for use in the symbol assignment
912 @subsection Assignment: Defining Symbols
913 @cindex assignment in scripts
914 @cindex symbol definition, scripts
915 @cindex variables, defining
916 You may create global symbols, and assign values (addresses) to global
917 symbols, using any of the C assignment operators:
920 @item @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} ;
925 @itemx @var{symbol} /= @var{expression} ;
928 Two things distinguish assignment from other operators in @code{ld}
932 Assignment may only be used at the root of an expression;
933 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
938 You must place a trailing semicolon (``@key{;}'') at the end of an
939 assignment statement.
942 Assignment statements may appear:
945 as commands in their own right in an @code{ld} script; or
947 as independent statements within a @code{SECTIONS} command; or
949 as part of the contents of a section definition in a
950 @code{SECTIONS} command.
953 The first two cases are equivalent in effect---both define a symbol with
954 an absolute address. The last case defines a symbol whose address is
955 relative to a particular section (@pxref{SECTIONS}).
957 @cindex absolute and relocatable symbols
958 @cindex relocatable and absolute symbols
959 @cindex symbols, relocatable and absolute
960 When a linker expression is evaluated and assigned to a variable, it is
961 given either an absolute or a relocatable type. An absolute expression
962 type is one in which the symbol contains the value that it will have in
963 the output file, a relocatable expression type is one in which the
964 value is expressed as a fixed offset from the base of a section.
966 The type of the expression is controlled by its position in the script
967 file. A symbol assigned within a section definition is created relative
968 to the base of the section; a symbol assigned in any other place is
969 created as an absolute symbol. Since a symbol created within a
970 section definition is relative to the base of the section, it
971 will remain relocatable if relocatable output is requested. A symbol
972 may be created with an absolute value even when assigned to within a
973 section definition by using the absolute assignment function
974 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
975 is the last byte of an output section named @code{.data}:
981 _edata = ABSOLUTE(.) ;
986 The linker tries to put off the evaluation of an assignment until all
987 the terms in the source expression are known (@pxref{Evaluation}). For
988 instance, the sizes of sections cannot be known until after allocation,
989 so assignments dependent upon these are not performed until after
990 allocation. Some expressions, such as those depending upon the location
991 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
992 result of an expression is required, but the value is not available,
993 then an error results. For example, a script like the following
996 text 9+this_isnt_constant :
1001 @kindex Non constant expression
1003 will cause the error message ``@code{Non constant expression for initial
1007 @subsection Built-In Functions
1008 @cindex functions in expression language
1009 The command language includes a number of built-in
1010 functions for use in link script expressions.
1012 @item ABSOLUTE(@var{exp})
1013 @kindex ABSOLUTE(@var{exp})
1014 @cindex expression, absolute
1015 Return the absolute (non-relocatable, as opposed to non-negative) value
1016 of the expression @var{exp}. Primarily useful to assign an absolute
1017 value to a symbol within a section definition, where symbol values are
1018 normally section-relative.
1020 @item ADDR(@var{section})
1021 @kindex ADDR(@var{section})
1022 @cindex section address
1023 Return the absolute address of the named @var{section}. Your script must
1024 previously have defined the location of that section. In the following
1025 example, @code{symbol_1} and @code{symbol_2} are assigned identical
1031 start_of_output_1 = ABSOLUTE(.);
1036 symbol_1 = ADDR(.output1);
1037 symbol_2 = start_of_output_1;
1042 @item ALIGN(@var{exp})
1043 @kindex ALIGN(@var{exp})
1044 @cindex rounding up location counter
1045 Return the result of the current location counter (@code{.}) aligned to
1046 the next @var{exp} boundary. @var{exp} must be an expression whose
1047 value is a power of two. This is equivalent to
1049 (. + @var{exp} - 1) & ~(@var{exp} - 1)
1052 @code{ALIGN} doesn't change the value of the location counter---it just
1053 does arithmetic on it. As an example, to align the output @code{.data}
1054 section to the next @code{0x2000} byte boundary after the preceding
1055 section and to set a variable within the section to the next
1056 @code{0x8000} boundary after the input sections:
1059 .data ALIGN(0x2000): @{
1061 variable = ALIGN(0x8000);
1066 The first use of @code{ALIGN} in this example specifies the location of
1067 a section because it is used as the optional @var{start} attribute of a
1068 section definition (@pxref{Section Options}). The second use simply
1069 defines the value of a variable.
1071 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1073 @item DEFINED(@var{symbol})
1074 @kindex DEFINED(@var{symbol})
1075 @cindex symbol defaults
1076 Return 1 if @var{symbol} is in the linker global symbol table and is
1077 defined, otherwise return 0. You can use this function to provide default
1078 values for symbols. For example, the following command-file fragment shows how
1079 to set a global symbol @code{begin} to the first location in the
1080 @code{.text} section---but if a symbol called @code{begin} already
1081 existed, its value is preserved:
1085 begin = DEFINED(begin) ? begin : . ;
1091 @item NEXT(@var{exp})
1092 @kindex NEXT(@var{exp})
1093 @cindex unallocated address, next
1094 Return the next unallocated address that is a multiple of @var{exp}.
1095 This function is closely related to @code{ALIGN(@var{exp})}; unless you
1096 use the @code{MEMORY} command to define discontinuous memory for the
1097 output file, the two functions are equivalent.
1099 @item SIZEOF(@var{section})
1100 @kindex SIZEOF(@var{section})
1101 @cindex section size
1102 Return the size in bytes of the named @var{section}, if that section has
1103 been allocated. In the following example, @code{symbol_1} and
1104 @code{symbol_2} are assigned identical values:
1105 @c What does it return if the section hasn't been allocated? 0?
1113 symbol_1 = .end - .start ;
1114 symbol_2 = SIZEOF(.output);
1119 @item SIZEOF_HEADERS
1120 @kindex SIZEOF_HEADERS
1122 @itemx sizeof_headers
1123 @kindex sizeof_headers
1124 Return the size in bytes of the output file's headers. You can use this number
1125 as the start address of the first section, if you choose, to facilitate
1131 @section MEMORY Command
1133 @cindex regions of memory
1134 @cindex discontinuous memory
1135 @cindex allocating memory
1136 The linker's default configuration permits allocation of all available memory.
1137 You can override this configuration by using the @code{MEMORY} command. The
1138 @code{MEMORY} command describes the location and size of blocks of
1139 memory in the target. By using it carefully, you can describe which
1140 memory regions may be used by the linker, and which memory regions it
1141 must avoid. The linker does not shuffle sections to fit into the
1142 available regions, but does move the requested sections into the correct
1143 regions and issue errors when the regions become too full.
1145 The command files may contain at most one use of the @code{MEMORY}
1146 command; however, you can define as many blocks of memory within it as
1147 you wish. The syntax is:
1152 @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
1158 @cindex naming memory regions
1159 is a name used internally by the linker to refer to the region. Any
1160 symbol name may be used. The region names are stored in a separate
1161 name space, and will not conflict with symbols, file names or section
1162 names. Use distinct names to specify multiple regions.
1164 @cindex memory region attributes
1165 is an optional list of attributes, permitted for compatibility with the
1166 AT&T linker but not used by @code{ld} beyond checking that the
1167 attribute list is valid. Valid attribute lists must be made up of the
1168 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1169 omit the parentheses around it as well.
1174 is the start address of the region in physical memory. It is
1175 an expression that must evaluate to a constant before
1176 memory allocation is performed. The keyword @code{ORIGIN} may be
1177 abbreviated to @code{org} or @code{o}.
1182 is the size in bytes of the region (an expression).
1183 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1186 For example, to specify that memory has two regions available for
1187 allocation---one starting at 0 for 256 kilobytes, and the other
1188 starting at @code{0x40000000} for four megabytes:
1193 rom : ORIGIN = 0, LENGTH = 256K
1194 ram : org = 0x40000000, l = 4M
1198 Once you have defined a region of memory named @var{mem}, you can direct
1199 specific output sections there by using a command ending in
1200 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1201 Options}). If the combined output sections directed to a region are too
1202 big for the region, the linker will issue an error message.
1205 @section SECTIONS Command
1207 The @code{SECTIONS} command controls exactly where input sections are
1208 placed into output sections, their order and to which output sections
1211 You may use at most one @code{SECTIONS} command in a commands file,
1212 but you can have as many statements within it as you wish. Statements
1213 within the @code{SECTIONS} command can do one of three things:
1216 define the entry point;
1218 assign a value to a symbol;
1220 describe the placement of a named output section, and what input
1221 sections make it up.
1224 The first two possibilities---defining the entry point, and defining
1225 symbols---can also be done outside the @code{SECTIONS} command:
1226 @pxref{Entry Point}, @pxref{Assignment}. They are permitted here as
1227 well for your convenience in reading the script, so that symbols or the
1228 entry point can be defined at meaningful points in your output-file
1231 When no @code{SECTIONS} command is specified, the default action
1232 of the linker is to place each input section into an identically named
1233 output section in the order that the sections are first encountered in
1234 the input files; if all input sections are present in the first file,
1235 for example, the order of sections in the output file will match the
1236 order in the first input file.
1239 * Section Definition:: Section Definitions
1240 * Section Contents:: Section Contents
1241 * Section Options:: Optional Section Attributes
1244 @node Section Definition
1245 @subsection Section Definitions
1246 @cindex section definition
1247 The most frequently used statement in the @code{SECTIONS} command is
1248 the @dfn{section definition}, which you can use to specify the
1249 properties of an output section: its location, alignment, contents,
1250 fill pattern, and target memory region. Most of
1251 these specifications are optional; the simplest form of a section
1260 @cindex naming output sections
1262 @var{secname} is the name of the output section, and @var{contents} a
1263 specification of what goes there---for example, a list of input files or
1264 sections of input files. As you might assume, the whitespace shown is
1265 optional. You do need the colon @samp{:} and the braces @samp{@{@}},
1268 @var{secname} must meet the constraints of your output format. In
1269 formats which only support a limited number of sections, such as
1270 @code{a.out}, the name must be one of the names supported by the format
1271 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1272 @code{.bss}). If the output format supports any number of sections, but
1273 with numbers and not names (as is the case for Oasys), the name should be
1274 supplied as a quoted numeric string. A section name may consist of any
1275 sequence characters, but any name which does not conform to the standard
1276 @code{ld} symbol name syntax must be quoted.
1277 @xref{Symbols, , Symbol Names}.
1279 @node Section Contents
1280 @subsection Section Contents
1281 @cindex contents of a section
1282 In a section definition, you can specify the contents of an output section by
1283 listing particular object files, by listing particular input-file
1284 sections, or by a combination of the two. You can also place arbitrary
1285 data in the section, and define symbols relative to the beginning of the
1288 The @var{contents} of a section definition may include any of the
1289 following kinds of statement. You can include as many of these as you
1290 like in a single section definition, separated from one another by
1294 @item @var{filename}
1295 @kindex @var{filename}
1296 @cindex input files, section defn
1297 @cindex files, including in output sections
1298 You may simply name a particular input file to be placed in the current
1299 output section; @emph{all} sections from that file are placed in the
1300 current section definition. To specify a list of particular files by
1303 .data : @{ afile.o bfile.o cfile.o @}
1306 The example also illustrates that multiple statements can be included in
1307 the contents of a section definition, since each file name is a separate
1310 If the file name has already been mentioned in another section
1311 definition, with an explicit section name list, then only those sections
1312 which have not yet been allocated are used.
1314 @item @var{filename}( @var{section} )
1315 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1316 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1317 @kindex @var{filename}(@var{section})
1318 @cindex files and sections, section defn
1319 You can name one or more sections from your input files, for
1320 insertion in the current output section. If you wish to specify a list
1321 of input-file sections inside the parentheses, you may separate the
1322 section names by either commas or whitespace.
1324 @item * (@var{section})
1325 @itemx * (@var{section}, @var{section}, @dots{})
1326 @itemx * (@var{section} @var{section} @dots{}
1327 @cindex input sections to output section
1328 @kindex *(@var{section})
1329 Instead of explicitly naming particular input files in a link control
1330 script, you can refer to @emph{all} files from the @code{ld} command
1331 line: use @samp{*} instead of a particular file name before the
1332 parenthesized input-file section list.
1334 For example, to copy sections @code{1} through @code{4} from an Oasys file
1335 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1336 and @code{14} into the @code{.data} section:
1349 If you have already explicitly included some files by name, @samp{*}
1350 refers to all @emph{remaining} files---those whose places in the output
1351 file have not yet been defined.
1353 @item [ @var{section} ]
1354 @itemx [ @var{section}, @var{section}, @dots{} ]
1355 @itemx [ @var{section} @var{section} @dots{} ]
1356 @kindex [ @var{sections} ]
1357 This is an alternate notation to specify named sections from all
1358 unallocated input files; its effect is exactly the same as that of
1359 @samp{* (@var{section}@dots{})}
1361 @item @var{filename}@code{( COMMON )}
1364 @cindex uninitialized data
1365 @cindex commons in output
1366 Specify where in your output file to place uninitialized data
1367 with this notation. @code{*(COMMON)} by itself refers to all
1368 uninitialized data from all input files (so far as it is not yet
1369 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1370 from a particular file. Both are special cases of the general
1371 mechanisms for specifying where to place input-file sections:
1372 @code{ld} permits you to refer to uninitialized data as if it
1373 were in an input-file section named @code{COMMON}, regardless of the
1374 input file's format.
1377 For example, the following command script arranges the output file into
1378 three consecutive sections, named @code{.text}, @code{.data}, and
1379 @code{.bss}, taking the input for each from the correspondingly named
1380 sections of all the input files:
1383 .text : @{ *(.text) @}
1384 .data : @{ *(.data) @}
1385 .bss : @{ *(.bss) *(COMMON) @}
1389 The following example reads all of the sections from file @code{all.o}
1390 and places them at the start of output section @code{outputa} which
1391 starts at location @code{0x10000}. All of section @code{.input1} from
1392 file @code{foo.o} follows immediately, in the same output section. All
1393 of section @code{.input2} from @code{foo.o} goes into output section
1394 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1395 All of the remaining @code{.input1} and @code{.input2} sections from any
1396 files are written to output section @code{outputc}.
1418 There are still more kinds of statements permitted in the contents of
1419 output section definitions. The foregoing statements permitted you to
1420 arrange, in your output file, data originating from your input files.
1421 You can also place data directly in an output section from the link
1422 command script. Most of these additional statements involve
1423 expressions; @pxref{Expressions}. Although these statements are shown
1424 separately here for ease of presentation, no such segregation is needed
1425 within a section definition in the @code{SECTIONS} command; you can
1426 intermix them freely with any of the statements we've just described.
1429 @item CREATE_OBJECT_SYMBOLS
1430 @kindex CREATE_OBJECT_SYMBOLS
1431 @cindex input filename symbols
1432 @cindex filename symbols
1433 Create a symbol for each input file
1434 in the current section, set to the address of the first byte of
1435 data written from the input file. For instance, with @code{a.out}
1436 files it is conventional to have a symbol for each input file. You can
1437 accomplish this by defining the output @code{.text} section as follows:
1442 CREATE_OBJECT_SYMBOLS
1444 _etext = ALIGN(0x2000);
1450 If @code{objsym} is a file containing this script, and @code{a.o},
1451 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1452 contents like the following---
1462 @samp{ld -M sample a.o b.o c.o d.o} would create a map like this,
1463 containing symbols matching the object file names:
1465 00000000 A __DYNAMIC
1468 00002020 T _afunction
1471 00002038 T _bfunction
1474 00002050 T _cfunction
1477 00002068 T _dfunction
1487 @item @var{symbol} = @var{expression} ;
1488 @kindex @var{symbol} = @var{expression} ;
1489 @itemx @var{symbol} @var{f}= @var{expression} ;
1490 @kindex @var{symbol} @var{f}= @var{expression} ;
1491 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1492 refers to any of the operators @code{&= += -= *= /=} which combine
1493 arithmetic and assignment.
1495 @cindex assignment, in section defn
1496 When you assign a value to a symbol within a particular section
1497 definition, the value is relative to the beginning of the section
1498 (@pxref{Assignment}). If you write
1503 .data : @{ @dots{} rel = 14 ; @dots{} @}
1504 abs2 = 14 + ADDR(.data);
1508 @c FIXME: Try above example!
1510 @code{abs} and @code{rel} do not have the same value; @code{rel} has the
1511 same value as @code{abs2}.
1513 @item BYTE(@var{expression})
1514 @kindex BYTE(@var{expression})
1515 @itemx SHORT(@var{expression})
1516 @kindex SHORT(@var{expression})
1517 @itemx LONG(@var{expression})
1518 @kindex LONG(@var{expression})
1519 @cindex direct output
1520 By including one of these three statements in a section definition, you
1521 can explicitly place one, two, or four bytes (respectively) at the
1522 current address of that section.
1524 @ifclear SingleFormat
1525 Multiple-byte quantities are represented in whatever byte order is
1526 appropriate for the output file format (@pxref{BFD}).
1529 @item FILL(@var{expression})
1530 @kindex FILL(@var{expression})
1531 @cindex holes, filling
1532 @cindex unspecified memory
1533 Specifies the ``fill pattern'' for the current section. Any otherwise
1534 unspecified regions of memory within the section (for example, regions
1535 you skip over by assigning a new value to the location counter @samp{.})
1536 are filled with the two least significant bytes from the
1537 @var{expression} argument. A @code{FILL} statement covers memory
1538 locations @emph{after} the point it occurs in the section definition; by
1539 including more than one @code{FILL} statement, you can have different
1540 fill patterns in different parts of an output section.
1543 @node Section Options
1544 @subsection Optional Section Attributes
1545 @cindex section defn, full syntax
1546 Here is the full syntax of a section definition, including all the
1552 @var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : @{ @var{contents} @} =@var{fill} >@var{region}
1557 @var{secname} and @var{contents} are required. @xref{Section
1558 Definition}, and @pxref{Section Contents} for details on @var{contents}.
1559 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1560 @code{(NOLOAD)} @code{=@var{fill}}, and @code{>@var{region}}---are all
1565 @cindex start address, section
1566 @cindex section start
1567 @cindex section address
1568 You can force the output section to be loaded at a specified address by
1569 specifying @var{start} immediately following the section name.
1570 @var{start} can be represented as any expression. The following
1571 example generates section @var{output} at location
1576 output 0x40000000: @{
1583 @item BLOCK(@var{align})
1584 @kindex BLOCK(@var{align})
1585 @cindex section alignment
1586 @cindex aligning sections
1587 You can include @code{BLOCK()} specification to advance
1588 the location counter @code{.} prior to the beginning of the section, so
1589 that the section will begin at the specified alignment. @var{align} is
1594 @cindex prevent unnecessary loading
1595 Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
1596 each time it is accessed. For example, in the script sample below, the
1597 @code{ROM} segment is addressed at memory location @samp{0} and does not
1598 need to be loaded into each object file:
1601 ROM 0 (NOLOAD) : @{ @dots{} @}
1608 @cindex section fill pattern
1609 @cindex fill pattern, entire section
1611 @code{=@var{fill}} in a section definition specifies the initial fill
1612 value for that section.
1613 You may use any expression to specify @var{fill}.
1614 Any unallocated holes in the current output
1615 section when written to the output file will be filled with the two
1616 least significant bytes of the value, repeated as necessary. You can
1617 also change the fill value with a @code{FILL} statement in the
1618 @var{contents} of a section definition.
1621 @kindex >@var{region}
1622 @cindex section, assigning to memory region
1623 @cindex memory regions and sections
1624 Assign this section to a previously defined region of memory.
1630 @section The Entry Point
1631 @kindex ENTRY(@var{symbol})
1632 @cindex start of execution
1633 @cindex first instruction
1634 The linker command language includes a command specifically for
1635 defining the first executable instruction in an output file (its
1636 @dfn{entry point}). Its argument is a symbol name:
1641 Like symbol assignments, the @code{ENTRY} command may be placed either
1642 as an independent command in the command file, or among the section
1643 definitions within the @code{SECTIONS} command---whatever makes the most
1644 sense for your layout.
1646 @cindex entry point, defaults
1647 @code{ENTRY} is only one of several ways of choosing the entry point.
1648 You may indicate it in any of the following ways (shown in descending
1649 order of priority: methods higher in the list override methods lower down).
1652 the @samp{-e} @var{entry} command-line option;
1654 the @code{ENTRY(@var{symbol}} command in a linker control script;
1656 the value of the symbol @code{start}, if present;
1658 the value of the symbol @code{_main}, if present;
1660 the address of the first byte of the @code{.text} section, if present;
1662 The address @code{0}.
1665 For example, you can use these rules to generate an entry point with an
1666 assignment statement: if no symbol @code{start} is defined within your
1667 input files, you can simply define it, assigning it an appropriate
1674 The example shows an absolute address, but you can use any expression.
1675 For example, if your input object files use some other symbol-name
1676 convention for the entry point, you can just assign the value of
1677 whatever symbol contains the start address to @code{start}:
1679 start = other_symbol ;
1682 @node Other Commands
1683 @section Other Commands
1684 The command language includes a number of other commands that you can
1685 use for specialized purposes. They are similar in purpose to
1686 command-line options.
1693 These keywords were used in some older linkers to request a particular
1694 math subroutine library. @code{ld} doesn't use the keywords, assuming
1695 instead that any necessary subroutines are in libraries specified using
1696 the general mechanisms for linking to archives; but to permit the use of
1697 scripts that were written for the older linkers, the keywords
1698 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1700 @item FORCE_COMMON_ALLOCATION
1701 @kindex FORCE_COMMON_ALLOCATION
1702 @cindex common allocation
1703 This command has the same effect as the @samp{-d} command-line option:
1704 to make @code{ld} assign space to common symbols even if a relocatable
1705 output file is specified (@samp{-r}).
1707 @item INPUT ( @var{file}, @var{file}, @dots{} )
1708 @kindex INPUT ( @var{files} )
1709 @itemx INPUT ( @var{file} @var{file} @dots{} )
1710 @cindex binary input files
1711 Use this command to include binary input files in the link, without
1712 including them in a particular section definition. Files specified this
1713 way are treated identically to object files listed on the command line.
1716 @item MAP ( @var{name} )
1717 @kindex MAP ( @var{name} )
1718 @c MAP(...) appears to look for an F in the arg, ignoring all other
1719 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1720 @c checks map_option_f. Apparently a stub for the future...
1723 @item OUTPUT ( @var{filename} )
1724 @kindex OUTPUT ( @var{filename} )
1725 @cindex naming the output file
1726 Use this command to name the link output file @var{filename}. The
1727 effect of @code{OUTPUT(@var{filename})} is identical to the effect of
1728 @w{@samp{-o @var{filename}}}, and whichever is encountered last will
1729 control the name actually used to name the output file. In particular,
1730 you can use this command to supply a default output-file name other than
1733 @ifclear SingleFormat
1734 @item OUTPUT_ARCH ( @var{bfdname} )
1735 @kindex OUTPUT_ARCH ( @var{bfdname} )
1736 @cindex machine architecture, output
1737 Specify a particular output machine architecture, with one of the names
1738 used by the BFD back-end routines (@pxref{BFD}). This command is often
1739 unnecessary; the architecture is most often set implicitly by either the
1740 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1743 @item OUTPUT_FORMAT ( @var{bfdname} )
1744 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1745 @cindex format, output file
1746 Specify a particular output format, with one of the names used by the
1747 BFD back-end routines (@pxref{BFD}). This selection will only affect
1748 the output file; the related command @code{TARGET} affects primarily
1752 @item SEARCH_DIR ( @var{path} )
1753 @kindex SEARCH_DIR ( @var{path} )
1754 @cindex path for libraries
1755 @cindex search path, libraries
1756 Add @var{path} to the list of paths where @code{ld} looks for
1757 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1758 effect as @samp{-L@var{path}} on the command line.
1760 @item STARTUP ( @var{filename} )
1761 @kindex STARTUP ( @var{filename} )
1762 @cindex first input file
1763 Ensure that @var{filename} is the first input file used in the link
1766 @ifclear SingleFormat
1767 @item TARGET ( @var{format} )
1768 @cindex input file format
1769 @kindex TARGET ( @var{format} )
1770 Change the input-file object code format (like the command-line option
1771 @samp{-b} or its synonym @samp{-format}). The argument @var{format} is
1772 one of the strings used by BFD to name binary formats. In the current
1773 @code{ld} implementation, if @code{TARGET} is specified but
1774 @code{OUTPUT_FORMAT} is not, the last @code{TARGET} argument is also
1775 used as the default format for the @code{ld} output file.
1779 If you don't use the @code{TARGET} command, @code{ld} uses the value of
1780 the environment variable @code{GNUTARGET}, if available, to select the
1781 output file format. If that variable is also absent, @code{ld} uses
1782 the default format configured for your machine in the BFD libraries.
1787 @node Machine Dependent
1788 @chapter Machine Dependent Features
1790 @cindex machine dependencies
1791 @code{ld} has additional features on some platforms; the following
1792 sections describe them. Machines where @code{ld} has no additional
1793 functionality are not listed.
1796 * H8/300:: @code{ld} and the H8/300
1797 * i960:: @code{ld} and the Intel 960 family
1801 @c FIXME! This could use @up/@down, but there seems to be a conflict
1802 @c between those and node-defaulting.
1808 @section @code{ld} and the H8/300
1810 @cindex H8/300 support
1811 For the H8/300, @code{ld} can perform these global optimizations when
1812 you specify the @samp{-relax} command-line option.
1815 @item relaxing address modes
1816 @cindex relaxing on H8/300
1817 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
1818 targets are within eight bits, and turns them into eight-bit
1819 program-counter relative @code{bsr} and @code{bra} instructions,
1822 @item synthesizing instructions
1823 @cindex synthesizing on H8/300
1824 @c FIXME: specifically mov.b, or any mov instructions really?
1825 @code{ld} finds all @code{mov.b} instructions which use the
1826 sixteen-bit absolute address form, but refer to the top
1827 page of memory, and changes them to use the eight-bit address form.
1828 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1829 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1830 top page of memory).
1842 @section @code{ld} and the Intel 960 family
1844 @cindex i960 support
1846 You can use the @samp{-A@var{architecture}} command line option to
1847 specify one of the two-letter names identifying members of the 960
1848 family; the option specifies the desired output target, and warns of any
1849 incompatible instructions in the input files. It also modifies the
1850 linker's search strategy for archive libraries, to support the use of
1851 libraries specific to each particular architecture, by including in the
1852 search loop names suffixed with the string identifying the architecture.
1854 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
1855 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1856 paths, and in any paths you specify with @samp{-L}) for a library with
1867 The first two possibilities would be considered in any event; the last
1868 two are due to the use of @w{@samp{-ACA}}.
1870 You can meaningfully use @samp{-A} more than once on a command line, since
1871 the 960 architecture family allows combination of target architectures; each
1872 use will add another pair of name variants to search for when @w{@samp{-l}}
1873 specifies a library.
1879 @ifclear SingleFormat
1884 @cindex object file management
1885 The linker accesses object and archive files using the BFD libraries.
1886 These libraries allow the linker to use the same routines to operate on
1887 object files whatever the object file format. A different object file
1888 format can be supported simply by creating a new BFD back end and adding
1889 it to the library. You can use @code{objdump -i}
1890 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
1891 list all the formats available for each architecture under BFD. This
1892 was the list of formats, and of architectures supported for each format,
1893 as of the time this manual was prepared:
1894 @cindex formats available
1895 @cindex architectures available
1897 BFD header file version 0.18
1899 (header big endian, data big endian)
1905 (header big endian, data big endian)
1911 (header big endian, data little endian)
1914 (header little endian, data little endian)
1917 (header big endian, data big endian)
1920 (header big endian, data big endian)
1923 (header little endian, data little endian)
1926 (header big endian, data little endian)
1929 (header little endian, data little endian)
1932 (header big endian, data big endian)
1935 (header big endian, data big endian)
1938 (header big endian, data big endian)
1941 (header little endian, data little endian)
1944 (header big endian, data big endian)
1956 (header little endian, data little endian)
1968 (header big endian, data big endian)
1980 (header big endian, data big endian)
1993 @cindex BFD requirements
1994 @cindex requirements for BFD
1995 As with most implementations, BFD is a compromise between
1996 several conflicting requirements. The major factor influencing
1997 BFD design was efficiency: any time used converting between
1998 formats is time which would not have been spent had BFD not
1999 been involved. This is partly offset by abstraction payback; since
2000 BFD simplifies applications and back ends, more time and care
2001 may be spent optimizing algorithms for a greater speed.
2003 One minor artifact of the BFD solution which you should bear in
2004 mind is the potential for information loss. There are two places where
2005 useful information can be lost using the BFD mechanism: during
2006 conversion and during output. @xref{BFD information loss}.
2009 * BFD outline:: How it works: an outline of BFD
2013 @section How it works: an outline of BFD
2014 @cindex opening object files
2015 @include bfdsumm.texi
2019 @appendix MRI Compatible Script Files
2020 @cindex MRI compatibility
2021 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
2022 linker, @code{ld} can use MRI compatible linker scripts as an
2023 alternative to the more general-purpose linker scripting language
2024 described in @ref{Commands,,Command Language}. MRI compatible linker
2025 scripts have a much simpler command set than the scripting language
2026 otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
2027 commonly used MRI linker commands; these commands are described here.
2029 You can specify a file containing an MRI-compatible script using the
2030 @samp{-c} command-line option.
2032 Each command in an MRI-compatible script occupies its own line; each
2033 command line starts with the keyword that identifies the command (though
2034 blank lines are also allowed for punctuation). If a line of an
2035 MRI-compatible script begins with an unrecognized keyword, @code{ld}
2036 issues a warning message, but continues processing the script.
2038 Lines beginning with @samp{*} are comments.
2040 You can write these commands using all upper-case letters, or all
2041 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
2042 The following list shows only the upper-case form of each command.
2045 @item ABSOLUTE @var{secname}
2046 @item ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
2047 @cindex @code{ABSOLUTE} (MRI)
2048 Normally, @code{ld} includes in the output file all sections from all
2049 the input files. However, in an MRI-compatible script, you can use the
2050 @code{ABSOLUTE} command to restrict the sections that will be present in
2051 your output program. If the @code{ABSOLUTE} command is used at all in a
2052 script, then only the sections named explicitly in @code{ABSOLUTE}
2053 commands will appear in the linker output. You can still use other
2054 input sections (whatever you select on the command line, or using
2055 @code{LOAD}) to resolve addresses in the output file.
2057 @item ALIAS @var{out-secname}, @var{in-secname}
2058 @cindex @code{ALIAS} (MRI)
2059 Use this command to place the data from input section @var{in-secname}
2060 in a section called @var{out-secname} in the linker output file.
2062 @var{in-secname} may be an integer.
2064 @item BASE @var{expression}
2065 @cindex @code{BASE} (MRI)
2066 Use the value of @var{expression} as the lowest address (other than
2067 absolute addresses) in the output file.
2069 @item CHIP @var{expression}
2070 @itemx CHIP @var{expression}, @var{expression}
2071 @cindex @code{CHIP} (MRI)
2072 This command does nothing; it is accepted only for compatibility.
2075 @cindex @code{END} (MRI)
2076 This command does nothing whatever; it's only accepted for compatibility.
2078 @item FORMAT @var{output-format}
2079 @cindex @code{FORMAT} (MRI)
2080 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
2081 language, but restricted to one of these output formats:
2084 S-records, if @var{output-format} is @samp{S}
2087 IEEE, if @var{output-format} is @samp{IEEE}
2090 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
2094 @item LIST @var{anything}@dots{}
2095 @cindex @code{LIST} (MRI)
2096 Print (to the standard output file) a link map, as produced by the
2097 @code{ld} command-line option @samp{-M}.
2099 The keyword @code{LIST} may be followed by anything on the
2100 same line, with no change in its effect.
2102 @item LOAD @var{filename}
2103 @item LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
2104 @cindex @code{LOAD} (MRI)
2105 Include one or more object file @var{filename} in the link; this has the
2106 same effect as specifying @var{filename} directly on the @code{ld}
2109 @item NAME @var{output-name}
2110 @cindex @code{NAME} (MRI)
2111 @var{output-name} is the name for the program produced by @code{ld}; the
2112 MRI-compatible command @code{NAME} is equivalent to the command-line
2113 option @samp{-o} or the general script language command @code{OUTPUT}.
2115 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
2116 @itemx ORDER @var{secname} @var{secname} @var{secname}
2117 @cindex @code{ORDER} (MRI)
2118 Normally, @code{ld} orders the sections in its output file in the
2119 order in which they first appear in the input files. In an MRI-compatible
2120 script, you can override this ordering with the @code{ORDER} command. The
2121 sections you list with @code{ORDER} will appear first in your output
2122 file, in the order specified.
2124 @item PUBLIC @var{name}=@var{expression}
2125 @itemx PUBLIC @var{name},@var{expression}
2126 @itemx PUBLIC @var{name} @var{expression}
2127 @cindex @code{PUBLIC} (MRI)
2128 Supply a value (@var{expression}) for external symbol
2129 @var{name} used in the linker input files.
2131 @item SECT @var{secname}, @var{expression}
2132 @itemx SECT @var{secname}=@var{expression}
2133 @itemx SECT @var{secname} @var{expression}
2134 @cindex @code{SECT} (MRI)
2135 You can use any of these three forms of the @code{SECT} command to
2136 specify the start address (@var{expression}) for section @var{secname}.
2137 If you have more than one @code{SECT} statement for the same
2138 @var{secname}, only the @emph{first} sets the start address.
2148 % I think something like @colophon should be in texinfo. In the
2150 \long\def\colophon{\hbox to0pt{}\vfill
2151 \centerline{The body of this manual is set in}
2152 \centerline{\fontname\tenrm,}
2153 \centerline{with headings in {\bf\fontname\tenbf}}
2154 \centerline{and examples in {\tt\fontname\tentt}.}
2155 \centerline{{\it\fontname\tenit\/} and}
2156 \centerline{{\sl\fontname\tensl\/}}
2157 \centerline{are used for emphasis.}\vfill}
2159 % Blame: pesch@cygnus.com, 28mar91.