4 @include configdoc.texi
5 @c (configdoc.texi is generated by the Makefile)
13 * Ld:: The GNU linker.
19 This file documents the GNU linker LD.
21 Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
23 Permission is granted to make and distribute verbatim copies of
24 this manual provided the copyright notice and this permission notice
25 are preserved on all copies.
27 Permission is granted to copy and distribute modified versions of this
28 manual under the conditions for verbatim copying, provided also that
29 the entire resulting derived work is distributed under the terms of a
30 permission notice identical to this one.
32 Permission is granted to copy and distribute translations of this manual
33 into another language, under the above conditions for modified versions.
36 Permission is granted to process this file through Tex and print the
37 results, provided the printed document carries copying permission
38 notice identical to this one except for the removal of this paragraph
39 (this paragraph not being relevant to the printed manual).
45 @setchapternewpage odd
46 @settitle Using LD, the GNU linker
49 @subtitle The GNU linker
51 @subtitle @code{ld} version 2
53 @author Steve Chamberlain and Roland Pesch
54 @author Cygnus Support
59 \hfill Cygnus Support\par
60 \hfill steve\@cygnus.com, pesch\@cygnus.com\par
61 \hfill {\it Using LD, the GNU linker}\par
62 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com), March 1993.\par
64 \global\parindent=0pt % Steve likes it this way.
67 @vskip 0pt plus 1filll
68 Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
70 Permission is granted to make and distribute verbatim copies of
71 this manual provided the copyright notice and this permission notice
72 are preserved on all copies.
74 Permission is granted to copy and distribute modified versions of this
75 manual under the conditions for verbatim copying, provided also that
76 the entire resulting derived work is distributed under the terms of a
77 permission notice identical to this one.
79 Permission is granted to copy and distribute translations of this manual
80 into another language, under the above conditions for modified versions.
83 @c FIXME: Talk about importance of *order* of args, cmds to linker!
88 This file documents the GNU linker ld.
92 * Invocation:: Invocation
93 * Commands:: Command Language
95 * Machine Dependent:: Machine Dependent Features
99 * H8/300:: ld and the H8/300
102 * i960:: ld and the Intel 960 family
105 @ifclear SingleFormat
108 @c Following blank line required for remaining bug in makeinfo conds/menus
110 * MRI:: MRI Compatible Script Files
119 @cindex what is this?
120 @code{ld} combines a number of object and archive files, relocates
121 their data and ties up symbol references. Usually the last step in
122 compiling a program is to run @code{ld}.
124 @code{ld} accepts Linker Command Language files written in
125 a superset of AT&T's Link Editor Command Language syntax,
126 to provide explicit and total control over the linking process.
128 @ifclear SingleFormat
129 This version of @code{ld} uses the general purpose BFD libraries
130 to operate on object files. This allows @code{ld} to read, combine, and
131 write object files in many different formats---for example, COFF or
132 @code{a.out}. Different formats may be linked together to produce any
133 available kind of object file. @xref{BFD} for a list of formats
134 supported on various architectures.
137 Aside from its flexibility, the GNU linker is more helpful than other
138 linkers in providing diagnostic information. Many linkers abandon
139 execution immediately upon encountering an error; whenever possible,
140 @code{ld} continues executing, allowing you to identify other errors
141 (or, in some cases, to get an output file in spite of the error).
146 The GNU linker @code{ld} is meant to cover a broad range of situations,
147 and to be as compatible as possible with other linkers. As a result,
148 you have many choices to control its behavior.
152 * Options:: Command Line Options
153 * Environment:: Environment Variables
157 @section Command Line Options
162 Here is a summary of the options you can use on the @code{ld} command
165 @c FIXME! -relax only avail h8/300, i960. Conditionals screwed in examples.
167 ld [ -o @var{output} ] @var{objfile}@dots{}
168 [ -A@var{architecture} ] [ -b @var{input-format} ] [ -Bstatic ]
169 [ -c @var{MRI-commandfile} ] [ -d | -dc | -dp ]
170 [ -defsym @var{symbol}=@var{expression} ]
171 [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
172 [ -format @var{input-format} ] [ -g ] [ -G @var{size} ] [ --help ] [ -i ]
173 [ -l@var{archive} ] [ -L@var{searchdir} ] [ -M ] [ -Map @var{mapfile} ]
174 [ -m @var{emulation} ] [ -N | -n ] [ -noinhibit-exec ]
175 [ -oformat @var{output-format} ] [ -R @var{filename} ] [ -relax ]
176 [ -r | -Ur ] [ -S ] [ -s ] [ -sort-common ] [ -stats ]
177 [ -T @var{commandfile} ]
178 [ -Ttext @var{org} ] [ -Tdata @var{org} ]
179 [ -Tbss @var{org} ] [ -t ] [ -u @var{symbol}] [-V] [-v] [ --version ]
180 [ -warn-common ] [ -y@var{symbol} ] [ -X ] [-x ]
183 This plethora of command-line options may seem intimidating, but in
184 actual practice few of them are used in any particular context.
185 @cindex standard Unix system
186 For instance, a frequent use of @code{ld} is to link standard Unix
187 object files on a standard, supported Unix system. On such a system, to
188 link a file @code{hello.o}:
191 ld -o @var{output} /lib/crt0.o hello.o -lc
194 This tells @code{ld} to produce a file called @var{output} as the
195 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
196 the library @code{libc.a}, which will come from the standard search
197 directories. (See the discussion of the @samp{-l} option below.)
199 The command-line options to @code{ld} may be specified in any order, and
200 may be repeated at will. Repeating most options with a
201 different argument will either have no further effect, or override prior
202 occurrences (those further to the left on the command line) of that
205 @ifclear SingleFormat
206 The exceptions---which may meaningfully be used more than once---are
207 @samp{-A}, @samp{-b} (or its synonym @samp{-format}), @samp{-defsym},
208 @samp{-L}, @samp{-l}, @samp{-R}, and @samp{-u}.
211 The exceptions---which may meaningfully be used more than once---are
212 @samp{-A}, @samp{-defsym}, @samp{-L}, @samp{-l}, @samp{-R}, and @samp{-u}.
216 The list of object files to be linked together, shown as @var{objfile}@dots{},
217 may follow, precede, or be mixed in with command-line options, except that
218 an @var{objfile} argument may not be placed between an option and
221 Usually the linker is invoked with at least one object file, but you can
222 specify other forms of binary input files using @samp{-l}, @samp{-R},
223 and the script command language. If @emph{no} binary input files at all
224 are specified, the linker does not produce any output, and issues the
225 message @samp{No input files}.
227 Option arguments must either follow the option letter without intervening
228 whitespace, or be given as separate arguments immediately following the
229 option that requires them.
233 @cindex architectures
235 @item -A@var{architecture}
236 In the current release of @code{ld}, this option is useful only for the
237 Intel 960 family of architectures. In that @code{ld} configuration, the
238 @var{architecture} argument identifies the particular architecture in
239 the 960 family, enabling some safeguards and modifying the
240 archive-library search path. @xref{i960,,@code{ld} and the Intel 960
241 family}, for details.
243 Future releases of @code{ld} may support similar functionality for
244 other architecture families.
247 @ifclear SingleFormat
248 @cindex binary input format
249 @kindex -b @var{format}
251 @item -b @var{input-format}
253 Specify the binary format for input object files that follow this option
254 on the command line. You don't usually need to specify this, as
255 @code{ld} is configured to expect as a default input format the most
256 usual format on each machine. @var{input-format} is a text string, the
257 name of a particular format supported by the BFD libraries.
258 (You can list the available binary formats with @samp{objdump -i}.)
259 @w{@samp{-format @var{input-format}}} has the same effect, as does the
260 script command @code{TARGET}. @xref{BFD}.
262 You may want to use this option if you are linking files with an unusual
263 binary format. You can also use @samp{-b} to switch formats explicitly (when
264 linking object files of different formats), by including
265 @samp{-b @var{input-format}} before each group of object files in a
268 The default format is taken from the environment variable
273 You can also define the input
274 format from a script, using the command @code{TARGET}; see @ref{Option
280 Ignored. This option is accepted for command-line compatibility with
283 @kindex -c @var{MRI-cmdfile}
284 @cindex compatibility, MRI
285 @item -c @var{MRI-commandfile}
286 For compatibility with linkers produced by MRI, @code{ld} accepts script
287 files written in an alternate, restricted command language, described in
288 @ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
289 the option @samp{-c}; use the @samp{-T} option to run linker
290 scripts written in the general-purpose @code{ld} scripting language.
291 If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
292 specified by any @samp{-L} options.
294 @cindex common allocation
301 These three options are equivalent; multiple forms are supported for
302 compatibility with other linkers. They
303 assign space to common symbols even if a relocatable output file is
304 specified (with @samp{-r}). The script command
305 @code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Option
308 @cindex symbols, from command line
309 @kindex -defsym @var{symbol}=@var{exp}
310 @item -defsym @var{symbol}=@var{expression}
311 Create a global symbol in the output file, containing the absolute
312 address given by @var{expression}. You may use this option as many
313 times as necessary to define multiple symbols in the command line. A
314 limited form of arithmetic is supported for the @var{expression} in this
315 context: you may give a hexadecimal constant or the name of an existing
316 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
317 constants or symbols. If you need more elaborate expressions, consider
318 using the linker command language from a script (@pxref{Assignment, ,
319 Assignment: Symbol Definitions}). @emph{Note:} there should be no
320 white space between @var{symbol}, the equals sign (``@key{=}''), and
323 @cindex entry point, from command line
324 @kindex -e @var{entry}
326 Use @var{entry} as the explicit symbol for beginning execution of your
327 program, rather than the default entry point. @xref{Entry Point}, for a
328 discussion of defaults and other ways of specifying the
331 @ifclear SingleFormat
334 @itemx -F@var{format}
335 Ignored. Some older linkers used this option throughout a compilation
336 toolchain for specifying object-file format for both input and output
337 object files. The mechanisms @code{ld} uses for this purpose (the
338 @samp{-b} or @samp{-format} options for input files, @samp{-oformat}
339 option or the @code{TARGET} command in linker scripts for output files,
340 the @code{GNUTARGET} environment variable) are more flexible, but
341 @code{ld} accepts the @samp{-F} option for compatibility with scripts
342 written to call the old linker.
345 @item -format @var{input-format}
346 Synonym for @samp{-b @var{input-format}}.
351 Ignored. Provided for compatibility with other tools.
356 @itemx -G @var{value}
357 Set the maximum size of objects to be optimized using the GP register to
358 @var{size} under MIPS ECOFF. Ignored for other object file formats.
364 Print a summary of the command-line options on the standard output and exit.
365 This option and @samp{--version} begin with two dashes instead of one
366 for compatibility with other GNU programs. The other options start with
367 only one dash for compatibility with other linkers.
370 @cindex incremental link
372 Perform an incremental link (same as option @samp{-r}).
374 @cindex archive files, from cmd line
375 @kindex -l@var{archive}
377 Add archive file @var{archive} to the list of files to link. This
378 option may be used any number of times. @code{ld} will search its
379 path-list for occurrences of @code{lib@var{ar}.a} for every @var{archive}
382 @cindex search directory, from cmd line
384 @item -L@var{searchdir}
385 @itemx -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.
451 @ifclear SingleFormat
453 @item -oformat @var{output-format}
454 Specify the binary format for the output object file. You don't usually
455 need to specify this, as @code{ld} is configured to produce as a default
456 output format the most usual format on each machine.
457 @var{output-format} is a text string, the name of a particular format
458 supported by the BFD libraries. (You can list the available binary
459 formats with @samp{objdump -i}.) The script command
460 @code{OUTPUT_FORMAT} can also specify the output format, but this option
461 overrides it. @xref{BFD}.
464 @item -R @var{filename}
465 @kindex -R @var{file}
466 @cindex symbol-only input
467 Read symbol names and their addresses from @var{filename}, but do not
468 relocate it or include it in the output. This allows your output file
469 to refer symbolically to absolute locations of memory defined in other
474 @cindex synthesizing linker
475 @cindex relaxing addressing modes
476 An option with machine dependent effects. Currently this option is only
477 supported on the H8/300.
479 @xref{H8/300,,@code{ld} and the H8/300}.
482 On some platforms, use option performs global optimizations that
483 become possible when the linker resolves addressing in the program, such
484 as relaxing address modes and synthesizing new instructions in the
487 On platforms where this is not supported, @samp{-relax} is accepted, but
492 @cindex relocatable output
494 Generate relocatable output---i.e., generate an output file that can in
495 turn serve as input to @code{ld}. This is often called @dfn{partial
496 linking}. As a side effect, in environments that support standard Unix
497 magic numbers, this option also sets the output file's magic number to
500 If this option is not specified, an absolute file is produced. When
501 linking C++ programs, this option @emph{will not} resolve references to
502 constructors; to do that, use @samp{-Ur}.
504 This option does the same thing as @samp{-i}.
508 @cindex strip debugger symbols
509 Omit debugger symbol information (but not all symbols) from the output file.
513 @cindex strip all symbols
514 Omit all symbol information from the output file.
517 Normally, when @code{ld} places the global common symbols in the
518 appropriate output sections, it sorts them by size. First come all the
519 one byte symbols, then all the two bytes, then all the four bytes, and
520 then everything else. This is to prevent gaps between symbols due to
521 alignment constraints. This option disables that sorting.
524 Compute and display statistics about the operation of the linker,
525 such as execution time and memory usage.
527 @item -Tbss @var{org}
528 @kindex -Tbss @var{org}
529 @itemx -Tdata @var{org}
530 @kindex -Tdata @var{org}
531 @itemx -Ttext @var{org}
532 @kindex -Ttext @var{org}
533 @cindex segment origins, cmd line
534 Use @var{org} as the starting address for---respectively---the
535 @code{bss}, @code{data}, or the @code{text} segment of the output file.
536 @var{org} must be a single hexadecimal integer;
537 for compatibility with other linkers, you may omit the leading
538 @samp{0x} usually associated with hexadecimal values.
540 @item -T @var{commandfile}
541 @itemx -T@var{commandfile}
542 @kindex -T @var{script}
544 Read link commands from the file @var{commandfile}. These commands
545 replace @code{ld}'s default link script (rather than adding
546 to it), so @var{commandfile} must specify everything necessary to describe
547 the target format. @xref{Commands}. If @var{commandfile} does not
548 exist, @code{ld} looks for it in the directories specified by any
549 preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
554 @cindex input files, displaying
555 Print the names of the input files as @code{ld} processes them.
557 @item -u @var{symbol}
558 @kindex -u @var{symbol}
559 @cindex undefined symbol
560 Force @var{symbol} to be entered in the output file as an undefined symbol.
561 Doing this may, for example, trigger linking of additional modules from
562 standard libraries. @samp{-u} may be repeated with different option
563 arguments to enter additional undefined symbols.
564 @c Nice idea, but no such command: This option is equivalent
565 @c to the @code{EXTERN} linker command.
570 For anything other than C++ programs, this option is equivalent to
571 @samp{-r}: it generates relocatable output---i.e., an output file that can in
572 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
573 @emph{will} resolve references to constructors, unlike @samp{-r}.
574 It does not work to use @samp{-Ur} on files that were themselves linked
575 with @samp{-Ur}; once the constructor table has been built, it can not
576 be added to. Use @samp{-Ur} only for the last partial link, and
577 @samp{-r} for the others.
582 Display the version number for @code{ld} and list the supported emulations.
583 Display which input files can and can not be opened.
588 Display the version number for @code{ld}.
592 Display the version number for @code{ld} and exit.
596 @cindex warnings, on combining symbols
597 @cindex combining symbols, warnings on
598 Warn when a common symbol is combined with another common symbol or with
599 a symbol definition. Unix linkers allow this somewhat sloppy practice,
600 but linkers on some other operating systems do not. This option allows
601 you to find potential problems from combining global symbols.
602 Unfortunately, some C libraries use this practice, so you may get some
603 warnings about symbols in the libraries as well as in your programs.
605 There are three kinds of global symbols, illustrated here by C examples:
609 A definition, which goes in the initialized data section of the output
613 An undefined reference, which does not allocate space.
614 There must be either a definition or a common symbol for the
618 A common symbol. If there are only (one or more) common symbols for a
619 variable, it goes in the uninitialized data area of the output file.
620 The linker merges multiple common symbols for the same variable into a
621 single symbol. If they are of different sizes, it picks the largest
622 size. The linker turns a common symbol into a declaration, if there is
623 a definition of the same variable.
626 The @samp{-warn-common} option can produce five kinds of warnings. Each
627 warning consists of a pair of lines: the first describes the symbol just
628 encountered, and the second describes the previous symbol encountered
629 with the same name. One or both of the two symbols will be a common
634 Turning a common symbol into a reference, because there is already a
635 definition for the symbol.
637 @var{file}(@var{section}): warning: common of `@var{symbol}'
638 overridden by definition
639 @var{file}(@var{section}): warning: defined here
643 Turning a common symbol into a reference, because a later definition for
644 the symbol is encountered. This is the same as the previous case,
645 except that the symbols are encountered in a different order.
647 @var{file}(@var{section}): warning: definition of `@var{symbol}'
649 @var{file}(@var{section}): warning: common is here
653 Merging a common symbol with a previous same-sized common symbol.
655 @var{file}(@var{section}): warning: multiple common
657 @var{file}(@var{section}): warning: previous common is here
661 Merging a common symbol with a previous larger common symbol.
663 @var{file}(@var{section}): warning: common of `@var{symbol}'
664 overridden by larger common
665 @var{file}(@var{section}): warning: larger common is here
669 Merging a common symbol with a previous smaller common symbol. This is
670 the same as the previous case, except that the symbols are
671 encountered in a different order.
673 @var{file}(@var{section}): warning: common of `@var{symbol}'
674 overriding smaller common
675 @var{file}(@var{section}): warning: smaller common is here
681 @cindex local symbols, deleting
682 @cindex L, deleting symbols beginning
683 If @samp{-s} or @samp{-S} is also specified, delete only local symbols
684 beginning with @samp{L}.
688 @cindex deleting local symbols
689 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
690 not just those beginning with @samp{L}.
693 @kindex -y@var{symbol}
694 @cindex symbol tracing
695 Print the name of each linked file in which @var{symbol} appears. This
696 option may be given any number of times. On many systems it is necessary
697 to prepend an underscore.
699 This option is useful when you have an undefined symbol in your link but
700 don't know where the reference is coming from.
705 @section Environment Variables
707 You can change the behavior of @code{ld} with the environment
708 variable @code{GNUTARGET}.
711 @cindex default input format
712 @code{GNUTARGET} determines the input-file object format if you don't
713 use @samp{-b} (or its synonym @samp{-format}). Its value should be one
714 of the BFD names for an input format (@pxref{BFD}). If there is no
715 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
716 of the target. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
717 input format by examining binary input files; this method often
718 succeeds, but there are potential ambiguities, since there is no method
719 of ensuring that the magic number used to specify object-file formats is
720 unique. However, the configuration procedure for BFD on each system
721 places the conventional format for that system first in the search-list,
722 so ambiguities are resolved in favor of convention.
726 @chapter Command Language
728 @cindex command files
729 The command language provides explicit control over the link process,
730 allowing complete specification of the mapping between the linker's
731 input files and its output. It controls:
740 addresses of sections
742 placement of common blocks
745 You may supply a command file (also known as a link script) to the
746 linker either explicitly through the @samp{-T} option, or implicitly as
747 an ordinary file. If the linker opens a file which it cannot recognize
748 as a supported object or archive format, it reports an error.
751 * Scripts:: Linker Scripts
752 * Expressions:: Expressions
753 * MEMORY:: MEMORY Command
754 * SECTIONS:: SECTIONS Command
755 * Entry Point:: The Entry Point
756 * Option Commands:: Option Commands
760 @section Linker Scripts
761 The @code{ld} command language is a collection of statements; some are
762 simple keywords setting a particular option, some are used to select and
763 group input files or name output files; and two statement
764 types have a fundamental and pervasive impact on the linking process.
766 @cindex fundamental script commands
767 @cindex commands, fundamental
768 @cindex output file layout
769 @cindex layout of output file
770 The most fundamental command of the @code{ld} command language is the
771 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
772 script must have a @code{SECTIONS} command: it specifies a
773 ``picture'' of the output file's layout, in varying degrees of detail.
774 No other command is required in all cases.
776 The @code{MEMORY} command complements @code{SECTIONS} by describing the
777 available memory in the target architecture. This command is optional;
778 if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
779 memory is available in a contiguous block for all output.
783 You may include comments in linker scripts just as in C: delimited
784 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
785 equivalent to whitespace.
789 @cindex expression syntax
791 Many useful commands involve arithmetic expressions. The syntax for
792 expressions in the command language is identical to that of C
793 expressions, with the following features:
796 All expressions evaluated as integers and
797 are of ``long'' or ``unsigned long'' type.
799 All constants are integers.
801 All of the C arithmetic operators are provided.
803 You may reference, define, and create global variables.
805 You may call special purpose built-in functions.
809 * Integers:: Integers
810 * Symbols:: Symbol Names
811 * Location Counter:: The Location Counter
812 * Operators:: Operators
813 * Evaluation:: Evaluation
814 * Assignment:: Assignment: Defining Symbols
815 * Arithmetic Functions:: Built-In Functions
820 @cindex integer notation
821 @cindex octal integers
822 An octal integer is @samp{0} followed by zero or more of the octal
823 digits (@samp{01234567}).
828 @cindex decimal integers
829 A decimal integer starts with a non-zero digit followed by zero or
830 more digits (@samp{0123456789}).
835 @cindex hexadecimal integers
837 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
838 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
843 @cindex negative integers
844 To write a negative integer, use
845 the prefix operator @samp{-}; @pxref{Operators}.
850 @cindex scaled integers
851 @cindex K and M integer suffixes
852 @cindex M and K integer suffixes
853 @cindex suffixes for integers
854 @cindex integer suffixes
855 Additionally the suffixes @code{K} and @code{M} may be used to scale a
859 @c END TEXI2ROFF-KILL
860 @code{1024} or @code{1024*1024}
864 ${\rm 1024}$ or ${\rm 1024}^2$
866 @c END TEXI2ROFF-KILL
867 respectively. For example, the following all refer to the same quantity:
876 @subsection Symbol Names
879 @cindex quoted symbol names
881 Unless quoted, symbol names start with a letter, underscore, point or
882 hyphen and may include any letters, underscores, digits, points,
883 and minus signs. Unquoted symbol names must not conflict with any
884 keywords. You can specify a symbol which contains odd characters or has
885 the same name as a keyword, by surrounding the symbol name in double quotes:
888 "with a space" = "also with a space" + 10;
891 @node Location Counter
892 @subsection The Location Counter
895 @cindex location counter
896 @cindex current output location
897 The special linker variable @dfn{dot} @samp{.} always contains the
898 current output location counter. Since the @code{.} always refers to
899 a location in an output section, it must always appear in an
900 expression within a @code{SECTIONS} command. The @code{.} symbol
901 may appear anywhere that an ordinary symbol is allowed in an
902 expression, but its assignments have a side effect. Assigning a value
903 to the @code{.} symbol will cause the location counter to be moved.
905 This may be used to create holes in the output section. The location
906 counter may never be moved backwards.
921 In the previous example, @code{file1} is located at the beginning of the
922 output section, then there is a 1000 byte gap. Then @code{file2}
923 appears, also with a 1000 byte gap following before @code{file3} is
924 loaded. The notation @samp{= 0x1234} specifies what data to write in
925 the gaps (@pxref{Section Options}).
928 @subsection Operators
929 @cindex Operators for arithmetic
930 @cindex arithmetic operators
931 @cindex precedence in expressions
932 The linker recognizes the standard C set of arithmetic operators, with
933 the standard bindings and precedence levels:
936 @c END TEXI2ROFF-KILL
938 precedence associativity Operators Notes
944 5 left == != > < <= >=
950 11 right &= += -= *= /= (2)
955 (2) @xref{Assignment}
960 %"lispnarrowing" is the extra indent used generally for @example
961 \hskip\lispnarrowing\vbox{\offinterlineskip
964 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
965 height2pt&\omit&&\omit&&\omit&\cr
966 &Precedence&& Associativity &&{\rm Operators}&\cr
967 height2pt&\omit&&\omit&&\omit&\cr
969 height2pt&\omit&&\omit&&\omit&\cr
971 % '176 is tilde, '~' in tt font
972 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
976 &5&&left&&== != > < <= >=&\cr
982 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
984 height2pt&\omit&&\omit&&\omit&\cr}
989 @obeylines@parskip=0pt@parindent=0pt
990 @dag@quad Prefix operators.
991 @ddag@quad @xref{Assignment}.
994 @c END TEXI2ROFF-KILL
997 @subsection Evaluation
999 @cindex lazy evaluation
1000 @cindex expression evaluation order
1001 The linker uses ``lazy evaluation'' for expressions; it only calculates
1002 an expression when absolutely necessary. The linker needs the value of
1003 the start address, and the lengths of memory regions, in order to do any
1004 linking at all; these values are computed as soon as possible when the
1005 linker reads in the command file. However, other values (such as symbol
1006 values) are not known or needed until after storage allocation. Such
1007 values are evaluated later, when other information (such as the sizes of
1008 output sections) is available for use in the symbol assignment
1012 @subsection Assignment: Defining Symbols
1013 @cindex assignment in scripts
1014 @cindex symbol definition, scripts
1015 @cindex variables, defining
1016 You may create global symbols, and assign values (addresses) to global
1017 symbols, using any of the C assignment operators:
1020 @item @var{symbol} = @var{expression} ;
1021 @itemx @var{symbol} &= @var{expression} ;
1022 @itemx @var{symbol} += @var{expression} ;
1023 @itemx @var{symbol} -= @var{expression} ;
1024 @itemx @var{symbol} *= @var{expression} ;
1025 @itemx @var{symbol} /= @var{expression} ;
1028 Two things distinguish assignment from other operators in @code{ld}
1032 Assignment may only be used at the root of an expression;
1033 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
1038 You must place a trailing semicolon (``@key{;}'') at the end of an
1039 assignment statement.
1042 Assignment statements may appear:
1045 as commands in their own right in an @code{ld} script; or
1047 as independent statements within a @code{SECTIONS} command; or
1049 as part of the contents of a section definition in a
1050 @code{SECTIONS} command.
1053 The first two cases are equivalent in effect---both define a symbol with
1054 an absolute address. The last case defines a symbol whose address is
1055 relative to a particular section (@pxref{SECTIONS}).
1057 @cindex absolute and relocatable symbols
1058 @cindex relocatable and absolute symbols
1059 @cindex symbols, relocatable and absolute
1060 When a linker expression is evaluated and assigned to a variable, it is
1061 given either an absolute or a relocatable type. An absolute expression
1062 type is one in which the symbol contains the value that it will have in
1063 the output file; a relocatable expression type is one in which the
1064 value is expressed as a fixed offset from the base of a section.
1066 The type of the expression is controlled by its position in the script
1067 file. A symbol assigned within a section definition is created relative
1068 to the base of the section; a symbol assigned in any other place is
1069 created as an absolute symbol. Since a symbol created within a
1070 section definition is relative to the base of the section, it
1071 will remain relocatable if relocatable output is requested. A symbol
1072 may be created with an absolute value even when assigned to within a
1073 section definition by using the absolute assignment function
1074 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
1075 is the last byte of an output section named @code{.data}:
1081 _edata = ABSOLUTE(.) ;
1086 The linker tries to put off the evaluation of an assignment until all
1087 the terms in the source expression are known (@pxref{Evaluation}). For
1088 instance, the sizes of sections cannot be known until after allocation,
1089 so assignments dependent upon these are not performed until after
1090 allocation. Some expressions, such as those depending upon the location
1091 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
1092 result of an expression is required, but the value is not available,
1093 then an error results. For example, a script like the following
1096 text 9+this_isnt_constant :
1101 @kindex Non constant expression
1103 will cause the error message ``@code{Non constant expression for initial
1106 @node Arithmetic Functions
1107 @subsection Arithmetic Functions
1108 @cindex functions in expression language
1109 The command language includes a number of built-in
1110 functions for use in link script expressions.
1112 @item ABSOLUTE(@var{exp})
1113 @kindex ABSOLUTE(@var{exp})
1114 @cindex expression, absolute
1115 Return the absolute (non-relocatable, as opposed to non-negative) value
1116 of the expression @var{exp}. Primarily useful to assign an absolute
1117 value to a symbol within a section definition, where symbol values are
1118 normally section-relative.
1120 @item ADDR(@var{section})
1121 @kindex ADDR(@var{section})
1122 @cindex section address
1123 Return the absolute address of the named @var{section}. Your script must
1124 previously have defined the location of that section. In the following
1125 example, @code{symbol_1} and @code{symbol_2} are assigned identical
1131 start_of_output_1 = ABSOLUTE(.);
1136 symbol_1 = ADDR(.output1);
1137 symbol_2 = start_of_output_1;
1142 @item ALIGN(@var{exp})
1143 @kindex ALIGN(@var{exp})
1144 @cindex rounding up location counter
1145 Return the result of the current location counter (@code{.}) aligned to
1146 the next @var{exp} boundary. @var{exp} must be an expression whose
1147 value is a power of two. This is equivalent to
1149 (. + @var{exp} - 1) & ~(@var{exp} - 1)
1152 @code{ALIGN} doesn't change the value of the location counter---it just
1153 does arithmetic on it. As an example, to align the output @code{.data}
1154 section to the next @code{0x2000} byte boundary after the preceding
1155 section and to set a variable within the section to the next
1156 @code{0x8000} boundary after the input sections:
1159 .data ALIGN(0x2000): @{
1161 variable = ALIGN(0x8000);
1166 The first use of @code{ALIGN} in this example specifies the location of
1167 a section because it is used as the optional @var{start} attribute of a
1168 section definition (@pxref{Section Options}). The second use simply
1169 defines the value of a variable.
1171 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1173 @item DEFINED(@var{symbol})
1174 @kindex DEFINED(@var{symbol})
1175 @cindex symbol defaults
1176 Return 1 if @var{symbol} is in the linker global symbol table and is
1177 defined, otherwise return 0. You can use this function to provide default
1178 values for symbols. For example, the following command-file fragment shows how
1179 to set a global symbol @code{begin} to the first location in the
1180 @code{.text} section---but if a symbol called @code{begin} already
1181 existed, its value is preserved:
1185 begin = DEFINED(begin) ? begin : . ;
1191 @item NEXT(@var{exp})
1192 @kindex NEXT(@var{exp})
1193 @cindex unallocated address, next
1194 Return the next unallocated address that is a multiple of @var{exp}.
1195 This function is closely related to @code{ALIGN(@var{exp})}; unless you
1196 use the @code{MEMORY} command to define discontinuous memory for the
1197 output file, the two functions are equivalent.
1199 @item SIZEOF(@var{section})
1200 @kindex SIZEOF(@var{section})
1201 @cindex section size
1202 Return the size in bytes of the named @var{section}, if that section has
1203 been allocated. In the following example, @code{symbol_1} and
1204 @code{symbol_2} are assigned identical values:
1205 @c What does it return if the section hasn't been allocated? 0?
1213 symbol_1 = .end - .start ;
1214 symbol_2 = SIZEOF(.output);
1219 @item SIZEOF_HEADERS
1220 @kindex SIZEOF_HEADERS
1222 @itemx sizeof_headers
1223 @kindex sizeof_headers
1224 Return the size in bytes of the output file's headers. You can use this number
1225 as the start address of the first section, if you choose, to facilitate
1231 @section Memory Layout
1233 @cindex regions of memory
1234 @cindex discontinuous memory
1235 @cindex allocating memory
1236 The linker's default configuration permits allocation of all available memory.
1237 You can override this configuration by using the @code{MEMORY} command. The
1238 @code{MEMORY} command describes the location and size of blocks of
1239 memory in the target. By using it carefully, you can describe which
1240 memory regions may be used by the linker, and which memory regions it
1241 must avoid. The linker does not shuffle sections to fit into the
1242 available regions, but does move the requested sections into the correct
1243 regions and issue errors when the regions become too full.
1245 A command file may contain at most one use of the @code{MEMORY}
1246 command; however, you can define as many blocks of memory within it as
1247 you wish. The syntax is:
1252 @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
1258 @cindex naming memory regions
1259 is a name used internally by the linker to refer to the region. Any
1260 symbol name may be used. The region names are stored in a separate
1261 name space, and will not conflict with symbols, file names or section
1262 names. Use distinct names to specify multiple regions.
1264 @cindex memory region attributes
1265 is an optional list of attributes, permitted for compatibility with the
1266 AT&T linker but not used by @code{ld} beyond checking that the
1267 attribute list is valid. Valid attribute lists must be made up of the
1268 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1269 omit the parentheses around it as well.
1274 is the start address of the region in physical memory. It is
1275 an expression that must evaluate to a constant before
1276 memory allocation is performed. The keyword @code{ORIGIN} may be
1277 abbreviated to @code{org} or @code{o} (but not, for example, @samp{ORG}).
1282 is the size in bytes of the region (an expression).
1283 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1286 For example, to specify that memory has two regions available for
1287 allocation---one starting at 0 for 256 kilobytes, and the other
1288 starting at @code{0x40000000} for four megabytes:
1293 rom : ORIGIN = 0, LENGTH = 256K
1294 ram : org = 0x40000000, l = 4M
1298 Once you have defined a region of memory named @var{mem}, you can direct
1299 specific output sections there by using a command ending in
1300 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1301 Options}). If the combined output sections directed to a region are too
1302 big for the region, the linker will issue an error message.
1305 @section Specifying Output Sections
1307 The @code{SECTIONS} command controls exactly where input sections are
1308 placed into output sections, their order in the output file, and to
1309 which output sections they are allocated.
1311 You may use at most one @code{SECTIONS} command in a script file,
1312 but you can have as many statements within it as you wish. Statements
1313 within the @code{SECTIONS} command can do one of three things:
1316 define the entry point;
1318 assign a value to a symbol;
1320 describe the placement of a named output section, and which input
1321 sections go into it.
1324 You can also use the first two operations---defining the entry point and
1325 defining symbols---outside the @code{SECTIONS} command: @pxref{Entry
1326 Point}, and @pxref{Assignment}. They are permitted here as well for
1327 your convenience in reading the script, so that symbols and the entry
1328 point can be defined at meaningful points in your output-file layout.
1330 When no @code{SECTIONS} command is given, the linker places each input
1331 section into an identically named output section in the order that the
1332 sections are first encountered in the input files. If all input sections
1333 are present in the first file, for example, the order of sections in the
1334 output file will match the order in the first input file.
1337 * Section Definition:: Section Definitions
1338 * Section Placement:: Section Placement
1339 * Section Data Expressions:: Section Data Expressions
1340 * Section Options:: Optional Section Attributes
1343 @node Section Definition
1344 @subsection Section Definitions
1345 @cindex section definition
1346 The most frequently used statement in the @code{SECTIONS} command is
1347 the @dfn{section definition}, which specifies the
1348 properties of an output section: its location, alignment, contents,
1349 fill pattern, and target memory region. Most of
1350 these specifications are optional; the simplest form of a section
1359 @cindex naming output sections
1361 @var{secname} is the name of the output section, and @var{contents} a
1362 specification of what goes there---for example, a list of input files or
1363 sections of input files (@pxref{Section Placement}). As you might
1364 assume, the whitespace shown is optional. You do need the colon
1365 @samp{:} and the braces @samp{@{@}}, however.
1367 @var{secname} must meet the constraints of your output format. In
1368 formats which only support a limited number of sections, such as
1369 @code{a.out}, the name must be one of the names supported by the format
1370 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1371 @code{.bss}). If the output format supports any number of sections, but
1372 with numbers and not names (as is the case for Oasys), the name should be
1373 supplied as a quoted numeric string. A section name may consist of any
1374 sequence of characters, but any name which does not conform to the standard
1375 @code{ld} symbol name syntax must be quoted.
1376 @xref{Symbols, , Symbol Names}.
1378 @node Section Placement
1379 @subsection Section Placement
1380 @cindex contents of a section
1381 In a section definition, you can specify the contents of an output section by
1382 listing particular input files, by listing particular input-file
1383 sections, or by a combination of the two. You can also place arbitrary
1384 data in the section, and define symbols relative to the beginning of the
1387 The @var{contents} of a section definition may include any of the
1388 following kinds of statement. You can include as many of these as you
1389 like in a single section definition, separated from one another by
1393 @item @var{filename}
1394 @kindex @var{filename}
1395 @cindex input files, section defn
1396 @cindex files, including in output sections
1397 You may simply name a particular input file to be placed in the current
1398 output section; @emph{all} sections from that file are placed in the
1399 current section definition. If the file name has already been mentioned
1400 in another section definition, with an explicit section name list, then
1401 only those sections which have not yet been allocated are used.
1403 To specify a list of particular files by name:
1405 .data : @{ afile.o bfile.o cfile.o @}
1408 The example also illustrates that multiple statements can be included in
1409 the contents of a section definition, since each file name is a separate
1412 @item @var{filename}( @var{section} )
1413 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1414 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1415 @kindex @var{filename}(@var{section})
1416 @cindex files and sections, section defn
1417 You can name one or more sections from your input files, for
1418 insertion in the current output section. If you wish to specify a list
1419 of input-file sections inside the parentheses, you may separate the
1420 section names by either commas or whitespace.
1422 @item * (@var{section})
1423 @itemx * (@var{section}, @var{section}, @dots{})
1424 @itemx * (@var{section} @var{section} @dots{})
1425 @cindex input sections to output section
1426 @kindex *(@var{section})
1427 Instead of explicitly naming particular input files in a link control
1428 script, you can refer to @emph{all} files from the @code{ld} command
1429 line: use @samp{*} instead of a particular file name before the
1430 parenthesized input-file section list.
1432 If you have already explicitly included some files by name, @samp{*}
1433 refers to all @emph{remaining} files---those whose places in the output
1434 file have not yet been defined.
1436 For example, to copy sections @code{1} through @code{4} from an Oasys file
1437 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1438 and @code{14} into the @code{.data} section:
1451 @samp{[ @var{section} @dots{} ]} used to be accepted as an alternate way
1452 to specify named sections from all unallocated input files. Because
1453 some operating systems (VMS) allow brackets in file names, that notation
1454 is no longer supported.
1456 @item @var{filename}@code{( COMMON )}
1459 @cindex uninitialized data
1460 @cindex commons in output
1461 Specify where in your output file to place uninitialized data
1462 with this notation. @code{*(COMMON)} by itself refers to all
1463 uninitialized data from all input files (so far as it is not yet
1464 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1465 from a particular file. Both are special cases of the general
1466 mechanisms for specifying where to place input-file sections:
1467 @code{ld} permits you to refer to uninitialized data as if it
1468 were in an input-file section named @code{COMMON}, regardless of the
1469 input file's format.
1472 For example, the following command script arranges the output file into
1473 three consecutive sections, named @code{.text}, @code{.data}, and
1474 @code{.bss}, taking the input for each from the correspondingly named
1475 sections of all the input files:
1478 .text : @{ *(.text) @}
1479 .data : @{ *(.data) @}
1480 .bss : @{ *(.bss) *(COMMON) @}
1484 The following example reads all of the sections from file @code{all.o}
1485 and places them at the start of output section @code{outputa} which
1486 starts at location @code{0x10000}. All of section @code{.input1} from
1487 file @code{foo.o} follows immediately, in the same output section. All
1488 of section @code{.input2} from @code{foo.o} goes into output section
1489 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1490 All of the remaining @code{.input1} and @code{.input2} sections from any
1491 files are written to output section @code{outputc}.
1513 @node Section Data Expressions
1514 @subsection Section Data Expressions
1515 @cindex expressions in a section
1516 The foregoing statements
1517 arrange, in your output file, data originating from your input files.
1518 You can also place data directly in an output section from the link
1519 command script. Most of these additional statements involve
1520 expressions; @pxref{Expressions}. Although these statements are shown
1521 separately here for ease of presentation, no such segregation is needed
1522 within a section definition in the @code{SECTIONS} command; you can
1523 intermix them freely with any of the statements we've just described.
1526 @item CREATE_OBJECT_SYMBOLS
1527 @kindex CREATE_OBJECT_SYMBOLS
1528 @cindex input filename symbols
1529 @cindex filename symbols
1530 Create a symbol for each input file
1531 in the current section, set to the address of the first byte of
1532 data written from that input file. For instance, with @code{a.out}
1533 files it is conventional to have a symbol for each input file. You can
1534 accomplish this by defining the output @code{.text} section as follows:
1539 CREATE_OBJECT_SYMBOLS
1541 _etext = ALIGN(0x2000);
1547 If @code{sample.ld} is a file containing this script, and @code{a.o},
1548 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1549 contents like the following---
1559 @samp{ld -M -T sample.ld a.o b.o c.o d.o} would create a map like this,
1560 containing symbols matching the object file names:
1562 00000000 A __DYNAMIC
1565 00002020 T _afunction
1568 00002038 T _bfunction
1571 00002050 T _cfunction
1574 00002068 T _dfunction
1584 @item @var{symbol} = @var{expression} ;
1585 @kindex @var{symbol} = @var{expression} ;
1586 @itemx @var{symbol} @var{f}= @var{expression} ;
1587 @kindex @var{symbol} @var{f}= @var{expression} ;
1588 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1589 refers to any of the operators @code{&= += -= *= /=} which combine
1590 arithmetic and assignment.
1592 @cindex assignment, in section defn
1593 When you assign a value to a symbol within a particular section
1594 definition, the value is relative to the beginning of the section
1595 (@pxref{Assignment}). If you write
1600 .data : @{ @dots{} rel = 14 ; @dots{} @}
1601 abs2 = 14 + ADDR(.data);
1605 @c FIXME: Try above example!
1607 @code{abs} and @code{rel} do not have the same value; @code{rel} has the
1608 same value as @code{abs2}.
1610 @item BYTE(@var{expression})
1611 @kindex BYTE(@var{expression})
1612 @itemx SHORT(@var{expression})
1613 @kindex SHORT(@var{expression})
1614 @itemx LONG(@var{expression})
1615 @kindex LONG(@var{expression})
1616 @itemx QUAD(@var{expression})
1617 @kindex QUAD(@var{expression})
1618 @cindex direct output
1619 By including one of these four statements in a section definition, you
1620 can explicitly place one, two, four, or eight bytes (respectively) at
1621 the current address of that section. @code{QUAD} is only supported when
1622 using a 64 bit host or target.
1624 @ifclear SingleFormat
1625 Multiple-byte quantities are represented in whatever byte order is
1626 appropriate for the output file format (@pxref{BFD}).
1629 @item FILL(@var{expression})
1630 @kindex FILL(@var{expression})
1631 @cindex holes, filling
1632 @cindex unspecified memory
1633 Specify the ``fill pattern'' for the current section. Any otherwise
1634 unspecified regions of memory within the section (for example, regions
1635 you skip over by assigning a new value to the location counter @samp{.})
1636 are filled with the two least significant bytes from the
1637 @var{expression} argument. A @code{FILL} statement covers memory
1638 locations @emph{after} the point it occurs in the section definition; by
1639 including more than one @code{FILL} statement, you can have different
1640 fill patterns in different parts of an output section.
1643 @node Section Options
1644 @subsection Optional Section Attributes
1645 @cindex section defn, full syntax
1646 Here is the full syntax of a section definition, including all the
1652 @var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : @{ @var{contents} @} =@var{fill} >@var{region}
1657 @var{secname} and @var{contents} are required. @xref{Section
1658 Definition}, and @pxref{Section Placement} for details on @var{contents}.
1659 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1660 @code{(NOLOAD)} @code{=@var{fill}}, and @code{>@var{region}}---are all
1665 @cindex start address, section
1666 @cindex section start
1667 @cindex section address
1668 You can force the output section to be loaded at a specified address by
1669 specifying @var{start} immediately following the section name.
1670 @var{start} can be represented as any expression. The following
1671 example generates section @var{output} at location
1676 output 0x40000000: @{
1683 @item BLOCK(@var{align})
1684 @kindex BLOCK(@var{align})
1685 @cindex section alignment
1686 @cindex aligning sections
1687 You can include @code{BLOCK()} specification to advance
1688 the location counter @code{.} prior to the beginning of the section, so
1689 that the section will begin at the specified alignment. @var{align} is
1694 @cindex prevent unnecessary loading
1695 Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
1696 each time it is accessed. For example, in the script sample below, the
1697 @code{ROM} segment is addressed at memory location @samp{0} and does not
1698 need to be loaded into each object file:
1701 ROM 0 (NOLOAD) : @{ @dots{} @}
1708 @cindex section fill pattern
1709 @cindex fill pattern, entire section
1711 @code{=@var{fill}} in a section definition specifies the initial fill
1712 value for that section.
1713 You may use any expression to specify @var{fill}.
1714 Any unallocated holes in the current output
1715 section when written to the output file will be filled with the two
1716 least significant bytes of the value, repeated as necessary. You can
1717 also change the fill value with a @code{FILL} statement in the
1718 @var{contents} of a section definition.
1721 @kindex >@var{region}
1722 @cindex section, assigning to memory region
1723 @cindex memory regions and sections
1724 Assign this section to a previously defined region of memory.
1730 @section The Entry Point
1731 @kindex ENTRY(@var{symbol})
1732 @cindex start of execution
1733 @cindex first instruction
1734 The linker command language includes a command specifically for
1735 defining the first executable instruction in an output file (its
1736 @dfn{entry point}). Its argument is a symbol name:
1741 Like symbol assignments, the @code{ENTRY} command may be placed either
1742 as an independent command in the command file, or among the section
1743 definitions within the @code{SECTIONS} command---whatever makes the most
1744 sense for your layout.
1746 @cindex entry point, defaults
1747 @code{ENTRY} is only one of several ways of choosing the entry point.
1748 You may indicate it in any of the following ways (shown in descending
1749 order of priority: methods higher in the list override methods lower down).
1752 the @samp{-e} @var{entry} command-line option;
1754 the @code{ENTRY(@var{symbol})} command in a linker control script;
1756 the value of the symbol @code{start}, if present;
1758 the value of the symbol @code{_main}, if present;
1760 the address of the first byte of the @code{.text} section, if present;
1762 The address @code{0}.
1765 For example, you can use these rules to generate an entry point with an
1766 assignment statement: if no symbol @code{start} is defined within your
1767 input files, you can simply define it, assigning it an appropriate
1774 The example shows an absolute address, but you can use any expression.
1775 For example, if your input object files use some other symbol-name
1776 convention for the entry point, you can just assign the value of
1777 whatever symbol contains the start address to @code{start}:
1779 start = other_symbol ;
1782 @node Option Commands
1783 @section Option Commands
1784 The command language includes a number of other commands that you can
1785 use for specialized purposes. They are similar in purpose to
1786 command-line options.
1793 These keywords were used in some older linkers to request a particular
1794 math subroutine library. @code{ld} doesn't use the keywords, assuming
1795 instead that any necessary subroutines are in libraries specified using
1796 the general mechanisms for linking to archives; but to permit the use of
1797 scripts that were written for the older linkers, the keywords
1798 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1800 @item FORCE_COMMON_ALLOCATION
1801 @kindex FORCE_COMMON_ALLOCATION
1802 @cindex common allocation
1803 This command has the same effect as the @samp{-d} command-line option:
1804 to make @code{ld} assign space to common symbols even if a relocatable
1805 output file is specified (@samp{-r}).
1807 @item INPUT ( @var{file}, @var{file}, @dots{} )
1808 @kindex INPUT ( @var{files} )
1809 @itemx INPUT ( @var{file} @var{file} @dots{} )
1810 @cindex binary input files
1811 Use this command to include binary input files in the link, without
1812 including them in a particular section definition.
1813 Specify the full name for each @var{file}, including @samp{.a} if
1816 @code{ld} searches for each @var{file} through the archive-library
1817 search path, just as for files you specify on the command line.
1818 See the description of @samp{-L} in @ref{Options,,Command Line
1822 @item MAP ( @var{name} )
1823 @kindex MAP ( @var{name} )
1824 @c MAP(...) appears to look for an F in the arg, ignoring all other
1825 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1826 @c checks map_option_f. Apparently a stub for the future...
1829 @item OUTPUT ( @var{filename} )
1830 @kindex OUTPUT ( @var{filename} )
1831 @cindex naming the output file
1832 Use this command to name the link output file @var{filename}. The
1833 effect of @code{OUTPUT(@var{filename})} is identical to the effect of
1834 @w{@samp{-o @var{filename}}}, which overrides it. You can use this
1835 command to supply a default output-file name other than @code{a.out}.
1837 @ifclear SingleFormat
1838 @item OUTPUT_ARCH ( @var{bfdname} )
1839 @kindex OUTPUT_ARCH ( @var{bfdname} )
1840 @cindex machine architecture, output
1841 Specify a particular output machine architecture, with one of the names
1842 used by the BFD back-end routines (@pxref{BFD}). This command is often
1843 unnecessary; the architecture is most often set implicitly by either the
1844 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1847 @item OUTPUT_FORMAT ( @var{bfdname} )
1848 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1849 @cindex format, output file
1850 Specify a particular output format, with one of the names used by the
1851 BFD back-end routines (@pxref{BFD}). The effect is identical to the
1852 effect of the @samp{-oformat} command-line option.
1853 This selection will only affect
1854 the output file; the related command @code{TARGET} affects primarily
1858 @item SEARCH_DIR ( @var{path} )
1859 @kindex SEARCH_DIR ( @var{path} )
1860 @cindex path for libraries
1861 @cindex search path, libraries
1862 Add @var{path} to the list of paths where @code{ld} looks for
1863 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1864 effect as @samp{-L@var{path}} on the command line.
1866 @item STARTUP ( @var{filename} )
1867 @kindex STARTUP ( @var{filename} )
1868 @cindex first input file
1869 Ensure that @var{filename} is the first input file used in the link
1872 @ifclear SingleFormat
1873 @item TARGET ( @var{format} )
1874 @cindex input file format
1875 @kindex TARGET ( @var{format} )
1876 Change the input-file object code format (like the command-line option
1877 @samp{-b} or its synonym @samp{-format}). The argument @var{format} is
1878 one of the strings used by BFD to name binary formats. If @code{TARGET}
1879 is specified but @code{OUTPUT_FORMAT} is not, the last @code{TARGET}
1880 argument is also used as the default format for the @code{ld} output
1884 If you don't use the @code{TARGET} command, @code{ld} uses the value of
1885 the environment variable @code{GNUTARGET}, if available, to select the
1886 output file format. If that variable is also absent, @code{ld} uses
1887 the default format configured for your machine in the BFD libraries.
1892 @node Machine Dependent
1893 @chapter Machine Dependent Features
1895 @cindex machine dependencies
1896 @code{ld} has additional features on some platforms; the following
1897 sections describe them. Machines where @code{ld} has no additional
1898 functionality are not listed.
1901 * H8/300:: @code{ld} and the H8/300
1902 * i960:: @code{ld} and the Intel 960 family
1906 @c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict
1907 @c between those and node-defaulting.
1913 @section @code{ld} and the H8/300
1915 @cindex H8/300 support
1916 For the H8/300, @code{ld} can perform these global optimizations when
1917 you specify the @samp{-relax} command-line option.
1920 @item relaxing address modes
1921 @cindex relaxing on H8/300
1922 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
1923 targets are within eight bits, and turns them into eight-bit
1924 program-counter relative @code{bsr} and @code{bra} instructions,
1927 @item synthesizing instructions
1928 @cindex synthesizing on H8/300
1929 @c FIXME: specifically mov.b, or any mov instructions really?
1930 @code{ld} finds all @code{mov.b} instructions which use the
1931 sixteen-bit absolute address form, but refer to the top
1932 page of memory, and changes them to use the eight-bit address form.
1933 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1934 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1935 top page of memory).
1947 @section @code{ld} and the Intel 960 family
1949 @cindex i960 support
1951 You can use the @samp{-A@var{architecture}} command line option to
1952 specify one of the two-letter names identifying members of the 960
1953 family; the option specifies the desired output target, and warns of any
1954 incompatible instructions in the input files. It also modifies the
1955 linker's search strategy for archive libraries, to support the use of
1956 libraries specific to each particular architecture, by including in the
1957 search loop names suffixed with the string identifying the architecture.
1959 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
1960 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1961 paths, and in any paths you specify with @samp{-L}) for a library with
1972 The first two possibilities would be considered in any event; the last
1973 two are due to the use of @w{@samp{-ACA}}.
1975 You can meaningfully use @samp{-A} more than once on a command line, since
1976 the 960 architecture family allows combination of target architectures; each
1977 use will add another pair of name variants to search for when @w{@samp{-l}}
1978 specifies a library.
1984 @ifclear SingleFormat
1989 @cindex object file management
1990 The linker accesses object and archive files using the BFD libraries.
1991 These libraries allow the linker to use the same routines to operate on
1992 object files whatever the object file format. A different object file
1993 format can be supported simply by creating a new BFD back end and adding
1994 it to the library. You can use @code{objdump -i}
1995 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
1996 list all the formats available for each architecture under BFD. This
1997 was the list of formats, and of architectures supported for each format,
1998 as of the time this manual was prepared:
1999 @cindex formats available
2000 @cindex architectures available
2002 BFD header file version 0.18
2004 (header big endian, data big endian)
2010 (header big endian, data big endian)
2016 (header big endian, data little endian)
2019 (header little endian, data little endian)
2022 (header big endian, data big endian)
2025 (header big endian, data big endian)
2028 (header little endian, data little endian)
2031 (header big endian, data little endian)
2034 (header little endian, data little endian)
2037 (header big endian, data big endian)
2040 (header big endian, data big endian)
2043 (header big endian, data big endian)
2046 (header little endian, data little endian)
2049 (header big endian, data big endian)
2061 (header little endian, data little endian)
2073 (header big endian, data big endian)
2085 (header big endian, data big endian)
2098 @cindex BFD requirements
2099 @cindex requirements for BFD
2100 As with most implementations, BFD is a compromise between
2101 several conflicting requirements. The major factor influencing
2102 BFD design was efficiency: any time used converting between
2103 formats is time which would not have been spent had BFD not
2104 been involved. This is partly offset by abstraction payback; since
2105 BFD simplifies applications and back ends, more time and care
2106 may be spent optimizing algorithms for a greater speed.
2108 One minor artifact of the BFD solution which you should bear in
2109 mind is the potential for information loss. There are two places where
2110 useful information can be lost using the BFD mechanism: during
2111 conversion and during output. @xref{BFD information loss}.
2114 * BFD outline:: How it works: an outline of BFD
2118 @section How it works: an outline of BFD
2119 @cindex opening object files
2120 @include bfdsumm.texi
2124 @appendix MRI Compatible Script Files
2125 @cindex MRI compatibility
2126 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
2127 linker, @code{ld} can use MRI compatible linker scripts as an
2128 alternative to the more general-purpose linker scripting language
2129 described in @ref{Commands,,Command Language}. MRI compatible linker
2130 scripts have a much simpler command set than the scripting language
2131 otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
2132 commonly used MRI linker commands; these commands are described here.
2134 In general, MRI scripts aren't of much use with the @code{a.out} object
2135 file format, since it only has three sections and MRI scripts lack some
2136 features to make use of them.
2138 You can specify a file containing an MRI-compatible script using the
2139 @samp{-c} command-line option.
2141 Each command in an MRI-compatible script occupies its own line; each
2142 command line starts with the keyword that identifies the command (though
2143 blank lines are also allowed for punctuation). If a line of an
2144 MRI-compatible script begins with an unrecognized keyword, @code{ld}
2145 issues a warning message, but continues processing the script.
2147 Lines beginning with @samp{*} are comments.
2149 You can write these commands using all upper-case letters, or all
2150 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
2151 The following list shows only the upper-case form of each command.
2154 @item ABSOLUTE @var{secname}
2155 @item ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
2156 @cindex @code{ABSOLUTE} (MRI)
2157 Normally, @code{ld} includes in the output file all sections from all
2158 the input files. However, in an MRI-compatible script, you can use the
2159 @code{ABSOLUTE} command to restrict the sections that will be present in
2160 your output program. If the @code{ABSOLUTE} command is used at all in a
2161 script, then only the sections named explicitly in @code{ABSOLUTE}
2162 commands will appear in the linker output. You can still use other
2163 input sections (whatever you select on the command line, or using
2164 @code{LOAD}) to resolve addresses in the output file.
2166 @item ALIAS @var{out-secname}, @var{in-secname}
2167 @cindex @code{ALIAS} (MRI)
2168 Use this command to place the data from input section @var{in-secname}
2169 in a section called @var{out-secname} in the linker output file.
2171 @var{in-secname} may be an integer.
2173 @item BASE @var{expression}
2174 @cindex @code{BASE} (MRI)
2175 Use the value of @var{expression} as the lowest address (other than
2176 absolute addresses) in the output file.
2178 @item CHIP @var{expression}
2179 @itemx CHIP @var{expression}, @var{expression}
2180 @cindex @code{CHIP} (MRI)
2181 This command does nothing; it is accepted only for compatibility.
2184 @cindex @code{END} (MRI)
2185 This command does nothing whatever; it's only accepted for compatibility.
2187 @item FORMAT @var{output-format}
2188 @cindex @code{FORMAT} (MRI)
2189 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
2190 language, but restricted to one of these output formats:
2193 S-records, if @var{output-format} is @samp{S}
2196 IEEE, if @var{output-format} is @samp{IEEE}
2199 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
2203 @item LIST @var{anything}@dots{}
2204 @cindex @code{LIST} (MRI)
2205 Print (to the standard output file) a link map, as produced by the
2206 @code{ld} command-line option @samp{-M}.
2208 The keyword @code{LIST} may be followed by anything on the
2209 same line, with no change in its effect.
2211 @item LOAD @var{filename}
2212 @item LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
2213 @cindex @code{LOAD} (MRI)
2214 Include one or more object file @var{filename} in the link; this has the
2215 same effect as specifying @var{filename} directly on the @code{ld}
2218 @item NAME @var{output-name}
2219 @cindex @code{NAME} (MRI)
2220 @var{output-name} is the name for the program produced by @code{ld}; the
2221 MRI-compatible command @code{NAME} is equivalent to the command-line
2222 option @samp{-o} or the general script language command @code{OUTPUT}.
2224 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
2225 @itemx ORDER @var{secname} @var{secname} @var{secname}
2226 @cindex @code{ORDER} (MRI)
2227 Normally, @code{ld} orders the sections in its output file in the
2228 order in which they first appear in the input files. In an MRI-compatible
2229 script, you can override this ordering with the @code{ORDER} command. The
2230 sections you list with @code{ORDER} will appear first in your output
2231 file, in the order specified.
2233 @item PUBLIC @var{name}=@var{expression}
2234 @itemx PUBLIC @var{name},@var{expression}
2235 @itemx PUBLIC @var{name} @var{expression}
2236 @cindex @code{PUBLIC} (MRI)
2237 Supply a value (@var{expression}) for external symbol
2238 @var{name} used in the linker input files.
2240 @item SECT @var{secname}, @var{expression}
2241 @itemx SECT @var{secname}=@var{expression}
2242 @itemx SECT @var{secname} @var{expression}
2243 @cindex @code{SECT} (MRI)
2244 You can use any of these three forms of the @code{SECT} command to
2245 specify the start address (@var{expression}) for section @var{secname}.
2246 If you have more than one @code{SECT} statement for the same
2247 @var{secname}, only the @emph{first} sets the start address.
2257 % I think something like @colophon should be in texinfo. In the
2259 \long\def\colophon{\hbox to0pt{}\vfill
2260 \centerline{The body of this manual is set in}
2261 \centerline{\fontname\tenrm,}
2262 \centerline{with headings in {\bf\fontname\tenbf}}
2263 \centerline{and examples in {\tt\fontname\tentt}.}
2264 \centerline{{\it\fontname\tenit\/} and}
2265 \centerline{{\sl\fontname\tensl\/}}
2266 \centerline{are used for emphasis.}\vfill}
2268 % Blame: pesch@cygnus.com, 28mar91.