4 @c @include configdoc.texi
12 * Ld:: The GNU linker.
18 This file documents the GNU linker LD.
20 Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
22 Permission is granted to make and distribute verbatim copies of
23 this manual provided the copyright notice and this permission notice
24 are preserved on all copies.
26 Permission is granted to copy and distribute modified versions of this
27 manual under the conditions for verbatim copying, provided also that
28 the entire resulting derived work is distributed under the terms of a
29 permission notice identical to this one.
31 Permission is granted to copy and distribute translations of this manual
32 into another language, under the above conditions for modified versions.
35 Permission is granted to process this file through Tex and print the
36 results, provided the printed document carries copying permission
37 notice identical to this one except for the removal of this paragraph
38 (this paragraph not being relevant to the printed manual).
44 @setchapternewpage odd
45 @settitle Using LD, the GNU linker
48 @subtitle The GNU linker
50 @subtitle @code{ld} version 2
52 @author Steve Chamberlain and Roland Pesch
53 @author Cygnus Support
58 \hfill Cygnus Support\par
59 \hfill steve\@cygnus.com, pesch\@cygnus.com\par
60 \hfill {\it Using LD, the GNU linker}\par
61 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com), March 1993.\par
63 \global\parindent=0pt % Steve likes it this way.
66 @vskip 0pt plus 1filll
67 Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
69 Permission is granted to make and distribute verbatim copies of
70 this manual provided the copyright notice and this permission notice
71 are preserved on all copies.
73 Permission is granted to copy and distribute modified versions of this
74 manual under the conditions for verbatim copying, provided also that
75 the entire resulting derived work is distributed under the terms of a
76 permission notice identical to this one.
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions.
82 @c FIXME: Talk about importance of *order* of args, cmds to linker!
87 This file documents the GNU linker ld.
91 * Invocation:: Invocation
92 * Commands:: Command Language
94 * Machine Dependent:: Machine Dependent Features
98 * H8/300:: ld and the H8/300
101 * i960:: ld and the Intel 960 family
104 @ifclear SingleFormat
107 @c Following blank line required for remaining bug in makeinfo conds/menus
109 * MRI:: MRI Compatible Script Files
118 @cindex what is this?
119 @code{ld} combines a number of object and archive files, relocates
120 their data and ties up symbol references. Usually the last step in
121 compiling a program is to run @code{ld}.
123 @code{ld} accepts Linker Command Language files written in
124 a superset of AT&T's Link Editor Command Language syntax,
125 to provide explicit and total control over the linking process.
127 @ifclear SingleFormat
128 This version of @code{ld} uses the general purpose BFD libraries
129 to operate on object files. This allows @code{ld} to read, combine, and
130 write object files in many different formats---for example, COFF or
131 @code{a.out}. Different formats may be linked together to produce any
132 available kind of object file. @xref{BFD} for a list of formats
133 supported on various architectures.
136 Aside from its flexibility, the GNU linker is more helpful than other
137 linkers in providing diagnostic information. Many linkers abandon
138 execution immediately upon encountering an error; whenever possible,
139 @code{ld} continues executing, allowing you to identify other errors
140 (or, in some cases, to get an output file in spite of the error).
145 The GNU linker @code{ld} is meant to cover a broad range of situations,
146 and to be as compatible as possible with other linkers. As a result,
147 you have many choices to control its behavior.
151 * Options:: Command Line Options
152 * Environment:: Environment Variables
156 @section Command Line Options
161 Here is a summary of the options you can use on the @code{ld} command
164 @c FIXME! -relax only avail h8/300, i960. Conditionals screwed in examples.
166 ld [ -o @var{output} ] @var{objfile}@dots{}
167 [ -A@var{architecture} ] [ -b @var{input-format} ] [ -Bstatic ]
168 [ -c @var{MRI-commandfile} ] [ -d | -dc | -dp ]
169 [ -defsym @var{symbol}=@var{expression} ]
170 [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
171 [ -format @var{input-format} ] [ -g ] [ -G @var{size} ] [ --help ] [ -i ]
172 [ -l@var{archive} ] [ -L@var{searchdir} ] [ -M ] [ -Map @var{mapfile} ]
173 [ -m @var{emulation} ] [ -N | -n ] [ -noinhibit-exec ]
174 [ -oformat @var{output-format} ] [ -R @var{filename} ] [ -relax ]
175 [ -r | -Ur ] [ -S ] [ -s ] [ -sort-common ] [ -T @var{commandfile} ]
176 [ -Ttext @var{textorg} ] [ -Tdata @var{dataorg} ]
177 [ -Tbss @var{bssorg} ] [ -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 other
220 forms of binary input files can also be specified with @samp{-l},
221 @samp{-R}, and the script command language. If @emph{no} binary input
222 files at all are specified, the linker does not produce any output, and
223 issues the message @samp{No input files}.
225 Option arguments must either follow the option letter without intervening
226 whitespace, or be given as separate arguments immediately following the
227 option that requires them.
231 @cindex architectures
233 @item -A@var{architecture}
234 In the current release of @code{ld}, this option is useful only for the
235 Intel 960 family of architectures. In that @code{ld} configuration, the
236 @var{architecture} argument identifies the particular architecture in
237 the 960 family, enabling some safeguards and modifying the
238 archive-library search path. @xref{i960,,@code{ld} and the Intel 960
239 family}, for details.
241 Future releases of @code{ld} may support similar functionality for
242 other architecture families.
245 @ifclear SingleFormat
246 @cindex binary input format
247 @kindex -b @var{format}
249 @item -b @var{input-format}
251 Specify the binary format for input object files that follow this option
252 on the command line. You don't usually need to specify this, as
253 @code{ld} is configured to expect as a default input format the most
254 usual format on each machine. @var{input-format} is a text string, the
255 name of a particular format supported by the BFD libraries.
256 (You can list the available binary formats with @samp{objdump -i}.)
257 @w{@samp{-format @var{input-format}}} has the same effect, as does the
258 script command @code{TARGET}. @xref{BFD}.
260 You may want to use this option if you are linking files with an unusual
261 binary format. You can also use @samp{-b} to switch formats explicitly (when
262 linking object files of different formats), by including
263 @samp{-b @var{input-format}} before each group of object files in a
266 The default format is taken from the environment variable
271 You can also define the input
272 format from a script, using the command @code{TARGET}; see @ref{Other
278 Ignored. This option is accepted for command-line compatibility with
281 @kindex -c @var{MRI-cmdfile}
282 @cindex compatibility, MRI
283 @item -c @var{MRI-commandfile}
284 For compatibility with linkers produced by MRI, @code{ld} accepts script
285 files written in an alternate, restricted command language, described in
286 @ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
287 the option @samp{-c}; use the @samp{-T} option to run linker
288 scripts written in the general-purpose @code{ld} scripting language.
289 If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
290 specified by any @samp{-L} options.
292 @cindex common allocation
299 These three options are equivalent; multiple forms are supported for
300 compatibility with other linkers. They
301 assign space to common symbols even if a relocatable output file is
302 specified (with @samp{-r}). The script command
303 @code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Other
306 @cindex symbols, from command line
307 @kindex -defsym @var{symbol}=@var{exp}
308 @item -defsym @var{symbol}=@var{expression}
309 Create a global symbol in the output file, containing the absolute
310 address given by @var{expression}. You may use this option as many
311 times as necessary to define multiple symbols in the command line. A
312 limited form of arithmetic is supported for the @var{expression} in this
313 context: you may give a hexadecimal constant or the name of an existing
314 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
315 constants or symbols. If you need more elaborate expressions, consider
316 using the linker command language from a script (@pxref{Assignment, ,
317 Assignment: Symbol Definitions}). @emph{Note:} there should be no
318 white space between @var{symbol}, the equals sign (``@key{=}''), and
321 @cindex entry point, from command line
322 @kindex -e @var{entry}
324 Use @var{entry} as the explicit symbol for beginning execution of your
325 program, rather than the default entry point. @xref{Entry Point}, for a
326 discussion of defaults and other ways of specifying the
329 @ifclear SingleFormat
332 @itemx -F@var{format}
333 Ignored. Some older linkers used this option throughout a compilation
334 toolchain for specifying object-file format for both input and output
335 object files. The mechanisms @code{ld} uses for this purpose (the
336 @samp{-b} or @samp{-format} options for input files, the @code{TARGET}
337 command in linker scripts for output files, the @code{GNUTARGET}
338 environment variable) are more flexible, but @code{ld} accepts the
339 @samp{-F} option for compatibility with scripts written to call the old
343 @item -format @var{input-format}
344 Synonym for @samp{-b @var{input-format}}.
349 Ignored. Provided for compatibility with other tools.
354 @itemx -G @var{value}
355 Set the maximum size of objects to be optimized using the GP register to
356 @var{size} under MIPS ECOFF. Ignored for other object file formats.
362 Print a summary of the command-line options on the standard output and exit.
363 This option and @samp{--version} begin with two dashes instead of one
364 for compatibility with other GNU programs. The other options start with
365 only one dash for compatibility with other linkers.
368 @cindex incremental link
370 Perform an incremental link (same as option @samp{-r}).
372 @cindex archive files, from cmd line
373 @kindex -l@var{archive}
375 Add archive file @var{archive} to the list of files to link. This
376 option may be used any number of times. @code{ld} will search its
377 path-list for occurrences of @code{lib@var{ar}.a} for every @var{archive}
380 @cindex search directory, from cmd line
382 @item -L@var{searchdir}
383 Add path @var{searchdir} to the list of paths that @code{ld} will search
384 for archive libraries and @code{ld} control scripts. You may use this
385 option any number of times.
388 The default set of paths searched (without being specified with
389 @samp{-L}) depends on which emulation mode @code{ld} is using, and in
390 some cases also on how it was configured. @xref{Environment}.
393 The paths can also be specified in a link script with the
394 @code{SEARCH_DIR} command.
399 Print (to the standard output) a link map---diagnostic information
400 about where symbols are mapped by @code{ld}, and information on global
401 common storage allocation.
405 @item -Map @var{mapfile}
406 Print to the file @var{mapfile} a link map---diagnostic information
407 about where symbols are mapped by @code{ld}, and information on global
408 common storage allocation.
411 @kindex -m @var{emulation}
412 @item -m@var{emulation}
413 @itemx -m @var{emulation}
414 Emulate the @var{emulation} linker. You can list the available
415 emulations with the @samp{-V} option. The
416 default is the system for which you configured @code{ld}.
419 @cindex read/write from cmd line
422 Set the text and data sections to be readable and writable. Also, do
423 not page-align the data segment. If the output format supports Unix
424 style magic numbers, mark the output as @code{OMAGIC}.
428 @cindex read-only text
430 Set the text segment to be read only, and mark the output as
431 @code{NMAGIC} if possible.
433 @item -noinhibit-exec
434 @cindex output file after errors
435 @kindex -noinhibit-exec
436 Retain the executable output file whenever it is still usable.
437 Normally, the linker will not produce an output file if it encounters
438 errors during the link process; it exits without writing an output file
439 when it issues any error whatsoever.
441 @item -o @var{output}
442 @kindex -o @var{output}
443 @cindex naming the output file
444 Use @var{output} as the name for the program produced by @code{ld}; if this
445 option is not specified, the name @file{a.out} is used by default. The
446 script command @code{OUTPUT} can also specify the output file name.
449 @item -oformat @var{output-format}
450 Specify the binary format for the output object file. You don't usually
451 need to specify this, as @code{ld} is configured to produce as a default
452 output format the most usual format on each machine.
453 @var{output-format} is a text string, the name of a particular format
454 supported by the BFD libraries. (You can list the available binary
455 formats with @samp{objdump -i}.) The script command
456 @code{OUTPUT_FORMAT} can also specify the output format, but this option
457 overrides it. @xref{BFD}.
459 @item -R @var{filename}
460 @kindex -R @var{file}
461 @cindex symbol-only input
462 On some platforms, this option performs global optimizations
463 that become possible when the linker resolves addressing in the
464 program, such as relaxing address modes and synthesizing new
465 instructions in the output object file.
469 @cindex synthesizing linker
470 @cindex relaxing addressing modes
471 An option with machine dependent effects. Currently this option is only
472 supported on the H8/300.
474 @xref{H8/300,,@code{ld} and the H8/300}.
477 On some platforms, use option performs global optimizations that
478 become possible when the linker resolves addressing in the program, such
479 as relaxing address modes and synthesizing new instructions in the
482 On platforms where this is not supported, @samp{-relax} is accepted, but
487 @cindex relocatable output
489 Generate relocatable output---i.e., generate an output file that can in
490 turn serve as input to @code{ld}. This is often called @dfn{partial
491 linking}. As a side effect, in environments that support standard Unix
492 magic numbers, this option also sets the output file's magic number to
495 If this option is not specified, an absolute file is produced. When
496 linking C++ programs, this option @emph{will not} resolve references to
497 constructors; to do that, use @samp{-Ur}.
499 This option does the same as @code{-i}.
503 @cindex strip debugger symbols
504 Omit debugger symbol information (but not all symbols) from the output file.
508 @cindex strip all symbols
509 Omit all symbol information from the output file.
512 Normally, when @code{ld} places the global common symbols in the
513 appropriate output sections, it sorts them by size. First come all the
514 one byte symbols, then all the two bytes, then all the four bytes, and
515 then everything else. This option disables that sorting.
517 @item -Tbss @var{bssorg}
518 @kindex -Tbss @var{bssorg}
519 @itemx -Tdata @var{dataorg}
520 @kindex -Tdata @var{dataorg}
521 @itemx -Ttext @var{textorg}
522 @kindex -Ttext @var{textorg}
523 @cindex segment origins, cmd line
524 Use @var{org} as the starting address for---respectively---the
525 @code{bss}, @code{data}, or the @code{text} segment of the output file.
526 @var{org} must be a single hexadecimal integer;
527 for compatibility with other linkers, you may omit the leading
528 @samp{0x} usually associated with hexadecimal values.
530 @item -T @var{commandfile}
531 @itemx -T@var{commandfile}
532 @kindex -T @var{script}
534 Read link commands from the file @var{commandfile}. These commands
535 completely override @code{ld}'s default link format (rather than adding
536 to it); @var{commandfile} must specify everything necessary to describe
537 the target format. @xref{Commands}. If @var{commandfile} does not
538 exist, @code{ld} looks for it in the directories specified by any
539 preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
544 @cindex input files, displaying
545 Print the names of the input files as @code{ld} processes them.
547 @item -u @var{symbol}
548 @kindex -u @var{symbol}
549 @cindex undefined symbol
550 Force @var{symbol} to be entered in the output file as an undefined symbol.
551 Doing this may, for example, trigger linking of additional modules from
552 standard libraries. @samp{-u} may be repeated with different option
553 arguments to enter additional undefined symbols.
554 @c Nice idea, but no such command: This option is equivalent
555 @c to the @code{EXTERN} linker command.
560 For anything other than C++ programs, this option is equivalent to
561 @samp{-r}: it generates relocatable output---i.e., an output file that can in
562 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
563 @emph{will} resolve references to constructors, unlike @samp{-r}.
564 It does not work to use @samp{-Ur} on files that were themselves linked
565 with @samp{-Ur}; once the constructor table has been built, it can not
566 be added to. Use @samp{-Ur} only for the last partial link, and
567 @samp{-r} for the others.
572 Display the version number for @code{ld} and list the supported emulations.
573 Display which input files can and can not be opened.
578 Display the version number for @code{ld}.
582 Display the version number for @code{ld} and exit.
585 Warn when a common symbol is combined with another common symbol or with
586 a symbol definition. Unix linkers allow this somewhat sloppy practice,
587 but linkers on some other operating systems do not. This option allows
588 you to find potential problems from combining global symbols.
589 Unfortunately, some C libraries use this practice, so you may get some
590 warnings about symbols in the libraries as well as in your programs.
592 There are three kinds of global symbols, illustrated here by C examples:
596 A definition, which goes in the initialized data section of the output
600 An undefined reference, which does not allocate space.
601 There must be either a definition or a common symbol for the
605 A common symbol. If there are only (one or more) common symbols for a
606 variable, it goes in the uninitialized data area of the output file.
607 The linker merges multiple common symbols for the same variable into a
608 single symbol. If they are of different sizes, it picks the largest
609 size. The linker turns a common symbol into a declaration, if there is
610 a definition of the same variable.
613 The @samp{-warn-common} option can produce five kinds of warnings. Each
614 warning consists of a pair of lines: the first describes the symbol just
615 encountered, and the second describes the previous symbol encountered
616 with the same name. One or both of the two symbols will be a common
621 Turning a common symbol into a reference, because there is already a
622 definition for the symbol.
624 @var{file}(@var{section}): warning: common of `@var{symbol}' overridden by definition
625 @var{file}(@var{section}): warning: defined here
629 Turning a common symbol into a reference, because a later definition for
630 the symbol is encountered. This is the same as the previous case,
631 except that the symbols are encountered in a different order.
633 @var{file}(@var{section}): warning: definition of `@var{symbol}' overriding common
634 @var{file}(@var{section}): warning: common is here
638 Merging a common symbol with a previous same-sized common symbol.
640 @var{file}(@var{section}): warning: multiple common of `@var{symbol}'
641 @var{file}(@var{section}): warning: previous common is here
645 Merging a common symbol with a previous larger common symbol.
647 @var{file}(@var{section}): warning: common of `@var{symbol}' overridden by larger common
648 @var{file}(@var{section}): warning: larger common is here
652 Merging a common symbol with a previous smaller common symbol. This is
653 the same as the previous case, except that the symbols are
654 encountered in a different order.
656 @var{file}(@var{section}): warning: common of `@var{symbol}' overriding smaller common
657 @var{file}(@var{section}): warning: smaller common is here
663 @cindex local symbols, deleting
664 @cindex L, deleting symbols beginning
665 If @samp{-s} or @samp{-S} is also specified, delete only local symbols
666 beginning with @samp{L}.
670 @cindex deleting local symbols
671 If @samp{-s} or @samp{-S} is also specified, delete all local symbols,
672 not just those beginning with @samp{L}.
675 @kindex -y@var{symbol}
676 @cindex symbol tracing
677 Print the name of each linked file in which @var{symbol} appears. This
678 option may be given any number of times. On many systems it is necessary
679 to prepend an underscore.
681 This option is useful when you have an undefined symbol in your link but
682 don't know where the reference is coming from.
687 @section Environment Variables
689 You can change the behavior of @code{ld} with the environment
690 variable @code{GNUTARGET}.
693 @cindex default input format
694 @code{GNUTARGET} determines the input-file object format if you don't
695 use @samp{-b} (or its synonym @samp{-format}). Its value should be one
696 of the BFD names for an input format (@pxref{BFD}). If there is no
697 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
698 of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
699 input format by examining binary input files; this method often
700 succeeds, but there are potential ambiguities, since there is no method
701 of ensuring that the magic number used to specify object-file formats is
702 unique. However, the configuration procedure for BFD on each system
703 places the conventional format for that system first in the search-list,
704 so ambiguities are resolved in favor of convention.
708 @chapter Command Language
710 @cindex command files
711 The command language provides explicit control over the link process,
712 allowing complete specification of the mapping between the linker's
713 input files and its output. It controls:
722 addresses of sections
724 placement of common blocks
727 You may supply a command file (also known as a link script) to the
728 linker either explicitly through the @samp{-T} option, or implicitly as
729 an ordinary file. If the linker opens a file which it cannot recognize
730 as a supported object or archive format, it tries to interpret the file
734 * Scripts:: Linker Scripts
735 * Expressions:: Expressions
736 * MEMORY:: MEMORY Command
737 * SECTIONS:: SECTIONS Command
738 * Entry Point:: The Entry Point
739 * Other Commands:: Other Commands
743 @section Linker Scripts
744 The @code{ld} command language is a collection of statements; some are
745 simple keywords setting a particular option, some are used to select and
746 group input files or name output files; and two statement
747 types have a fundamental and pervasive impact on the linking process.
749 @cindex fundamental script commands
750 @cindex commands, fundamental
751 @cindex output file layout
752 @cindex layout of output file
753 The most fundamental command of the @code{ld} command language is the
754 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
755 script must have a @code{SECTIONS} command: it specifies a
756 ``picture'' of the output file's layout, in varying degrees of detail.
757 No other command is required in all cases.
759 The @code{MEMORY} command complements @code{SECTIONS} by describing the
760 available memory in the target architecture. This command is optional;
761 if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
762 memory is available in a contiguous block for all output.
766 You may include comments in linker scripts just as in C: delimited
767 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
768 equivalent to whitespace.
772 @cindex expression syntax
774 Many useful commands involve arithmetic expressions. The syntax for
775 expressions in the command language is identical to that of C
776 expressions, with the following features:
779 All expressions evaluated as integers and
780 are of ``long'' or ``unsigned long'' type.
782 All constants are integers.
784 All of the C arithmetic operators are provided.
786 You may reference, define, and create global variables.
788 You may call special purpose built-in functions.
792 * Integers:: Integers
793 * Symbols:: Symbol Names
794 * Location Counter:: The Location Counter
795 * Operators:: Operators
796 * Evaluation:: Evaluation
797 * Assignment:: Assignment: Defining Symbols
798 * Built-ins:: Built-In Functions
803 @cindex integer notation
804 @cindex octal integers
805 An octal integer is @samp{0} followed by zero or more of the octal
806 digits (@samp{01234567}).
811 @cindex decimal integers
812 A decimal integer starts with a non-zero digit followed by zero or
813 more digits (@samp{0123456789}).
818 @cindex hexadecimal integers
820 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
821 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
826 @cindex negative integers
827 To write a negative integer, use
828 the prefix operator @samp{-}; @pxref{Operators}.
833 @cindex scaled integers
834 @cindex K and M integer suffixes
835 @cindex M and K integer suffixes
836 @cindex suffixes for integers
837 @cindex integer suffixes
838 Additionally the suffixes @code{K} and @code{M} may be used to scale a
842 @c END TEXI2ROFF-KILL
843 @code{1024} or @code{1024*1024}
847 ${\rm 1024}$ or ${\rm 1024}^2$
849 @c END TEXI2ROFF-KILL
850 respectively. For example, the following all refer to the same quantity:
859 @subsection Symbol Names
862 @cindex quoted symbol names
864 Unless quoted, symbol names start with a letter, underscore, point or
865 hyphen and may include any letters, underscores, digits, points,
866 and minus signs. Unquoted symbol names must not conflict with any
867 keywords. You can specify a symbol which contains odd characters or has
868 the same name as a keyword, by surrounding the symbol name in double quotes:
871 "with a space" = "also with a space" + 10;
874 @node Location Counter
875 @subsection The Location Counter
878 @cindex location counter
879 @cindex current output location
880 The special linker variable @dfn{dot} @samp{.} always contains the
881 current output location counter. Since the @code{.} always refers to
882 a location in an output section, it must always appear in an
883 expression within a @code{SECTIONS} command. The @code{.} symbol
884 may appear anywhere that an ordinary symbol is allowed in an
885 expression, but its assignments have a side effect. Assigning a value
886 to the @code{.} symbol will cause the location counter to be moved.
888 This may be used to create holes in the output section. The location
889 counter may never be moved backwards.
904 In the previous example, @code{file1} is located at the beginning of the
905 output section, then there is a 1000 byte gap. Then @code{file2}
906 appears, also with a 1000 byte gap following before @code{file3} is
907 loaded. The notation @samp{= 0x1234} specifies what data to write in
908 the gaps (@pxref{Section Options}).
911 @subsection Operators
912 @cindex Operators for arithmetic
913 @cindex arithmetic operators
914 @cindex precedence in expressions
915 The linker recognizes the standard C set of arithmetic operators, with
916 the standard bindings and precedence levels:
919 @c END TEXI2ROFF-KILL
921 precedence associativity Operators Notes
927 5 left == != > < <= >=
933 11 right &= += -= *= /= (2)
938 (2) @xref{Assignment}
943 %"lispnarrowing" is the extra indent used generally for @example
944 \hskip\lispnarrowing\vbox{\offinterlineskip
947 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
948 height2pt&\omit&&\omit&&\omit&\cr
949 &Precedence&& Associativity &&{\rm Operators}&\cr
950 height2pt&\omit&&\omit&&\omit&\cr
952 height2pt&\omit&&\omit&&\omit&\cr
954 % '176 is tilde, '~' in tt font
955 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
959 &5&&left&&== != > < <= >=&\cr
965 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
967 height2pt&\omit&&\omit&&\omit&\cr}
972 @obeylines@parskip=0pt@parindent=0pt
973 @dag@quad Prefix operators.
974 @ddag@quad @xref{Assignment}.
977 @c END TEXI2ROFF-KILL
980 @subsection Evaluation
982 @cindex lazy evaluation
983 @cindex expression evaluation order
984 The linker uses ``lazy evaluation'' for expressions; it only calculates
985 an expression when absolutely necessary. The linker needs the value of
986 the start address, and the lengths of memory regions, in order to do any
987 linking at all; these values are computed as soon as possible when the
988 linker reads in the command file. However, other values (such as symbol
989 values) are not known or needed until after storage allocation. Such
990 values are evaluated later, when other information (such as the sizes of
991 output sections) is available for use in the symbol assignment
995 @subsection Assignment: Defining Symbols
996 @cindex assignment in scripts
997 @cindex symbol definition, scripts
998 @cindex variables, defining
999 You may create global symbols, and assign values (addresses) to global
1000 symbols, using any of the C assignment operators:
1003 @item @var{symbol} = @var{expression} ;
1004 @itemx @var{symbol} &= @var{expression} ;
1005 @itemx @var{symbol} += @var{expression} ;
1006 @itemx @var{symbol} -= @var{expression} ;
1007 @itemx @var{symbol} *= @var{expression} ;
1008 @itemx @var{symbol} /= @var{expression} ;
1011 Two things distinguish assignment from other operators in @code{ld}
1015 Assignment may only be used at the root of an expression;
1016 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
1021 You must place a trailing semicolon (``@key{;}'') at the end of an
1022 assignment statement.
1025 Assignment statements may appear:
1028 as commands in their own right in an @code{ld} script; or
1030 as independent statements within a @code{SECTIONS} command; or
1032 as part of the contents of a section definition in a
1033 @code{SECTIONS} command.
1036 The first two cases are equivalent in effect---both define a symbol with
1037 an absolute address. The last case defines a symbol whose address is
1038 relative to a particular section (@pxref{SECTIONS}).
1040 @cindex absolute and relocatable symbols
1041 @cindex relocatable and absolute symbols
1042 @cindex symbols, relocatable and absolute
1043 When a linker expression is evaluated and assigned to a variable, it is
1044 given either an absolute or a relocatable type. An absolute expression
1045 type is one in which the symbol contains the value that it will have in
1046 the output file, a relocatable expression type is one in which the
1047 value is expressed as a fixed offset from the base of a section.
1049 The type of the expression is controlled by its position in the script
1050 file. A symbol assigned within a section definition is created relative
1051 to the base of the section; a symbol assigned in any other place is
1052 created as an absolute symbol. Since a symbol created within a
1053 section definition is relative to the base of the section, it
1054 will remain relocatable if relocatable output is requested. A symbol
1055 may be created with an absolute value even when assigned to within a
1056 section definition by using the absolute assignment function
1057 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
1058 is the last byte of an output section named @code{.data}:
1064 _edata = ABSOLUTE(.) ;
1069 The linker tries to put off the evaluation of an assignment until all
1070 the terms in the source expression are known (@pxref{Evaluation}). For
1071 instance, the sizes of sections cannot be known until after allocation,
1072 so assignments dependent upon these are not performed until after
1073 allocation. Some expressions, such as those depending upon the location
1074 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
1075 result of an expression is required, but the value is not available,
1076 then an error results. For example, a script like the following
1079 text 9+this_isnt_constant :
1084 @kindex Non constant expression
1086 will cause the error message ``@code{Non constant expression for initial
1090 @subsection Built-In Functions
1091 @cindex functions in expression language
1092 The command language includes a number of built-in
1093 functions for use in link script expressions.
1095 @item ABSOLUTE(@var{exp})
1096 @kindex ABSOLUTE(@var{exp})
1097 @cindex expression, absolute
1098 Return the absolute (non-relocatable, as opposed to non-negative) value
1099 of the expression @var{exp}. Primarily useful to assign an absolute
1100 value to a symbol within a section definition, where symbol values are
1101 normally section-relative.
1103 @item ADDR(@var{section})
1104 @kindex ADDR(@var{section})
1105 @cindex section address
1106 Return the absolute address of the named @var{section}. Your script must
1107 previously have defined the location of that section. In the following
1108 example, @code{symbol_1} and @code{symbol_2} are assigned identical
1114 start_of_output_1 = ABSOLUTE(.);
1119 symbol_1 = ADDR(.output1);
1120 symbol_2 = start_of_output_1;
1125 @item ALIGN(@var{exp})
1126 @kindex ALIGN(@var{exp})
1127 @cindex rounding up location counter
1128 Return the result of the current location counter (@code{.}) aligned to
1129 the next @var{exp} boundary. @var{exp} must be an expression whose
1130 value is a power of two. This is equivalent to
1132 (. + @var{exp} - 1) & ~(@var{exp} - 1)
1135 @code{ALIGN} doesn't change the value of the location counter---it just
1136 does arithmetic on it. As an example, to align the output @code{.data}
1137 section to the next @code{0x2000} byte boundary after the preceding
1138 section and to set a variable within the section to the next
1139 @code{0x8000} boundary after the input sections:
1142 .data ALIGN(0x2000): @{
1144 variable = ALIGN(0x8000);
1149 The first use of @code{ALIGN} in this example specifies the location of
1150 a section because it is used as the optional @var{start} attribute of a
1151 section definition (@pxref{Section Options}). The second use simply
1152 defines the value of a variable.
1154 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1156 @item DEFINED(@var{symbol})
1157 @kindex DEFINED(@var{symbol})
1158 @cindex symbol defaults
1159 Return 1 if @var{symbol} is in the linker global symbol table and is
1160 defined, otherwise return 0. You can use this function to provide default
1161 values for symbols. For example, the following command-file fragment shows how
1162 to set a global symbol @code{begin} to the first location in the
1163 @code{.text} section---but if a symbol called @code{begin} already
1164 existed, its value is preserved:
1168 begin = DEFINED(begin) ? begin : . ;
1174 @item NEXT(@var{exp})
1175 @kindex NEXT(@var{exp})
1176 @cindex unallocated address, next
1177 Return the next unallocated address that is a multiple of @var{exp}.
1178 This function is closely related to @code{ALIGN(@var{exp})}; unless you
1179 use the @code{MEMORY} command to define discontinuous memory for the
1180 output file, the two functions are equivalent.
1182 @item SIZEOF(@var{section})
1183 @kindex SIZEOF(@var{section})
1184 @cindex section size
1185 Return the size in bytes of the named @var{section}, if that section has
1186 been allocated. In the following example, @code{symbol_1} and
1187 @code{symbol_2} are assigned identical values:
1188 @c What does it return if the section hasn't been allocated? 0?
1196 symbol_1 = .end - .start ;
1197 symbol_2 = SIZEOF(.output);
1202 @item SIZEOF_HEADERS
1203 @kindex SIZEOF_HEADERS
1205 @itemx sizeof_headers
1206 @kindex sizeof_headers
1207 Return the size in bytes of the output file's headers. You can use this number
1208 as the start address of the first section, if you choose, to facilitate
1214 @section MEMORY Command
1216 @cindex regions of memory
1217 @cindex discontinuous memory
1218 @cindex allocating memory
1219 The linker's default configuration permits allocation of all available memory.
1220 You can override this configuration by using the @code{MEMORY} command. The
1221 @code{MEMORY} command describes the location and size of blocks of
1222 memory in the target. By using it carefully, you can describe which
1223 memory regions may be used by the linker, and which memory regions it
1224 must avoid. The linker does not shuffle sections to fit into the
1225 available regions, but does move the requested sections into the correct
1226 regions and issue errors when the regions become too full.
1228 The command files may contain at most one use of the @code{MEMORY}
1229 command; however, you can define as many blocks of memory within it as
1230 you wish. The syntax is:
1235 @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
1241 @cindex naming memory regions
1242 is a name used internally by the linker to refer to the region. Any
1243 symbol name may be used. The region names are stored in a separate
1244 name space, and will not conflict with symbols, file names or section
1245 names. Use distinct names to specify multiple regions.
1247 @cindex memory region attributes
1248 is an optional list of attributes, permitted for compatibility with the
1249 AT&T linker but not used by @code{ld} beyond checking that the
1250 attribute list is valid. Valid attribute lists must be made up of the
1251 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1252 omit the parentheses around it as well.
1257 is the start address of the region in physical memory. It is
1258 an expression that must evaluate to a constant before
1259 memory allocation is performed. The keyword @code{ORIGIN} may be
1260 abbreviated to @code{org} or @code{o}.
1265 is the size in bytes of the region (an expression).
1266 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1269 For example, to specify that memory has two regions available for
1270 allocation---one starting at 0 for 256 kilobytes, and the other
1271 starting at @code{0x40000000} for four megabytes:
1276 rom : ORIGIN = 0, LENGTH = 256K
1277 ram : org = 0x40000000, l = 4M
1281 Once you have defined a region of memory named @var{mem}, you can direct
1282 specific output sections there by using a command ending in
1283 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1284 Options}). If the combined output sections directed to a region are too
1285 big for the region, the linker will issue an error message.
1288 @section SECTIONS Command
1290 The @code{SECTIONS} command controls exactly where input sections are
1291 placed into output sections, their order and to which output sections
1294 You may use at most one @code{SECTIONS} command in a commands file,
1295 but you can have as many statements within it as you wish. Statements
1296 within the @code{SECTIONS} command can do one of three things:
1299 define the entry point;
1301 assign a value to a symbol;
1303 describe the placement of a named output section, and what input
1304 sections make it up.
1307 The first two possibilities---defining the entry point, and defining
1308 symbols---can also be done outside the @code{SECTIONS} command:
1309 @pxref{Entry Point}, @pxref{Assignment}. They are permitted here as
1310 well for your convenience in reading the script, so that symbols or the
1311 entry point can be defined at meaningful points in your output-file
1314 When no @code{SECTIONS} command is specified, the default action
1315 of the linker is to place each input section into an identically named
1316 output section in the order that the sections are first encountered in
1317 the input files; if all input sections are present in the first file,
1318 for example, the order of sections in the output file will match the
1319 order in the first input file.
1322 * Section Definition:: Section Definitions
1323 * Section Contents:: Section Contents
1324 * Section Options:: Optional Section Attributes
1327 @node Section Definition
1328 @subsection Section Definitions
1329 @cindex section definition
1330 The most frequently used statement in the @code{SECTIONS} command is
1331 the @dfn{section definition}, which you can use to specify the
1332 properties of an output section: its location, alignment, contents,
1333 fill pattern, and target memory region. Most of
1334 these specifications are optional; the simplest form of a section
1343 @cindex naming output sections
1345 @var{secname} is the name of the output section, and @var{contents} a
1346 specification of what goes there---for example, a list of input files or
1347 sections of input files. As you might assume, the whitespace shown is
1348 optional. You do need the colon @samp{:} and the braces @samp{@{@}},
1351 @var{secname} must meet the constraints of your output format. In
1352 formats which only support a limited number of sections, such as
1353 @code{a.out}, the name must be one of the names supported by the format
1354 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1355 @code{.bss}). If the output format supports any number of sections, but
1356 with numbers and not names (as is the case for Oasys), the name should be
1357 supplied as a quoted numeric string. A section name may consist of any
1358 sequence characters, but any name which does not conform to the standard
1359 @code{ld} symbol name syntax must be quoted.
1360 @xref{Symbols, , Symbol Names}.
1362 @node Section Contents
1363 @subsection Section Contents
1364 @cindex contents of a section
1365 In a section definition, you can specify the contents of an output section by
1366 listing particular object files, by listing particular input-file
1367 sections, or by a combination of the two. You can also place arbitrary
1368 data in the section, and define symbols relative to the beginning of the
1371 The @var{contents} of a section definition may include any of the
1372 following kinds of statement. You can include as many of these as you
1373 like in a single section definition, separated from one another by
1377 @item @var{filename}
1378 @kindex @var{filename}
1379 @cindex input files, section defn
1380 @cindex files, including in output sections
1381 You may simply name a particular input file to be placed in the current
1382 output section; @emph{all} sections from that file are placed in the
1383 current section definition. To specify a list of particular files by
1386 .data : @{ afile.o bfile.o cfile.o @}
1389 The example also illustrates that multiple statements can be included in
1390 the contents of a section definition, since each file name is a separate
1393 If the file name has already been mentioned in another section
1394 definition, with an explicit section name list, then only those sections
1395 which have not yet been allocated are used.
1397 @item @var{filename}( @var{section} )
1398 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1399 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1400 @kindex @var{filename}(@var{section})
1401 @cindex files and sections, section defn
1402 You can name one or more sections from your input files, for
1403 insertion in the current output section. If you wish to specify a list
1404 of input-file sections inside the parentheses, you may separate the
1405 section names by either commas or whitespace.
1407 @item * (@var{section})
1408 @itemx * (@var{section}, @var{section}, @dots{})
1409 @itemx * (@var{section} @var{section} @dots{}
1410 @cindex input sections to output section
1411 @kindex *(@var{section})
1412 Instead of explicitly naming particular input files in a link control
1413 script, you can refer to @emph{all} files from the @code{ld} command
1414 line: use @samp{*} instead of a particular file name before the
1415 parenthesized input-file section list.
1417 For example, to copy sections @code{1} through @code{4} from an Oasys file
1418 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1419 and @code{14} into the @code{.data} section:
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 @item [ @var{section} ]
1437 @itemx [ @var{section}, @var{section}, @dots{} ]
1438 @itemx [ @var{section} @var{section} @dots{} ]
1439 @kindex [ @var{sections} ]
1440 This is an alternate notation to specify named sections from all
1441 unallocated input files; its effect is exactly the same as that of
1442 @samp{* (@var{section}@dots{})}
1444 @item @var{filename}@code{( COMMON )}
1447 @cindex uninitialized data
1448 @cindex commons in output
1449 Specify where in your output file to place uninitialized data
1450 with this notation. @code{*(COMMON)} by itself refers to all
1451 uninitialized data from all input files (so far as it is not yet
1452 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1453 from a particular file. Both are special cases of the general
1454 mechanisms for specifying where to place input-file sections:
1455 @code{ld} permits you to refer to uninitialized data as if it
1456 were in an input-file section named @code{COMMON}, regardless of the
1457 input file's format.
1460 For example, the following command script arranges the output file into
1461 three consecutive sections, named @code{.text}, @code{.data}, and
1462 @code{.bss}, taking the input for each from the correspondingly named
1463 sections of all the input files:
1466 .text : @{ *(.text) @}
1467 .data : @{ *(.data) @}
1468 .bss : @{ *(.bss) *(COMMON) @}
1472 The following example reads all of the sections from file @code{all.o}
1473 and places them at the start of output section @code{outputa} which
1474 starts at location @code{0x10000}. All of section @code{.input1} from
1475 file @code{foo.o} follows immediately, in the same output section. All
1476 of section @code{.input2} from @code{foo.o} goes into output section
1477 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1478 All of the remaining @code{.input1} and @code{.input2} sections from any
1479 files are written to output section @code{outputc}.
1501 There are still more kinds of statements permitted in the contents of
1502 output section definitions. The foregoing statements permitted you to
1503 arrange, in your output file, data originating from your input files.
1504 You can also place data directly in an output section from the link
1505 command script. Most of these additional statements involve
1506 expressions; @pxref{Expressions}. Although these statements are shown
1507 separately here for ease of presentation, no such segregation is needed
1508 within a section definition in the @code{SECTIONS} command; you can
1509 intermix them freely with any of the statements we've just described.
1512 @item CREATE_OBJECT_SYMBOLS
1513 @kindex CREATE_OBJECT_SYMBOLS
1514 @cindex input filename symbols
1515 @cindex filename symbols
1516 Create a symbol for each input file
1517 in the current section, set to the address of the first byte of
1518 data written from the input file. For instance, with @code{a.out}
1519 files it is conventional to have a symbol for each input file. You can
1520 accomplish this by defining the output @code{.text} section as follows:
1525 CREATE_OBJECT_SYMBOLS
1527 _etext = ALIGN(0x2000);
1533 If @code{objsym} is a file containing this script, and @code{a.o},
1534 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1535 contents like the following---
1545 @samp{ld -M sample a.o b.o c.o d.o} would create a map like this,
1546 containing symbols matching the object file names:
1548 00000000 A __DYNAMIC
1551 00002020 T _afunction
1554 00002038 T _bfunction
1557 00002050 T _cfunction
1560 00002068 T _dfunction
1570 @item @var{symbol} = @var{expression} ;
1571 @kindex @var{symbol} = @var{expression} ;
1572 @itemx @var{symbol} @var{f}= @var{expression} ;
1573 @kindex @var{symbol} @var{f}= @var{expression} ;
1574 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1575 refers to any of the operators @code{&= += -= *= /=} which combine
1576 arithmetic and assignment.
1578 @cindex assignment, in section defn
1579 When you assign a value to a symbol within a particular section
1580 definition, the value is relative to the beginning of the section
1581 (@pxref{Assignment}). If you write
1586 .data : @{ @dots{} rel = 14 ; @dots{} @}
1587 abs2 = 14 + ADDR(.data);
1591 @c FIXME: Try above example!
1593 @code{abs} and @code{rel} do not have the same value; @code{rel} has the
1594 same value as @code{abs2}.
1596 @item BYTE(@var{expression})
1597 @kindex BYTE(@var{expression})
1598 @itemx SHORT(@var{expression})
1599 @kindex SHORT(@var{expression})
1600 @itemx LONG(@var{expression})
1601 @kindex LONG(@var{expression})
1602 @cindex direct output
1603 By including one of these three statements in a section definition, you
1604 can explicitly place one, two, or four bytes (respectively) at the
1605 current address of that section.
1607 @ifclear SingleFormat
1608 Multiple-byte quantities are represented in whatever byte order is
1609 appropriate for the output file format (@pxref{BFD}).
1612 @item FILL(@var{expression})
1613 @kindex FILL(@var{expression})
1614 @cindex holes, filling
1615 @cindex unspecified memory
1616 Specifies the ``fill pattern'' for the current section. Any otherwise
1617 unspecified regions of memory within the section (for example, regions
1618 you skip over by assigning a new value to the location counter @samp{.})
1619 are filled with the two least significant bytes from the
1620 @var{expression} argument. A @code{FILL} statement covers memory
1621 locations @emph{after} the point it occurs in the section definition; by
1622 including more than one @code{FILL} statement, you can have different
1623 fill patterns in different parts of an output section.
1626 @node Section Options
1627 @subsection Optional Section Attributes
1628 @cindex section defn, full syntax
1629 Here is the full syntax of a section definition, including all the
1635 @var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : @{ @var{contents} @} =@var{fill} >@var{region}
1640 @var{secname} and @var{contents} are required. @xref{Section
1641 Definition}, and @pxref{Section Contents} for details on @var{contents}.
1642 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1643 @code{(NOLOAD)} @code{=@var{fill}}, and @code{>@var{region}}---are all
1648 @cindex start address, section
1649 @cindex section start
1650 @cindex section address
1651 You can force the output section to be loaded at a specified address by
1652 specifying @var{start} immediately following the section name.
1653 @var{start} can be represented as any expression. The following
1654 example generates section @var{output} at location
1659 output 0x40000000: @{
1666 @item BLOCK(@var{align})
1667 @kindex BLOCK(@var{align})
1668 @cindex section alignment
1669 @cindex aligning sections
1670 You can include @code{BLOCK()} specification to advance
1671 the location counter @code{.} prior to the beginning of the section, so
1672 that the section will begin at the specified alignment. @var{align} is
1677 @cindex prevent unnecessary loading
1678 Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
1679 each time it is accessed. For example, in the script sample below, the
1680 @code{ROM} segment is addressed at memory location @samp{0} and does not
1681 need to be loaded into each object file:
1684 ROM 0 (NOLOAD) : @{ @dots{} @}
1691 @cindex section fill pattern
1692 @cindex fill pattern, entire section
1694 @code{=@var{fill}} in a section definition specifies the initial fill
1695 value for that section.
1696 You may use any expression to specify @var{fill}.
1697 Any unallocated holes in the current output
1698 section when written to the output file will be filled with the two
1699 least significant bytes of the value, repeated as necessary. You can
1700 also change the fill value with a @code{FILL} statement in the
1701 @var{contents} of a section definition.
1704 @kindex >@var{region}
1705 @cindex section, assigning to memory region
1706 @cindex memory regions and sections
1707 Assign this section to a previously defined region of memory.
1713 @section The Entry Point
1714 @kindex ENTRY(@var{symbol})
1715 @cindex start of execution
1716 @cindex first instruction
1717 The linker command language includes a command specifically for
1718 defining the first executable instruction in an output file (its
1719 @dfn{entry point}). Its argument is a symbol name:
1724 Like symbol assignments, the @code{ENTRY} command may be placed either
1725 as an independent command in the command file, or among the section
1726 definitions within the @code{SECTIONS} command---whatever makes the most
1727 sense for your layout.
1729 @cindex entry point, defaults
1730 @code{ENTRY} is only one of several ways of choosing the entry point.
1731 You may indicate it in any of the following ways (shown in descending
1732 order of priority: methods higher in the list override methods lower down).
1735 the @samp{-e} @var{entry} command-line option;
1737 the @code{ENTRY(@var{symbol}} command in a linker control script;
1739 the value of the symbol @code{start}, if present;
1741 the value of the symbol @code{_main}, if present;
1743 the address of the first byte of the @code{.text} section, if present;
1745 The address @code{0}.
1748 For example, you can use these rules to generate an entry point with an
1749 assignment statement: if no symbol @code{start} is defined within your
1750 input files, you can simply define it, assigning it an appropriate
1757 The example shows an absolute address, but you can use any expression.
1758 For example, if your input object files use some other symbol-name
1759 convention for the entry point, you can just assign the value of
1760 whatever symbol contains the start address to @code{start}:
1762 start = other_symbol ;
1765 @node Other Commands
1766 @section Other Commands
1767 The command language includes a number of other commands that you can
1768 use for specialized purposes. They are similar in purpose to
1769 command-line options.
1776 These keywords were used in some older linkers to request a particular
1777 math subroutine library. @code{ld} doesn't use the keywords, assuming
1778 instead that any necessary subroutines are in libraries specified using
1779 the general mechanisms for linking to archives; but to permit the use of
1780 scripts that were written for the older linkers, the keywords
1781 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1783 @item FORCE_COMMON_ALLOCATION
1784 @kindex FORCE_COMMON_ALLOCATION
1785 @cindex common allocation
1786 This command has the same effect as the @samp{-d} command-line option:
1787 to make @code{ld} assign space to common symbols even if a relocatable
1788 output file is specified (@samp{-r}).
1790 @item INPUT ( @var{file}, @var{file}, @dots{} )
1791 @kindex INPUT ( @var{files} )
1792 @itemx INPUT ( @var{file} @var{file} @dots{} )
1793 @cindex binary input files
1794 Use this command to include binary input files in the link, without
1795 including them in a particular section definition. Files specified this
1796 way are treated identically to object files listed on the command line.
1799 @item MAP ( @var{name} )
1800 @kindex MAP ( @var{name} )
1801 @c MAP(...) appears to look for an F in the arg, ignoring all other
1802 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1803 @c checks map_option_f. Apparently a stub for the future...
1806 @item OUTPUT ( @var{filename} )
1807 @kindex OUTPUT ( @var{filename} )
1808 @cindex naming the output file
1809 Use this command to name the link output file @var{filename}. The
1810 effect of @code{OUTPUT(@var{filename})} is identical to the effect of
1811 @w{@samp{-o @var{filename}}}, and whichever is encountered last will
1812 control the name actually used to name the output file. In particular,
1813 you can use this command to supply a default output-file name other than
1816 @ifclear SingleFormat
1817 @item OUTPUT_ARCH ( @var{bfdname} )
1818 @kindex OUTPUT_ARCH ( @var{bfdname} )
1819 @cindex machine architecture, output
1820 Specify a particular output machine architecture, with one of the names
1821 used by the BFD back-end routines (@pxref{BFD}). This command is often
1822 unnecessary; the architecture is most often set implicitly by either the
1823 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1826 @item OUTPUT_FORMAT ( @var{bfdname} )
1827 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1828 @cindex format, output file
1829 Specify a particular output format, with one of the names used by the
1830 BFD back-end routines (@pxref{BFD}). This selection will only affect
1831 the output file; the related command @code{TARGET} affects primarily
1835 @item SEARCH_DIR ( @var{path} )
1836 @kindex SEARCH_DIR ( @var{path} )
1837 @cindex path for libraries
1838 @cindex search path, libraries
1839 Add @var{path} to the list of paths where @code{ld} looks for
1840 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1841 effect as @samp{-L@var{path}} on the command line.
1843 @item STARTUP ( @var{filename} )
1844 @kindex STARTUP ( @var{filename} )
1845 @cindex first input file
1846 Ensure that @var{filename} is the first input file used in the link
1849 @ifclear SingleFormat
1850 @item TARGET ( @var{format} )
1851 @cindex input file format
1852 @kindex TARGET ( @var{format} )
1853 Change the input-file object code format (like the command-line option
1854 @samp{-b} or its synonym @samp{-format}). The argument @var{format} is
1855 one of the strings used by BFD to name binary formats. In the current
1856 @code{ld} implementation, if @code{TARGET} is specified but
1857 @code{OUTPUT_FORMAT} is not, the last @code{TARGET} argument is also
1858 used as the default format for the @code{ld} output file.
1862 If you don't use the @code{TARGET} command, @code{ld} uses the value of
1863 the environment variable @code{GNUTARGET}, if available, to select the
1864 output file format. If that variable is also absent, @code{ld} uses
1865 the default format configured for your machine in the BFD libraries.
1870 @node Machine Dependent
1871 @chapter Machine Dependent Features
1873 @cindex machine dependencies
1874 @code{ld} has additional features on some platforms; the following
1875 sections describe them. Machines where @code{ld} has no additional
1876 functionality are not listed.
1879 * H8/300:: @code{ld} and the H8/300
1880 * i960:: @code{ld} and the Intel 960 family
1884 @c FIXME! This could use @up/@down, but there seems to be a conflict
1885 @c between those and node-defaulting.
1891 @section @code{ld} and the H8/300
1893 @cindex H8/300 support
1894 For the H8/300, @code{ld} can perform these global optimizations when
1895 you specify the @samp{-relax} command-line option.
1898 @item relaxing address modes
1899 @cindex relaxing on H8/300
1900 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
1901 targets are within eight bits, and turns them into eight-bit
1902 program-counter relative @code{bsr} and @code{bra} instructions,
1905 @item synthesizing instructions
1906 @cindex synthesizing on H8/300
1907 @c FIXME: specifically mov.b, or any mov instructions really?
1908 @code{ld} finds all @code{mov.b} instructions which use the
1909 sixteen-bit absolute address form, but refer to the top
1910 page of memory, and changes them to use the eight-bit address form.
1911 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1912 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1913 top page of memory).
1925 @section @code{ld} and the Intel 960 family
1927 @cindex i960 support
1929 You can use the @samp{-A@var{architecture}} command line option to
1930 specify one of the two-letter names identifying members of the 960
1931 family; the option specifies the desired output target, and warns of any
1932 incompatible instructions in the input files. It also modifies the
1933 linker's search strategy for archive libraries, to support the use of
1934 libraries specific to each particular architecture, by including in the
1935 search loop names suffixed with the string identifying the architecture.
1937 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
1938 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1939 paths, and in any paths you specify with @samp{-L}) for a library with
1950 The first two possibilities would be considered in any event; the last
1951 two are due to the use of @w{@samp{-ACA}}.
1953 You can meaningfully use @samp{-A} more than once on a command line, since
1954 the 960 architecture family allows combination of target architectures; each
1955 use will add another pair of name variants to search for when @w{@samp{-l}}
1956 specifies a library.
1962 @ifclear SingleFormat
1967 @cindex object file management
1968 The linker accesses object and archive files using the BFD libraries.
1969 These libraries allow the linker to use the same routines to operate on
1970 object files whatever the object file format. A different object file
1971 format can be supported simply by creating a new BFD back end and adding
1972 it to the library. You can use @code{objdump -i}
1973 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
1974 list all the formats available for each architecture under BFD. This
1975 was the list of formats, and of architectures supported for each format,
1976 as of the time this manual was prepared:
1977 @cindex formats available
1978 @cindex architectures available
1980 BFD header file version 0.18
1982 (header big endian, data big endian)
1988 (header big endian, data big endian)
1994 (header big endian, data little endian)
1997 (header little endian, data little endian)
2000 (header big endian, data big endian)
2003 (header big endian, data big endian)
2006 (header little endian, data little 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 big endian, data big endian)
2024 (header little endian, data little endian)
2027 (header big endian, data big endian)
2039 (header little endian, data little endian)
2051 (header big endian, data big endian)
2063 (header big endian, data big endian)
2076 @cindex BFD requirements
2077 @cindex requirements for BFD
2078 As with most implementations, BFD is a compromise between
2079 several conflicting requirements. The major factor influencing
2080 BFD design was efficiency: any time used converting between
2081 formats is time which would not have been spent had BFD not
2082 been involved. This is partly offset by abstraction payback; since
2083 BFD simplifies applications and back ends, more time and care
2084 may be spent optimizing algorithms for a greater speed.
2086 One minor artifact of the BFD solution which you should bear in
2087 mind is the potential for information loss. There are two places where
2088 useful information can be lost using the BFD mechanism: during
2089 conversion and during output. @xref{BFD information loss}.
2092 * BFD outline:: How it works: an outline of BFD
2096 @section How it works: an outline of BFD
2097 @cindex opening object files
2098 @include bfdsumm.texi
2102 @appendix MRI Compatible Script Files
2103 @cindex MRI compatibility
2104 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
2105 linker, @code{ld} can use MRI compatible linker scripts as an
2106 alternative to the more general-purpose linker scripting language
2107 described in @ref{Commands,,Command Language}. MRI compatible linker
2108 scripts have a much simpler command set than the scripting language
2109 otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
2110 commonly used MRI linker commands; these commands are described here.
2112 You can specify a file containing an MRI-compatible script using the
2113 @samp{-c} command-line option.
2115 Each command in an MRI-compatible script occupies its own line; each
2116 command line starts with the keyword that identifies the command (though
2117 blank lines are also allowed for punctuation). If a line of an
2118 MRI-compatible script begins with an unrecognized keyword, @code{ld}
2119 issues a warning message, but continues processing the script.
2121 Lines beginning with @samp{*} are comments.
2123 You can write these commands using all upper-case letters, or all
2124 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
2125 The following list shows only the upper-case form of each command.
2128 @item ABSOLUTE @var{secname}
2129 @item ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
2130 @cindex @code{ABSOLUTE} (MRI)
2131 Normally, @code{ld} includes in the output file all sections from all
2132 the input files. However, in an MRI-compatible script, you can use the
2133 @code{ABSOLUTE} command to restrict the sections that will be present in
2134 your output program. If the @code{ABSOLUTE} command is used at all in a
2135 script, then only the sections named explicitly in @code{ABSOLUTE}
2136 commands will appear in the linker output. You can still use other
2137 input sections (whatever you select on the command line, or using
2138 @code{LOAD}) to resolve addresses in the output file.
2140 @item ALIAS @var{out-secname}, @var{in-secname}
2141 @cindex @code{ALIAS} (MRI)
2142 Use this command to place the data from input section @var{in-secname}
2143 in a section called @var{out-secname} in the linker output file.
2145 @var{in-secname} may be an integer.
2147 @item BASE @var{expression}
2148 @cindex @code{BASE} (MRI)
2149 Use the value of @var{expression} as the lowest address (other than
2150 absolute addresses) in the output file.
2152 @item CHIP @var{expression}
2153 @itemx CHIP @var{expression}, @var{expression}
2154 @cindex @code{CHIP} (MRI)
2155 This command does nothing; it is accepted only for compatibility.
2158 @cindex @code{END} (MRI)
2159 This command does nothing whatever; it's only accepted for compatibility.
2161 @item FORMAT @var{output-format}
2162 @cindex @code{FORMAT} (MRI)
2163 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
2164 language, but restricted to one of these output formats:
2167 S-records, if @var{output-format} is @samp{S}
2170 IEEE, if @var{output-format} is @samp{IEEE}
2173 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
2177 @item LIST @var{anything}@dots{}
2178 @cindex @code{LIST} (MRI)
2179 Print (to the standard output file) a link map, as produced by the
2180 @code{ld} command-line option @samp{-M}.
2182 The keyword @code{LIST} may be followed by anything on the
2183 same line, with no change in its effect.
2185 @item LOAD @var{filename}
2186 @item LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
2187 @cindex @code{LOAD} (MRI)
2188 Include one or more object file @var{filename} in the link; this has the
2189 same effect as specifying @var{filename} directly on the @code{ld}
2192 @item NAME @var{output-name}
2193 @cindex @code{NAME} (MRI)
2194 @var{output-name} is the name for the program produced by @code{ld}; the
2195 MRI-compatible command @code{NAME} is equivalent to the command-line
2196 option @samp{-o} or the general script language command @code{OUTPUT}.
2198 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
2199 @itemx ORDER @var{secname} @var{secname} @var{secname}
2200 @cindex @code{ORDER} (MRI)
2201 Normally, @code{ld} orders the sections in its output file in the
2202 order in which they first appear in the input files. In an MRI-compatible
2203 script, you can override this ordering with the @code{ORDER} command. The
2204 sections you list with @code{ORDER} will appear first in your output
2205 file, in the order specified.
2207 @item PUBLIC @var{name}=@var{expression}
2208 @itemx PUBLIC @var{name},@var{expression}
2209 @itemx PUBLIC @var{name} @var{expression}
2210 @cindex @code{PUBLIC} (MRI)
2211 Supply a value (@var{expression}) for external symbol
2212 @var{name} used in the linker input files.
2214 @item SECT @var{secname}, @var{expression}
2215 @itemx SECT @var{secname}=@var{expression}
2216 @itemx SECT @var{secname} @var{expression}
2217 @cindex @code{SECT} (MRI)
2218 You can use any of these three forms of the @code{SECT} command to
2219 specify the start address (@var{expression}) for section @var{secname}.
2220 If you have more than one @code{SECT} statement for the same
2221 @var{secname}, only the @emph{first} sets the start address.
2231 % I think something like @colophon should be in texinfo. In the
2233 \long\def\colophon{\hbox to0pt{}\vfill
2234 \centerline{The body of this manual is set in}
2235 \centerline{\fontname\tenrm,}
2236 \centerline{with headings in {\bf\fontname\tenbf}}
2237 \centerline{and examples in {\tt\fontname\tentt}.}
2238 \centerline{{\it\fontname\tenit\/} and}
2239 \centerline{{\sl\fontname\tensl\/}}
2240 \centerline{are used for emphasis.}\vfill}
2242 % Blame: pesch@cygnus.com, 28mar91.