4 @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 ] [ -sort-common ] [ -T @var{commandfile} ]
176 [ -Ttext @var{org} ] [ -Tdata @var{org} ]
177 [ -Tbss @var{org} ] [ -t ] [ -u @var{symbol}] [-V] [-v] [ --version ]
178 [ -warn-common ] [ -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 you can
220 specify other forms of binary input files using @samp{-l}, @samp{-R},
221 and the script command language. If @emph{no} binary input files at all
222 are specified, the linker does not produce any output, and issues the
223 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{Option
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{Option
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, @samp{-oformat}
337 option or the @code{TARGET} command in linker scripts for output files,
338 the @code{GNUTARGET} environment variable) are more flexible, but
339 @code{ld} accepts the @samp{-F} option for compatibility with scripts
340 written to call the old linker.
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 @itemx -L @var{searchdir}
384 Add path @var{searchdir} to the list of paths that @code{ld} will search
385 for archive libraries and @code{ld} control scripts. You may use this
386 option any number of times.
389 The default set of paths searched (without being specified with
390 @samp{-L}) depends on which emulation mode @code{ld} is using, and in
391 some cases also on how it was configured. @xref{Environment}.
394 The paths can also be specified in a link script with the
395 @code{SEARCH_DIR} command.
400 Print (to the standard output) a link map---diagnostic information
401 about where symbols are mapped by @code{ld}, and information on global
402 common storage allocation.
406 @item -Map @var{mapfile}
407 Print to the file @var{mapfile} a link map---diagnostic information
408 about where symbols are mapped by @code{ld}, and information on global
409 common storage allocation.
412 @kindex -m @var{emulation}
413 @item -m@var{emulation}
414 @itemx -m @var{emulation}
415 Emulate the @var{emulation} linker. You can list the available
416 emulations with the @samp{-V} option. The
417 default is the system for which you configured @code{ld}.
420 @cindex read/write from cmd line
423 Set the text and data sections to be readable and writable. Also, do
424 not page-align the data segment. If the output format supports Unix
425 style magic numbers, mark the output as @code{OMAGIC}.
429 @cindex read-only text
431 Set the text segment to be read only, and mark the output as
432 @code{NMAGIC} if possible.
434 @item -noinhibit-exec
435 @cindex output file after errors
436 @kindex -noinhibit-exec
437 Retain the executable output file whenever it is still usable.
438 Normally, the linker will not produce an output file if it encounters
439 errors during the link process; it exits without writing an output file
440 when it issues any error whatsoever.
442 @item -o @var{output}
443 @kindex -o @var{output}
444 @cindex naming the output file
445 Use @var{output} as the name for the program produced by @code{ld}; if this
446 option is not specified, the name @file{a.out} is used by default. The
447 script command @code{OUTPUT} can also specify the output file name.
449 @ifclear SingleFormat
451 @item -oformat @var{output-format}
452 Specify the binary format for the output object file. You don't usually
453 need to specify this, as @code{ld} is configured to produce as a default
454 output format the most usual format on each machine.
455 @var{output-format} is a text string, the name of a particular format
456 supported by the BFD libraries. (You can list the available binary
457 formats with @samp{objdump -i}.) The script command
458 @code{OUTPUT_FORMAT} can also specify the output format, but this option
459 overrides it. @xref{BFD}.
462 @item -R @var{filename}
463 @kindex -R @var{file}
464 @cindex symbol-only input
465 Read symbol names and their addresses from @var{filename}, but do not
466 relocate it or include it in the output. This allows your output file
467 to refer symbolically to absolute locations of memory defined in other
472 @cindex synthesizing linker
473 @cindex relaxing addressing modes
474 An option with machine dependent effects. Currently this option is only
475 supported on the H8/300.
477 @xref{H8/300,,@code{ld} and the H8/300}.
480 On some platforms, use option performs global optimizations that
481 become possible when the linker resolves addressing in the program, such
482 as relaxing address modes and synthesizing new instructions in the
485 On platforms where this is not supported, @samp{-relax} is accepted, but
490 @cindex relocatable output
492 Generate relocatable output---i.e., generate an output file that can in
493 turn serve as input to @code{ld}. This is often called @dfn{partial
494 linking}. As a side effect, in environments that support standard Unix
495 magic numbers, this option also sets the output file's magic number to
498 If this option is not specified, an absolute file is produced. When
499 linking C++ programs, this option @emph{will not} resolve references to
500 constructors; to do that, use @samp{-Ur}.
502 This option does the same thing as @samp{-i}.
506 @cindex strip debugger symbols
507 Omit debugger symbol information (but not all symbols) from the output file.
511 @cindex strip all symbols
512 Omit all symbol information from the output file.
515 Normally, when @code{ld} places the global common symbols in the
516 appropriate output sections, it sorts them by size. First come all the
517 one byte symbols, then all the two bytes, then all the four bytes, and
518 then everything else. This is to prevent gaps between symbols due to
519 alignment constraints. This option disables that sorting.
521 @item -Tbss @var{org}
522 @kindex -Tbss @var{org}
523 @itemx -Tdata @var{org}
524 @kindex -Tdata @var{org}
525 @itemx -Ttext @var{org}
526 @kindex -Ttext @var{org}
527 @cindex segment origins, cmd line
528 Use @var{org} as the starting address for---respectively---the
529 @code{bss}, @code{data}, or the @code{text} segment of the output file.
530 @var{org} must be a single hexadecimal integer;
531 for compatibility with other linkers, you may omit the leading
532 @samp{0x} usually associated with hexadecimal values.
534 @item -T @var{commandfile}
535 @itemx -T@var{commandfile}
536 @kindex -T @var{script}
538 Read link commands from the file @var{commandfile}. These commands
539 completely override @code{ld}'s default link format (rather than adding
540 to it); @var{commandfile} must specify everything necessary to describe
541 the target format. @xref{Commands}. If @var{commandfile} does not
542 exist, @code{ld} looks for it in the directories specified by any
543 preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
548 @cindex input files, displaying
549 Print the names of the input files as @code{ld} processes them.
551 @item -u @var{symbol}
552 @kindex -u @var{symbol}
553 @cindex undefined symbol
554 Force @var{symbol} to be entered in the output file as an undefined symbol.
555 Doing this may, for example, trigger linking of additional modules from
556 standard libraries. @samp{-u} may be repeated with different option
557 arguments to enter additional undefined symbols.
558 @c Nice idea, but no such command: This option is equivalent
559 @c to the @code{EXTERN} linker command.
564 For anything other than C++ programs, this option is equivalent to
565 @samp{-r}: it generates relocatable output---i.e., an output file that can in
566 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
567 @emph{will} resolve references to constructors, unlike @samp{-r}.
568 It does not work to use @samp{-Ur} on files that were themselves linked
569 with @samp{-Ur}; once the constructor table has been built, it can not
570 be added to. Use @samp{-Ur} only for the last partial link, and
571 @samp{-r} for the others.
576 Display the version number for @code{ld} and list the supported emulations.
577 Display which input files can and can not be opened.
582 Display the version number for @code{ld}.
586 Display the version number for @code{ld} and exit.
590 @cindex warnings, on combining symbols
591 @cindex combining symbols, warnings on
592 Warn when a common symbol is combined with another common symbol or with
593 a symbol definition. Unix linkers allow this somewhat sloppy practice,
594 but linkers on some other operating systems do not. This option allows
595 you to find potential problems from combining global symbols.
596 Unfortunately, some C libraries use this practice, so you may get some
597 warnings about symbols in the libraries as well as in your programs.
599 There are three kinds of global symbols, illustrated here by C examples:
603 A definition, which goes in the initialized data section of the output
607 An undefined reference, which does not allocate space.
608 There must be either a definition or a common symbol for the
612 A common symbol. If there are only (one or more) common symbols for a
613 variable, it goes in the uninitialized data area of the output file.
614 The linker merges multiple common symbols for the same variable into a
615 single symbol. If they are of different sizes, it picks the largest
616 size. The linker turns a common symbol into a declaration, if there is
617 a definition of the same variable.
620 The @samp{-warn-common} option can produce five kinds of warnings. Each
621 warning consists of a pair of lines: the first describes the symbol just
622 encountered, and the second describes the previous symbol encountered
623 with the same name. One or both of the two symbols will be a common
628 Turning a common symbol into a reference, because there is already a
629 definition for the symbol.
631 @var{file}(@var{section}): warning: common of `@var{symbol}'
632 overridden by definition
633 @var{file}(@var{section}): warning: defined here
637 Turning a common symbol into a reference, because a later definition for
638 the symbol is encountered. This is the same as the previous case,
639 except that the symbols are encountered in a different order.
641 @var{file}(@var{section}): warning: definition of `@var{symbol}'
643 @var{file}(@var{section}): warning: common is here
647 Merging a common symbol with a previous same-sized common symbol.
649 @var{file}(@var{section}): warning: multiple common
651 @var{file}(@var{section}): warning: previous common is here
655 Merging a common symbol with a previous larger common symbol.
657 @var{file}(@var{section}): warning: common of `@var{symbol}'
658 overridden by larger common
659 @var{file}(@var{section}): warning: larger common is here
663 Merging a common symbol with a previous smaller common symbol. This is
664 the same as the previous case, except that the symbols are
665 encountered in a different order.
667 @var{file}(@var{section}): warning: common of `@var{symbol}'
668 overriding smaller common
669 @var{file}(@var{section}): warning: smaller common is here
675 @cindex local symbols, deleting
676 @cindex L, deleting symbols beginning
677 If @samp{-s} or @samp{-S} is also specified, delete only local symbols
678 beginning with @samp{L}.
682 @cindex deleting local symbols
683 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
684 not just those beginning with @samp{L}.
687 @kindex -y@var{symbol}
688 @cindex symbol tracing
689 Print the name of each linked file in which @var{symbol} appears. This
690 option may be given any number of times. On many systems it is necessary
691 to prepend an underscore.
693 This option is useful when you have an undefined symbol in your link but
694 don't know where the reference is coming from.
699 @section Environment Variables
701 You can change the behavior of @code{ld} with the environment
702 variable @code{GNUTARGET}.
705 @cindex default input format
706 @code{GNUTARGET} determines the input-file object format if you don't
707 use @samp{-b} (or its synonym @samp{-format}). Its value should be one
708 of the BFD names for an input format (@pxref{BFD}). If there is no
709 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
710 of the target. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
711 input format by examining binary input files; this method often
712 succeeds, but there are potential ambiguities, since there is no method
713 of ensuring that the magic number used to specify object-file formats is
714 unique. However, the configuration procedure for BFD on each system
715 places the conventional format for that system first in the search-list,
716 so ambiguities are resolved in favor of convention.
720 @chapter Command Language
722 @cindex command files
723 The command language provides explicit control over the link process,
724 allowing complete specification of the mapping between the linker's
725 input files and its output. It controls:
734 addresses of sections
736 placement of common blocks
739 You may supply a command file (also known as a link script) to the
740 linker either explicitly through the @samp{-T} option, or implicitly as
741 an ordinary file. If the linker opens a file which it cannot recognize
742 as a supported object or archive format, it reports an error.
745 * Scripts:: Linker Scripts
746 * Expressions:: Expressions
747 * MEMORY:: MEMORY Command
748 * SECTIONS:: SECTIONS Command
749 * Entry Point:: The Entry Point
750 * Option Commands:: Option Commands
754 @section Linker Scripts
755 The @code{ld} command language is a collection of statements; some are
756 simple keywords setting a particular option, some are used to select and
757 group input files or name output files; and two statement
758 types have a fundamental and pervasive impact on the linking process.
760 @cindex fundamental script commands
761 @cindex commands, fundamental
762 @cindex output file layout
763 @cindex layout of output file
764 The most fundamental command of the @code{ld} command language is the
765 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
766 script must have a @code{SECTIONS} command: it specifies a
767 ``picture'' of the output file's layout, in varying degrees of detail.
768 No other command is required in all cases.
770 The @code{MEMORY} command complements @code{SECTIONS} by describing the
771 available memory in the target architecture. This command is optional;
772 if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
773 memory is available in a contiguous block for all output.
777 You may include comments in linker scripts just as in C: delimited
778 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
779 equivalent to whitespace.
783 @cindex expression syntax
785 Many useful commands involve arithmetic expressions. The syntax for
786 expressions in the command language is identical to that of C
787 expressions, with the following features:
790 All expressions evaluated as integers and
791 are of ``long'' or ``unsigned long'' type.
793 All constants are integers.
795 All of the C arithmetic operators are provided.
797 You may reference, define, and create global variables.
799 You may call special purpose built-in functions.
803 * Integers:: Integers
804 * Symbols:: Symbol Names
805 * Location Counter:: The Location Counter
806 * Operators:: Operators
807 * Evaluation:: Evaluation
808 * Assignment:: Assignment: Defining Symbols
809 * Arithmetic Functions:: Built-In Functions
814 @cindex integer notation
815 @cindex octal integers
816 An octal integer is @samp{0} followed by zero or more of the octal
817 digits (@samp{01234567}).
822 @cindex decimal integers
823 A decimal integer starts with a non-zero digit followed by zero or
824 more digits (@samp{0123456789}).
829 @cindex hexadecimal integers
831 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
832 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
837 @cindex negative integers
838 To write a negative integer, use
839 the prefix operator @samp{-}; @pxref{Operators}.
844 @cindex scaled integers
845 @cindex K and M integer suffixes
846 @cindex M and K integer suffixes
847 @cindex suffixes for integers
848 @cindex integer suffixes
849 Additionally the suffixes @code{K} and @code{M} may be used to scale a
853 @c END TEXI2ROFF-KILL
854 @code{1024} or @code{1024*1024}
858 ${\rm 1024}$ or ${\rm 1024}^2$
860 @c END TEXI2ROFF-KILL
861 respectively. For example, the following all refer to the same quantity:
870 @subsection Symbol Names
873 @cindex quoted symbol names
875 Unless quoted, symbol names start with a letter, underscore, point or
876 hyphen and may include any letters, underscores, digits, points,
877 and minus signs. Unquoted symbol names must not conflict with any
878 keywords. You can specify a symbol which contains odd characters or has
879 the same name as a keyword, by surrounding the symbol name in double quotes:
882 "with a space" = "also with a space" + 10;
885 @node Location Counter
886 @subsection The Location Counter
889 @cindex location counter
890 @cindex current output location
891 The special linker variable @dfn{dot} @samp{.} always contains the
892 current output location counter. Since the @code{.} always refers to
893 a location in an output section, it must always appear in an
894 expression within a @code{SECTIONS} command. The @code{.} symbol
895 may appear anywhere that an ordinary symbol is allowed in an
896 expression, but its assignments have a side effect. Assigning a value
897 to the @code{.} symbol will cause the location counter to be moved.
899 This may be used to create holes in the output section. The location
900 counter may never be moved backwards.
915 In the previous example, @code{file1} is located at the beginning of the
916 output section, then there is a 1000 byte gap. Then @code{file2}
917 appears, also with a 1000 byte gap following before @code{file3} is
918 loaded. The notation @samp{= 0x1234} specifies what data to write in
919 the gaps (@pxref{Section Options}).
922 @subsection Operators
923 @cindex Operators for arithmetic
924 @cindex arithmetic operators
925 @cindex precedence in expressions
926 The linker recognizes the standard C set of arithmetic operators, with
927 the standard bindings and precedence levels:
930 @c END TEXI2ROFF-KILL
932 precedence associativity Operators Notes
938 5 left == != > < <= >=
944 11 right &= += -= *= /= (2)
949 (2) @xref{Assignment}
954 %"lispnarrowing" is the extra indent used generally for @example
955 \hskip\lispnarrowing\vbox{\offinterlineskip
958 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
959 height2pt&\omit&&\omit&&\omit&\cr
960 &Precedence&& Associativity &&{\rm Operators}&\cr
961 height2pt&\omit&&\omit&&\omit&\cr
963 height2pt&\omit&&\omit&&\omit&\cr
965 % '176 is tilde, '~' in tt font
966 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
970 &5&&left&&== != > < <= >=&\cr
976 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
978 height2pt&\omit&&\omit&&\omit&\cr}
983 @obeylines@parskip=0pt@parindent=0pt
984 @dag@quad Prefix operators.
985 @ddag@quad @xref{Assignment}.
988 @c END TEXI2ROFF-KILL
991 @subsection Evaluation
993 @cindex lazy evaluation
994 @cindex expression evaluation order
995 The linker uses ``lazy evaluation'' for expressions; it only calculates
996 an expression when absolutely necessary. The linker needs the value of
997 the start address, and the lengths of memory regions, in order to do any
998 linking at all; these values are computed as soon as possible when the
999 linker reads in the command file. However, other values (such as symbol
1000 values) are not known or needed until after storage allocation. Such
1001 values are evaluated later, when other information (such as the sizes of
1002 output sections) is available for use in the symbol assignment
1006 @subsection Assignment: Defining Symbols
1007 @cindex assignment in scripts
1008 @cindex symbol definition, scripts
1009 @cindex variables, defining
1010 You may create global symbols, and assign values (addresses) to global
1011 symbols, using any of the C assignment operators:
1014 @item @var{symbol} = @var{expression} ;
1015 @itemx @var{symbol} &= @var{expression} ;
1016 @itemx @var{symbol} += @var{expression} ;
1017 @itemx @var{symbol} -= @var{expression} ;
1018 @itemx @var{symbol} *= @var{expression} ;
1019 @itemx @var{symbol} /= @var{expression} ;
1022 Two things distinguish assignment from other operators in @code{ld}
1026 Assignment may only be used at the root of an expression;
1027 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
1032 You must place a trailing semicolon (``@key{;}'') at the end of an
1033 assignment statement.
1036 Assignment statements may appear:
1039 as commands in their own right in an @code{ld} script; or
1041 as independent statements within a @code{SECTIONS} command; or
1043 as part of the contents of a section definition in a
1044 @code{SECTIONS} command.
1047 The first two cases are equivalent in effect---both define a symbol with
1048 an absolute address. The last case defines a symbol whose address is
1049 relative to a particular section (@pxref{SECTIONS}).
1051 @cindex absolute and relocatable symbols
1052 @cindex relocatable and absolute symbols
1053 @cindex symbols, relocatable and absolute
1054 When a linker expression is evaluated and assigned to a variable, it is
1055 given either an absolute or a relocatable type. An absolute expression
1056 type is one in which the symbol contains the value that it will have in
1057 the output file; a relocatable expression type is one in which the
1058 value is expressed as a fixed offset from the base of a section.
1060 The type of the expression is controlled by its position in the script
1061 file. A symbol assigned within a section definition is created relative
1062 to the base of the section; a symbol assigned in any other place is
1063 created as an absolute symbol. Since a symbol created within a
1064 section definition is relative to the base of the section, it
1065 will remain relocatable if relocatable output is requested. A symbol
1066 may be created with an absolute value even when assigned to within a
1067 section definition by using the absolute assignment function
1068 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
1069 is the last byte of an output section named @code{.data}:
1075 _edata = ABSOLUTE(.) ;
1080 The linker tries to put off the evaluation of an assignment until all
1081 the terms in the source expression are known (@pxref{Evaluation}). For
1082 instance, the sizes of sections cannot be known until after allocation,
1083 so assignments dependent upon these are not performed until after
1084 allocation. Some expressions, such as those depending upon the location
1085 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
1086 result of an expression is required, but the value is not available,
1087 then an error results. For example, a script like the following
1090 text 9+this_isnt_constant :
1095 @kindex Non constant expression
1097 will cause the error message ``@code{Non constant expression for initial
1100 @node Arithmetic Functions
1101 @subsection Arithmetic Functions
1102 @cindex functions in expression language
1103 The command language includes a number of built-in
1104 functions for use in link script expressions.
1106 @item ABSOLUTE(@var{exp})
1107 @kindex ABSOLUTE(@var{exp})
1108 @cindex expression, absolute
1109 Return the absolute (non-relocatable, as opposed to non-negative) value
1110 of the expression @var{exp}. Primarily useful to assign an absolute
1111 value to a symbol within a section definition, where symbol values are
1112 normally section-relative.
1114 @item ADDR(@var{section})
1115 @kindex ADDR(@var{section})
1116 @cindex section address
1117 Return the absolute address of the named @var{section}. Your script must
1118 previously have defined the location of that section. In the following
1119 example, @code{symbol_1} and @code{symbol_2} are assigned identical
1125 start_of_output_1 = ABSOLUTE(.);
1130 symbol_1 = ADDR(.output1);
1131 symbol_2 = start_of_output_1;
1136 @item ALIGN(@var{exp})
1137 @kindex ALIGN(@var{exp})
1138 @cindex rounding up location counter
1139 Return the result of the current location counter (@code{.}) aligned to
1140 the next @var{exp} boundary. @var{exp} must be an expression whose
1141 value is a power of two. This is equivalent to
1143 (. + @var{exp} - 1) & ~(@var{exp} - 1)
1146 @code{ALIGN} doesn't change the value of the location counter---it just
1147 does arithmetic on it. As an example, to align the output @code{.data}
1148 section to the next @code{0x2000} byte boundary after the preceding
1149 section and to set a variable within the section to the next
1150 @code{0x8000} boundary after the input sections:
1153 .data ALIGN(0x2000): @{
1155 variable = ALIGN(0x8000);
1160 The first use of @code{ALIGN} in this example specifies the location of
1161 a section because it is used as the optional @var{start} attribute of a
1162 section definition (@pxref{Section Options}). The second use simply
1163 defines the value of a variable.
1165 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1167 @item DEFINED(@var{symbol})
1168 @kindex DEFINED(@var{symbol})
1169 @cindex symbol defaults
1170 Return 1 if @var{symbol} is in the linker global symbol table and is
1171 defined, otherwise return 0. You can use this function to provide default
1172 values for symbols. For example, the following command-file fragment shows how
1173 to set a global symbol @code{begin} to the first location in the
1174 @code{.text} section---but if a symbol called @code{begin} already
1175 existed, its value is preserved:
1179 begin = DEFINED(begin) ? begin : . ;
1185 @item NEXT(@var{exp})
1186 @kindex NEXT(@var{exp})
1187 @cindex unallocated address, next
1188 Return the next unallocated address that is a multiple of @var{exp}.
1189 This function is closely related to @code{ALIGN(@var{exp})}; unless you
1190 use the @code{MEMORY} command to define discontinuous memory for the
1191 output file, the two functions are equivalent.
1193 @item SIZEOF(@var{section})
1194 @kindex SIZEOF(@var{section})
1195 @cindex section size
1196 Return the size in bytes of the named @var{section}, if that section has
1197 been allocated. In the following example, @code{symbol_1} and
1198 @code{symbol_2} are assigned identical values:
1199 @c What does it return if the section hasn't been allocated? 0?
1207 symbol_1 = .end - .start ;
1208 symbol_2 = SIZEOF(.output);
1213 @item SIZEOF_HEADERS
1214 @kindex SIZEOF_HEADERS
1216 @itemx sizeof_headers
1217 @kindex sizeof_headers
1218 Return the size in bytes of the output file's headers. You can use this number
1219 as the start address of the first section, if you choose, to facilitate
1225 @section Memory Layout
1227 @cindex regions of memory
1228 @cindex discontinuous memory
1229 @cindex allocating memory
1230 The linker's default configuration permits allocation of all available memory.
1231 You can override this configuration by using the @code{MEMORY} command. The
1232 @code{MEMORY} command describes the location and size of blocks of
1233 memory in the target. By using it carefully, you can describe which
1234 memory regions may be used by the linker, and which memory regions it
1235 must avoid. The linker does not shuffle sections to fit into the
1236 available regions, but does move the requested sections into the correct
1237 regions and issue errors when the regions become too full.
1239 A command file may contain at most one use of the @code{MEMORY}
1240 command; however, you can define as many blocks of memory within it as
1241 you wish. The syntax is:
1246 @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
1252 @cindex naming memory regions
1253 is a name used internally by the linker to refer to the region. Any
1254 symbol name may be used. The region names are stored in a separate
1255 name space, and will not conflict with symbols, file names or section
1256 names. Use distinct names to specify multiple regions.
1258 @cindex memory region attributes
1259 is an optional list of attributes, permitted for compatibility with the
1260 AT&T linker but not used by @code{ld} beyond checking that the
1261 attribute list is valid. Valid attribute lists must be made up of the
1262 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1263 omit the parentheses around it as well.
1268 is the start address of the region in physical memory. It is
1269 an expression that must evaluate to a constant before
1270 memory allocation is performed. The keyword @code{ORIGIN} may be
1271 abbreviated to @code{org} or @code{o} (but not, for example, @samp{ORG}).
1276 is the size in bytes of the region (an expression).
1277 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1280 For example, to specify that memory has two regions available for
1281 allocation---one starting at 0 for 256 kilobytes, and the other
1282 starting at @code{0x40000000} for four megabytes:
1287 rom : ORIGIN = 0, LENGTH = 256K
1288 ram : org = 0x40000000, l = 4M
1292 Once you have defined a region of memory named @var{mem}, you can direct
1293 specific output sections there by using a command ending in
1294 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1295 Options}). If the combined output sections directed to a region are too
1296 big for the region, the linker will issue an error message.
1299 @section Specifying Output Sections
1301 The @code{SECTIONS} command controls exactly where input sections are
1302 placed into output sections, their order in the output file, and to
1303 which output sections they are allocated.
1305 You may use at most one @code{SECTIONS} command in a script file,
1306 but you can have as many statements within it as you wish. Statements
1307 within the @code{SECTIONS} command can do one of three things:
1310 define the entry point;
1312 assign a value to a symbol;
1314 describe the placement of a named output section, and which input
1315 sections go into it.
1318 You can also use the first two operations---defining the entry point and
1319 defining symbols---outside the @code{SECTIONS} command: @pxref{Entry
1320 Point}, and @pxref{Assignment}. They are permitted here as well for
1321 your convenience in reading the script, so that symbols and the entry
1322 point can be defined at meaningful points in your output-file layout.
1324 When no @code{SECTIONS} command is given, the linker places each input
1325 section into an identically named output section in the order that the
1326 sections are first encountered in the input files. If all input sections
1327 are present in the first file, for example, the order of sections in the
1328 output file will match the order in the first input file.
1331 * Section Definition:: Section Definitions
1332 * Section Placement:: Section Placement
1333 * Section Data Expressions:: Section Data Expressions
1334 * Section Options:: Optional Section Attributes
1337 @node Section Definition
1338 @subsection Section Definitions
1339 @cindex section definition
1340 The most frequently used statement in the @code{SECTIONS} command is
1341 the @dfn{section definition}, which specifies the
1342 properties of an output section: its location, alignment, contents,
1343 fill pattern, and target memory region. Most of
1344 these specifications are optional; the simplest form of a section
1353 @cindex naming output sections
1355 @var{secname} is the name of the output section, and @var{contents} a
1356 specification of what goes there---for example, a list of input files or
1357 sections of input files (@pxref{Section Placement}). As you might
1358 assume, the whitespace shown is optional. You do need the colon
1359 @samp{:} and the braces @samp{@{@}}, however.
1361 @var{secname} must meet the constraints of your output format. In
1362 formats which only support a limited number of sections, such as
1363 @code{a.out}, the name must be one of the names supported by the format
1364 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1365 @code{.bss}). If the output format supports any number of sections, but
1366 with numbers and not names (as is the case for Oasys), the name should be
1367 supplied as a quoted numeric string. A section name may consist of any
1368 sequence of characters, but any name which does not conform to the standard
1369 @code{ld} symbol name syntax must be quoted.
1370 @xref{Symbols, , Symbol Names}.
1372 @node Section Placement
1373 @subsection Section Placement
1374 @cindex contents of a section
1375 In a section definition, you can specify the contents of an output section by
1376 listing particular input files, by listing particular input-file
1377 sections, or by a combination of the two. You can also place arbitrary
1378 data in the section, and define symbols relative to the beginning of the
1381 The @var{contents} of a section definition may include any of the
1382 following kinds of statement. You can include as many of these as you
1383 like in a single section definition, separated from one another by
1387 @item @var{filename}
1388 @kindex @var{filename}
1389 @cindex input files, section defn
1390 @cindex files, including in output sections
1391 You may simply name a particular input file to be placed in the current
1392 output section; @emph{all} sections from that file are placed in the
1393 current section definition. If the file name has already been mentioned
1394 in another section definition, with an explicit section name list, then
1395 only those sections which have not yet been allocated are used.
1397 To specify a list of particular files by name:
1399 .data : @{ afile.o bfile.o cfile.o @}
1402 The example also illustrates that multiple statements can be included in
1403 the contents of a section definition, since each file name is a separate
1406 @item @var{filename}( @var{section} )
1407 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1408 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1409 @kindex @var{filename}(@var{section})
1410 @cindex files and sections, section defn
1411 You can name one or more sections from your input files, for
1412 insertion in the current output section. If you wish to specify a list
1413 of input-file sections inside the parentheses, you may separate the
1414 section names by either commas or whitespace.
1416 @item * (@var{section})
1417 @itemx * (@var{section}, @var{section}, @dots{})
1418 @itemx * (@var{section} @var{section} @dots{})
1419 @cindex input sections to output section
1420 @kindex *(@var{section})
1421 Instead of explicitly naming particular input files in a link control
1422 script, you can refer to @emph{all} files from the @code{ld} command
1423 line: use @samp{*} instead of a particular file name before the
1424 parenthesized input-file section list.
1426 If you have already explicitly included some files by name, @samp{*}
1427 refers to all @emph{remaining} files---those whose places in the output
1428 file have not yet been defined.
1430 For example, to copy sections @code{1} through @code{4} from an Oasys file
1431 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1432 and @code{14} into the @code{.data} section:
1445 @samp{[ @var{section} @dots{} ]} used to be accepted as an alternate way
1446 to specify named sections from all unallocated input files. Because
1447 some operating systems (VMS) allow brackets in file names, that notation
1448 is no longer supported.
1450 @item @var{filename}@code{( COMMON )}
1453 @cindex uninitialized data
1454 @cindex commons in output
1455 Specify where in your output file to place uninitialized data
1456 with this notation. @code{*(COMMON)} by itself refers to all
1457 uninitialized data from all input files (so far as it is not yet
1458 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1459 from a particular file. Both are special cases of the general
1460 mechanisms for specifying where to place input-file sections:
1461 @code{ld} permits you to refer to uninitialized data as if it
1462 were in an input-file section named @code{COMMON}, regardless of the
1463 input file's format.
1466 For example, the following command script arranges the output file into
1467 three consecutive sections, named @code{.text}, @code{.data}, and
1468 @code{.bss}, taking the input for each from the correspondingly named
1469 sections of all the input files:
1472 .text : @{ *(.text) @}
1473 .data : @{ *(.data) @}
1474 .bss : @{ *(.bss) *(COMMON) @}
1478 The following example reads all of the sections from file @code{all.o}
1479 and places them at the start of output section @code{outputa} which
1480 starts at location @code{0x10000}. All of section @code{.input1} from
1481 file @code{foo.o} follows immediately, in the same output section. All
1482 of section @code{.input2} from @code{foo.o} goes into output section
1483 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1484 All of the remaining @code{.input1} and @code{.input2} sections from any
1485 files are written to output section @code{outputc}.
1507 @node Section Data Expressions
1508 @subsection Section Data Expressions
1509 @cindex expressions in a section
1510 The foregoing statements
1511 arrange, in your output file, data originating from your input files.
1512 You can also place data directly in an output section from the link
1513 command script. Most of these additional statements involve
1514 expressions; @pxref{Expressions}. Although these statements are shown
1515 separately here for ease of presentation, no such segregation is needed
1516 within a section definition in the @code{SECTIONS} command; you can
1517 intermix them freely with any of the statements we've just described.
1520 @item CREATE_OBJECT_SYMBOLS
1521 @kindex CREATE_OBJECT_SYMBOLS
1522 @cindex input filename symbols
1523 @cindex filename symbols
1524 Create a symbol for each input file
1525 in the current section, set to the address of the first byte of
1526 data written from that input file. For instance, with @code{a.out}
1527 files it is conventional to have a symbol for each input file. You can
1528 accomplish this by defining the output @code{.text} section as follows:
1533 CREATE_OBJECT_SYMBOLS
1535 _etext = ALIGN(0x2000);
1541 If @code{sample.ld} is a file containing this script, and @code{a.o},
1542 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1543 contents like the following---
1553 @samp{ld -M -T sample.ld a.o b.o c.o d.o} would create a map like this,
1554 containing symbols matching the object file names:
1556 00000000 A __DYNAMIC
1559 00002020 T _afunction
1562 00002038 T _bfunction
1565 00002050 T _cfunction
1568 00002068 T _dfunction
1578 @item @var{symbol} = @var{expression} ;
1579 @kindex @var{symbol} = @var{expression} ;
1580 @itemx @var{symbol} @var{f}= @var{expression} ;
1581 @kindex @var{symbol} @var{f}= @var{expression} ;
1582 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1583 refers to any of the operators @code{&= += -= *= /=} which combine
1584 arithmetic and assignment.
1586 @cindex assignment, in section defn
1587 When you assign a value to a symbol within a particular section
1588 definition, the value is relative to the beginning of the section
1589 (@pxref{Assignment}). If you write
1594 .data : @{ @dots{} rel = 14 ; @dots{} @}
1595 abs2 = 14 + ADDR(.data);
1599 @c FIXME: Try above example!
1601 @code{abs} and @code{rel} do not have the same value; @code{rel} has the
1602 same value as @code{abs2}.
1604 @item BYTE(@var{expression})
1605 @kindex BYTE(@var{expression})
1606 @itemx SHORT(@var{expression})
1607 @kindex SHORT(@var{expression})
1608 @itemx LONG(@var{expression})
1609 @kindex LONG(@var{expression})
1610 @cindex direct output
1611 By including one of these three statements in a section definition, you
1612 can explicitly place one, two, or four bytes (respectively) at the
1613 current address of that section.
1615 @ifclear SingleFormat
1616 Multiple-byte quantities are represented in whatever byte order is
1617 appropriate for the output file format (@pxref{BFD}).
1620 @item FILL(@var{expression})
1621 @kindex FILL(@var{expression})
1622 @cindex holes, filling
1623 @cindex unspecified memory
1624 Specify the ``fill pattern'' for the current section. Any otherwise
1625 unspecified regions of memory within the section (for example, regions
1626 you skip over by assigning a new value to the location counter @samp{.})
1627 are filled with the two least significant bytes from the
1628 @var{expression} argument. A @code{FILL} statement covers memory
1629 locations @emph{after} the point it occurs in the section definition; by
1630 including more than one @code{FILL} statement, you can have different
1631 fill patterns in different parts of an output section.
1634 @node Section Options
1635 @subsection Optional Section Attributes
1636 @cindex section defn, full syntax
1637 Here is the full syntax of a section definition, including all the
1643 @var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : @{ @var{contents} @} =@var{fill} >@var{region}
1648 @var{secname} and @var{contents} are required. @xref{Section
1649 Definition}, and @pxref{Section Placement} for details on @var{contents}.
1650 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1651 @code{(NOLOAD)} @code{=@var{fill}}, and @code{>@var{region}}---are all
1656 @cindex start address, section
1657 @cindex section start
1658 @cindex section address
1659 You can force the output section to be loaded at a specified address by
1660 specifying @var{start} immediately following the section name.
1661 @var{start} can be represented as any expression. The following
1662 example generates section @var{output} at location
1667 output 0x40000000: @{
1674 @item BLOCK(@var{align})
1675 @kindex BLOCK(@var{align})
1676 @cindex section alignment
1677 @cindex aligning sections
1678 You can include @code{BLOCK()} specification to advance
1679 the location counter @code{.} prior to the beginning of the section, so
1680 that the section will begin at the specified alignment. @var{align} is
1685 @cindex prevent unnecessary loading
1686 Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
1687 each time it is accessed. For example, in the script sample below, the
1688 @code{ROM} segment is addressed at memory location @samp{0} and does not
1689 need to be loaded into each object file:
1692 ROM 0 (NOLOAD) : @{ @dots{} @}
1699 @cindex section fill pattern
1700 @cindex fill pattern, entire section
1702 @code{=@var{fill}} in a section definition specifies the initial fill
1703 value for that section.
1704 You may use any expression to specify @var{fill}.
1705 Any unallocated holes in the current output
1706 section when written to the output file will be filled with the two
1707 least significant bytes of the value, repeated as necessary. You can
1708 also change the fill value with a @code{FILL} statement in the
1709 @var{contents} of a section definition.
1712 @kindex >@var{region}
1713 @cindex section, assigning to memory region
1714 @cindex memory regions and sections
1715 Assign this section to a previously defined region of memory.
1721 @section The Entry Point
1722 @kindex ENTRY(@var{symbol})
1723 @cindex start of execution
1724 @cindex first instruction
1725 The linker command language includes a command specifically for
1726 defining the first executable instruction in an output file (its
1727 @dfn{entry point}). Its argument is a symbol name:
1732 Like symbol assignments, the @code{ENTRY} command may be placed either
1733 as an independent command in the command file, or among the section
1734 definitions within the @code{SECTIONS} command---whatever makes the most
1735 sense for your layout.
1737 @cindex entry point, defaults
1738 @code{ENTRY} is only one of several ways of choosing the entry point.
1739 You may indicate it in any of the following ways (shown in descending
1740 order of priority: methods higher in the list override methods lower down).
1743 the @samp{-e} @var{entry} command-line option;
1745 the @code{ENTRY(@var{symbol}} command in a linker control script;
1747 the value of the symbol @code{start}, if present;
1749 the value of the symbol @code{_main}, if present;
1751 the address of the first byte of the @code{.text} section, if present;
1753 The address @code{0}.
1756 For example, you can use these rules to generate an entry point with an
1757 assignment statement: if no symbol @code{start} is defined within your
1758 input files, you can simply define it, assigning it an appropriate
1765 The example shows an absolute address, but you can use any expression.
1766 For example, if your input object files use some other symbol-name
1767 convention for the entry point, you can just assign the value of
1768 whatever symbol contains the start address to @code{start}:
1770 start = other_symbol ;
1773 @node Option Commands
1774 @section Option Commands
1775 The command language includes a number of other commands that you can
1776 use for specialized purposes. They are similar in purpose to
1777 command-line options.
1784 These keywords were used in some older linkers to request a particular
1785 math subroutine library. @code{ld} doesn't use the keywords, assuming
1786 instead that any necessary subroutines are in libraries specified using
1787 the general mechanisms for linking to archives; but to permit the use of
1788 scripts that were written for the older linkers, the keywords
1789 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1791 @item FORCE_COMMON_ALLOCATION
1792 @kindex FORCE_COMMON_ALLOCATION
1793 @cindex common allocation
1794 This command has the same effect as the @samp{-d} command-line option:
1795 to make @code{ld} assign space to common symbols even if a relocatable
1796 output file is specified (@samp{-r}).
1798 @item INPUT ( @var{file}, @var{file}, @dots{} )
1799 @kindex INPUT ( @var{files} )
1800 @itemx INPUT ( @var{file} @var{file} @dots{} )
1801 @cindex binary input files
1802 Use this command to include binary input files in the link, without
1803 including them in a particular section definition.
1804 Specify the full name for each @var{file}, including @samp{.a} if
1807 @code{ld} searches for each @var{file} through the archive-library
1808 search path, just as for files you specify on the command line.
1809 See the description of @samp{-L} in @ref{Options,,Command Line
1813 @item MAP ( @var{name} )
1814 @kindex MAP ( @var{name} )
1815 @c MAP(...) appears to look for an F in the arg, ignoring all other
1816 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1817 @c checks map_option_f. Apparently a stub for the future...
1820 @item OUTPUT ( @var{filename} )
1821 @kindex OUTPUT ( @var{filename} )
1822 @cindex naming the output file
1823 Use this command to name the link output file @var{filename}. The
1824 effect of @code{OUTPUT(@var{filename})} is identical to the effect of
1825 @w{@samp{-o @var{filename}}}, and whichever is encountered last
1826 (@samp{-T} or @samp{-o} will control the name actually used to name the
1827 output file. In particular, you can use this command to supply a
1828 default output-file name other than @code{a.out}.
1830 @ifclear SingleFormat
1831 @item OUTPUT_ARCH ( @var{bfdname} )
1832 @kindex OUTPUT_ARCH ( @var{bfdname} )
1833 @cindex machine architecture, output
1834 Specify a particular output machine architecture, with one of the names
1835 used by the BFD back-end routines (@pxref{BFD}). This command is often
1836 unnecessary; the architecture is most often set implicitly by either the
1837 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1840 @item OUTPUT_FORMAT ( @var{bfdname} )
1841 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1842 @cindex format, output file
1843 Specify a particular output format, with one of the names used by the
1844 BFD back-end routines (@pxref{BFD}). The effect is identical to the
1845 effect of the @samp{-oformat} command-line option.
1846 This selection will only affect
1847 the output file; the related command @code{TARGET} affects primarily
1851 @item SEARCH_DIR ( @var{path} )
1852 @kindex SEARCH_DIR ( @var{path} )
1853 @cindex path for libraries
1854 @cindex search path, libraries
1855 Add @var{path} to the list of paths where @code{ld} looks for
1856 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1857 effect as @samp{-L@var{path}} on the command line.
1859 @item STARTUP ( @var{filename} )
1860 @kindex STARTUP ( @var{filename} )
1861 @cindex first input file
1862 Ensure that @var{filename} is the first input file used in the link
1865 @ifclear SingleFormat
1866 @item TARGET ( @var{format} )
1867 @cindex input file format
1868 @kindex TARGET ( @var{format} )
1869 Change the input-file object code format (like the command-line option
1870 @samp{-b} or its synonym @samp{-format}). The argument @var{format} is
1871 one of the strings used by BFD to name binary formats. If @code{TARGET}
1872 is specified but @code{OUTPUT_FORMAT} is not, the last @code{TARGET}
1873 argument is also used as the default format for the @code{ld} output
1877 If you don't use the @code{TARGET} command, @code{ld} uses the value of
1878 the environment variable @code{GNUTARGET}, if available, to select the
1879 output file format. If that variable is also absent, @code{ld} uses
1880 the default format configured for your machine in the BFD libraries.
1885 @node Machine Dependent
1886 @chapter Machine Dependent Features
1888 @cindex machine dependencies
1889 @code{ld} has additional features on some platforms; the following
1890 sections describe them. Machines where @code{ld} has no additional
1891 functionality are not listed.
1894 * H8/300:: @code{ld} and the H8/300
1895 * i960:: @code{ld} and the Intel 960 family
1899 @c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict
1900 @c between those and node-defaulting.
1906 @section @code{ld} and the H8/300
1908 @cindex H8/300 support
1909 For the H8/300, @code{ld} can perform these global optimizations when
1910 you specify the @samp{-relax} command-line option.
1913 @item relaxing address modes
1914 @cindex relaxing on H8/300
1915 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
1916 targets are within eight bits, and turns them into eight-bit
1917 program-counter relative @code{bsr} and @code{bra} instructions,
1920 @item synthesizing instructions
1921 @cindex synthesizing on H8/300
1922 @c FIXME: specifically mov.b, or any mov instructions really?
1923 @code{ld} finds all @code{mov.b} instructions which use the
1924 sixteen-bit absolute address form, but refer to the top
1925 page of memory, and changes them to use the eight-bit address form.
1926 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1927 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1928 top page of memory).
1940 @section @code{ld} and the Intel 960 family
1942 @cindex i960 support
1944 You can use the @samp{-A@var{architecture}} command line option to
1945 specify one of the two-letter names identifying members of the 960
1946 family; the option specifies the desired output target, and warns of any
1947 incompatible instructions in the input files. It also modifies the
1948 linker's search strategy for archive libraries, to support the use of
1949 libraries specific to each particular architecture, by including in the
1950 search loop names suffixed with the string identifying the architecture.
1952 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
1953 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1954 paths, and in any paths you specify with @samp{-L}) for a library with
1965 The first two possibilities would be considered in any event; the last
1966 two are due to the use of @w{@samp{-ACA}}.
1968 You can meaningfully use @samp{-A} more than once on a command line, since
1969 the 960 architecture family allows combination of target architectures; each
1970 use will add another pair of name variants to search for when @w{@samp{-l}}
1971 specifies a library.
1977 @ifclear SingleFormat
1982 @cindex object file management
1983 The linker accesses object and archive files using the BFD libraries.
1984 These libraries allow the linker to use the same routines to operate on
1985 object files whatever the object file format. A different object file
1986 format can be supported simply by creating a new BFD back end and adding
1987 it to the library. You can use @code{objdump -i}
1988 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
1989 list all the formats available for each architecture under BFD. This
1990 was the list of formats, and of architectures supported for each format,
1991 as of the time this manual was prepared:
1992 @cindex formats available
1993 @cindex architectures available
1995 BFD header file version 0.18
1997 (header big endian, data big endian)
2003 (header big endian, data big endian)
2009 (header big endian, data little endian)
2012 (header little endian, data little endian)
2015 (header big endian, data big endian)
2018 (header big endian, data big endian)
2021 (header little endian, data little endian)
2024 (header big endian, data little endian)
2027 (header little endian, data little endian)
2030 (header big endian, data big endian)
2033 (header big endian, data big endian)
2036 (header big endian, data big endian)
2039 (header little endian, data little endian)
2042 (header big endian, data big endian)
2054 (header little endian, data little endian)
2066 (header big endian, data big endian)
2078 (header big endian, data big endian)
2091 @cindex BFD requirements
2092 @cindex requirements for BFD
2093 As with most implementations, BFD is a compromise between
2094 several conflicting requirements. The major factor influencing
2095 BFD design was efficiency: any time used converting between
2096 formats is time which would not have been spent had BFD not
2097 been involved. This is partly offset by abstraction payback; since
2098 BFD simplifies applications and back ends, more time and care
2099 may be spent optimizing algorithms for a greater speed.
2101 One minor artifact of the BFD solution which you should bear in
2102 mind is the potential for information loss. There are two places where
2103 useful information can be lost using the BFD mechanism: during
2104 conversion and during output. @xref{BFD information loss}.
2107 * BFD outline:: How it works: an outline of BFD
2111 @section How it works: an outline of BFD
2112 @cindex opening object files
2113 @include bfdsumm.texi
2117 @appendix MRI Compatible Script Files
2118 @cindex MRI compatibility
2119 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
2120 linker, @code{ld} can use MRI compatible linker scripts as an
2121 alternative to the more general-purpose linker scripting language
2122 described in @ref{Commands,,Command Language}. MRI compatible linker
2123 scripts have a much simpler command set than the scripting language
2124 otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
2125 commonly used MRI linker commands; these commands are described here.
2127 In general, MRI scripts aren't of much use with the @code{a.out} object
2128 file format, since it only has three sections and MRI scripts lack some
2129 features to make use of them.
2131 You can specify a file containing an MRI-compatible script using the
2132 @samp{-c} command-line option.
2134 Each command in an MRI-compatible script occupies its own line; each
2135 command line starts with the keyword that identifies the command (though
2136 blank lines are also allowed for punctuation). If a line of an
2137 MRI-compatible script begins with an unrecognized keyword, @code{ld}
2138 issues a warning message, but continues processing the script.
2140 Lines beginning with @samp{*} are comments.
2142 You can write these commands using all upper-case letters, or all
2143 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
2144 The following list shows only the upper-case form of each command.
2147 @item ABSOLUTE @var{secname}
2148 @item ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
2149 @cindex @code{ABSOLUTE} (MRI)
2150 Normally, @code{ld} includes in the output file all sections from all
2151 the input files. However, in an MRI-compatible script, you can use the
2152 @code{ABSOLUTE} command to restrict the sections that will be present in
2153 your output program. If the @code{ABSOLUTE} command is used at all in a
2154 script, then only the sections named explicitly in @code{ABSOLUTE}
2155 commands will appear in the linker output. You can still use other
2156 input sections (whatever you select on the command line, or using
2157 @code{LOAD}) to resolve addresses in the output file.
2159 @item ALIAS @var{out-secname}, @var{in-secname}
2160 @cindex @code{ALIAS} (MRI)
2161 Use this command to place the data from input section @var{in-secname}
2162 in a section called @var{out-secname} in the linker output file.
2164 @var{in-secname} may be an integer.
2166 @item BASE @var{expression}
2167 @cindex @code{BASE} (MRI)
2168 Use the value of @var{expression} as the lowest address (other than
2169 absolute addresses) in the output file.
2171 @item CHIP @var{expression}
2172 @itemx CHIP @var{expression}, @var{expression}
2173 @cindex @code{CHIP} (MRI)
2174 This command does nothing; it is accepted only for compatibility.
2177 @cindex @code{END} (MRI)
2178 This command does nothing whatever; it's only accepted for compatibility.
2180 @item FORMAT @var{output-format}
2181 @cindex @code{FORMAT} (MRI)
2182 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
2183 language, but restricted to one of these output formats:
2186 S-records, if @var{output-format} is @samp{S}
2189 IEEE, if @var{output-format} is @samp{IEEE}
2192 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
2196 @item LIST @var{anything}@dots{}
2197 @cindex @code{LIST} (MRI)
2198 Print (to the standard output file) a link map, as produced by the
2199 @code{ld} command-line option @samp{-M}.
2201 The keyword @code{LIST} may be followed by anything on the
2202 same line, with no change in its effect.
2204 @item LOAD @var{filename}
2205 @item LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
2206 @cindex @code{LOAD} (MRI)
2207 Include one or more object file @var{filename} in the link; this has the
2208 same effect as specifying @var{filename} directly on the @code{ld}
2211 @item NAME @var{output-name}
2212 @cindex @code{NAME} (MRI)
2213 @var{output-name} is the name for the program produced by @code{ld}; the
2214 MRI-compatible command @code{NAME} is equivalent to the command-line
2215 option @samp{-o} or the general script language command @code{OUTPUT}.
2217 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
2218 @itemx ORDER @var{secname} @var{secname} @var{secname}
2219 @cindex @code{ORDER} (MRI)
2220 Normally, @code{ld} orders the sections in its output file in the
2221 order in which they first appear in the input files. In an MRI-compatible
2222 script, you can override this ordering with the @code{ORDER} command. The
2223 sections you list with @code{ORDER} will appear first in your output
2224 file, in the order specified.
2226 @item PUBLIC @var{name}=@var{expression}
2227 @itemx PUBLIC @var{name},@var{expression}
2228 @itemx PUBLIC @var{name} @var{expression}
2229 @cindex @code{PUBLIC} (MRI)
2230 Supply a value (@var{expression}) for external symbol
2231 @var{name} used in the linker input files.
2233 @item SECT @var{secname}, @var{expression}
2234 @itemx SECT @var{secname}=@var{expression}
2235 @itemx SECT @var{secname} @var{expression}
2236 @cindex @code{SECT} (MRI)
2237 You can use any of these three forms of the @code{SECT} command to
2238 specify the start address (@var{expression}) for section @var{secname}.
2239 If you have more than one @code{SECT} statement for the same
2240 @var{secname}, only the @emph{first} sets the start address.
2250 % I think something like @colophon should be in texinfo. In the
2252 \long\def\colophon{\hbox to0pt{}\vfill
2253 \centerline{The body of this manual is set in}
2254 \centerline{\fontname\tenrm,}
2255 \centerline{with headings in {\bf\fontname\tenbf}}
2256 \centerline{and examples in {\tt\fontname\tentt}.}
2257 \centerline{{\it\fontname\tenit\/} and}
2258 \centerline{{\sl\fontname\tensl\/}}
2259 \centerline{are used for emphasis.}\vfill}
2261 % Blame: pesch@cygnus.com, 28mar91.