11 * Ld: (ld). The GNU linker.
17 This file documents the GNU linker GLD.
19 Copyright (C) 1991 Free Software Foundation, Inc.
21 Permission is granted to make and distribute verbatim copies of
22 this manual provided the copyright notice and this permission notice
23 are preserved on all copies.
26 Permission is granted to process this file through Tex and print the
27 results, provided the printed document carries copying permission
28 notice identical to this one except for the removal of this paragraph
29 (this paragraph not being relevant to the printed manual).
32 Permission is granted to copy and distribute modified versions of this
33 manual under the conditions for verbatim copying, provided also that the
34 section entitled ``GNU General Public License'' is included exactly as
35 in the original, and provided that the entire resulting derived work is
36 distributed under the terms of a permission notice identical to this
39 Permission is granted to copy and distribute translations of this manual
40 into another language, under the above conditions for modified versions,
41 except that the section entitled ``GNU General Public License'' may be
42 included in a translation approved by the author instead of in the
47 @setchapternewpage odd
48 @settitle GLD, the GNU linker
51 @subtitle The GNU linker
53 @subtitle Second Edition---@code{gld} version 2.0
55 @author Steve Chamberlain and Roland Pesch
56 @author Cygnus Support
60 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
61 \xdef\manvers{\$Revision$} % For use in headers, footers too
63 \hfill Cygnus Support\par
64 \hfill steve\@cygnus.com, pesch\@cygnus.com\par
65 \hfill {\it GLD, the GNU linker}, \manvers\par
66 \hfill \TeX{}info \texinfoversion\par
68 \global\parindent=0pt % Steve likes it this way.
71 @vskip 0pt plus 1filll
72 Copyright @copyright{} 1991 Free Software Foundation, Inc.
74 Permission is granted to make and distribute verbatim copies of
75 this manual provided the copyright notice and this permission notice
76 are preserved on all copies.
78 Permission is granted to copy and distribute modified versions of this
79 manual under the conditions for verbatim copying, provided also that
80 the entire resulting derived work is distributed under the terms of a
81 permission notice identical to this one.
83 Permission is granted to copy and distribute translations of this manual
84 into another language, under the above conditions for modified versions.
87 @c FIXME: Talk about importance of *order* of args, cmds to linker!
89 @node Top, Overview, (dir), (dir)
91 This file documents the GNU linker gld.
96 * Invocation:: Invocation
97 * Commands:: Command Language
98 * Machine Dependent:: Machine Dependent Features
102 --- The Detailed Node Listing ---
106 * Options:: Command Line Options
107 * Environment:: Environment Variables
111 * Scripts:: Linker Scripts
112 * Expressions:: Expressions
113 * MEMORY:: MEMORY Command
114 * SECTIONS:: SECTIONS Command
115 * Entry Point:: The Entry Point
116 * Other Commands:: Other Commands
120 * Integers:: Integers
121 * Symbols:: Symbol Names
122 * Location Counter:: The Location Counter
123 * Operators:: Operators
124 * Evaluation:: Evaluation
125 * Assignment:: Assignment: Defining Symbols
126 * Built-ins:: Built-In Functions
130 * Section Definition:: Section Definitions
131 * Section Contents:: Section Contents
132 * Section Options:: Optional Section Attributes
134 Machine Dependent Features
136 * H8/300:: @code{gld} and the H8/300
137 * i960:: @code{gld} and the Intel 960 family
138 * m68k:: @code{gld} and the Motorola 68000 family
139 * m88k:: @code{gld} and the Motorola 880x0 family
141 @code{gld} and the Intel 960 family
143 * i960-arch:: Linking for a Specific i960 Architecture
144 * i960-emulation:: Emulating Other i960 Linkers
145 * i960-commands:: Command Language Extensions for i960
149 * BFD outline:: How it works: an outline of BFD
150 * BFD information loss:: Information Loss
151 * Mechanism:: Mechanism
154 @node Overview, Invocation, Top, Top
158 @cindex what is this?
159 @code{gld} combines a number of object and archive files, relocates
160 their data and ties up symbol references. Often the last step in
161 building a new compiled program to run is a call to @code{gld}.
163 @code{gld} accepts Linker Command Language files written in
164 a superset of AT&T's Link Editor Command Language syntax,
165 to provide explicit and total control over the linking process.
167 This version of @code{gld} uses the general purpose BFD libraries
168 to operate on object files. This allows @code{gld} to read, combine, and
169 write object files in many different formats---for example, COFF or
170 @code{a.out}. Different formats may be linked together to produce any
171 available kind of object file. @xref{BFD} for a list of formats
172 supported on various architectures.
174 Aside from its flexibility, the GNU linker is more helpful than other
175 linkers in providing diagnostic information. Many linkers abandon
176 execution immediately upon encountering an error; whenever possible,
177 @code{gld} continues executing, allowing you to identify other errors
178 (or, in some cases, to get an output file in spite of the error).
180 @node Invocation, Commands, Overview, Top
183 The GNU linker @code{gld} is meant to cover a broad range of situations,
184 and to be as compatible as possible with other linkers. As a result,
185 you have many choices to control its behavior through the command line,
186 and through environment variables.
189 * Options:: Command Line Options
190 * Environment:: Environment Variables
193 @node Options, Environment, Invocation, Invocation
194 @section Command Line Options
198 Here is a sketch of the options you can use on the @code{gld} command
202 gld [-o @var{output} ] @var{objfiles}@dots{}
203 [ -A@var{architecture} ] [ -b @var{input-format} ] [ -Bstatic ]
204 [ -c @var{commandfile} ] [ -d | -dc | -dp ]
205 [ -defsym @var{symbol} = @var{expression} ]
206 [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
207 [ -format @var{input-format} ] [ -g ] [ -i ]
208 [ -l@var{ar} ] [ -L@var{searchdir} ] [ -M | -m ]
209 [ -n ] [ -noinhibit-exec ] [ -R @var{filename} ] [ -relax ]
210 [ -r | -Ur ] [ -S ] [ -s ] [ -T @var{commandfile} ]
211 [ -Ttext @var{textorg} ] [ -Tdata @var{dataorg} ] [ -Tbss @var{bssorg} ]
212 [ -t ] [ -u @var{sym}] [-v] [ -X ] [ -x ]
213 [ @{ @var{script} @} ]
216 This plethora of command-line options may seem intimidating, but in
217 actual practice few of them are used in any particular context.
218 @cindex standard Unix system
219 For instance, a frequent use of @code{gld} is to link standard Unix
220 object files on a standard, supported Unix system. On such a system, to
221 link a file @code{hello.o}:
223 $ gld -o output /lib/crt0.o hello.o -lc
225 This tells @code{gld} to produce a file called @code{output} as the
226 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
227 the library @code{libc.a} which will come from the standard search
230 The command-line options to @code{gld} may be specified in any order, and
231 may be repeated at will. For the most part, repeating an option with a
232 different argument will either have no further effect, or override prior
233 occurrences (those further to the left on the command line) of an
236 The exceptions---which may meaningfully be used more than once---are
237 @code{-A}, @code{-b} (or its synonym @code{-format}), @code{-defsym},
238 @code{-L}, @code{-l}, @code{-R}, and @code{-u}.
241 The list of object files to be linked together, shown as @var{objfiles},
242 may follow, precede, or be mixed in with command-line options; save that
243 an @var{objfiles} argument may not be placed between an option flag and
246 Usually the linker is invoked with at least one object file, but other
247 forms of binary input files can also be specified with @code{-l},
248 @code{-R}, and the script command language. If @emph{no} binary input
249 files at all are specified, the linker does not produce any output, and
250 issues the message @samp{No input files}.
252 Option arguments must either follow the option letter without intervening
253 whitespace, or be given as separate arguments immediately following the
254 option that requires them.
257 @item @var{objfiles}@dots{}
258 The object files @var{objfiles} to be linked.
260 @cindex architectures
262 @item -A@var{architecture}
263 In the current release of @code{gld}, this option is useful only for the
264 Intel 960 family of architectures. In that @code{gld} configuration, the
265 @var{architecture} argument identifies the particular architecture in
266 the 960 family, enabling some safeguards and modifying the
267 archive-library search path. @xref{i960-arch,,,Linking for a Specific
268 i960 Architecture}, for details.
270 Future releases of @code{gld} may support similar functionality for
271 other architecture families.
273 @cindex binary input format
274 @kindex -b @var{format}
276 @item -b @var{input-format}
278 Specify the binary format for input object files that follow this option
279 on the command line. You don't usually need to specify this, as
280 @code{gld} is configured to expect as a default input format the most
281 usual format on each machine. @var{input-format} is a text string, the
282 name of a particular format supported by the BFD libraries. @xref{BFD}.
283 @code{-format @var{input-format}} has the same effect.@refill
285 You may want to use this option if you are linking files with an unusual
286 binary format. You can also use @code{-b} to switch formats explicitly (when
287 linking object files of different formats), by including
288 @code{-b @var{input-format}} before each group of object files in a
291 The default format is taken from the environment variable
292 @code{GNUTARGET}. @xref{Environment}. You can also define the input
293 format from a script, using the command @code{TARGET}.
297 This flag is accepted for command-line compatibility with the SunOS linker,
298 but has no effect on @code{gld}.
300 @kindex -c @var{cmdfile}
302 @item -c @var{commandfile}
303 Directs @code{gld} to read link commands from the file
304 @var{commandfile}. These commands will completely override @code{gld}'s
305 default link format (rather than adding to it); @var{commandfile} must
306 specify everything necessary to describe the target format.
309 You may also include a script of link commands directly in the command
310 line by bracketing it between @samp{@{} and @samp{@}} characters.
312 @cindex common allocation
319 These three options are equivalent; multiple forms are supported for
320 compatibility with other linkers. Use any of them to make @code{ld}
321 assign space to common symbols even if a relocatable output file is
322 specified (@code{-r}). The script command
323 @code{FORCE_COMMON_ALLOCATION} has the same effect.
325 @cindex symbols, from command line
326 @kindex -defsym @var{symbol}=@var{exp}
327 @item -defsym @var{symbol} = @var{expression}
328 Create a global symbol in the output file, containing the absolute
329 address given by @var{expression}. You may use this option as many
330 times as necessary to define multiple symbols in the command line. A
331 limited form of arithmetic is supported for the @var{expression} in this
332 context: you may give a hexadecimal constant or the name of an existing
333 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
334 constants or symbols. If you need more elaborate expressions, consider
335 using the linker command language from a script.
337 @cindex entry point, from command line
338 @kindex -e @var{entry}
340 Use @var{entry} as the explicit symbol for beginning execution of your
341 program, rather than the default entry point. @xref{Entry Point}, for a
342 discussion of defaults and other ways of specifying the
346 @cindex fill, from command line
347 @kindex -f @var{fill}
348 @c -f in older GNU linker, not in new
350 Sets the default fill pattern for ``holes'' in the output file to
351 the lowest two bytes of the expression specified. Holes are created
352 when you advance the location counter (@xref{Location Counter}), or when
353 there is a gap between explicitly specified section addresses
354 (@xref{Section Options}).
359 @itemx -F@var{format}
360 Some older linkers used this option throughout a compilation toolchain
361 for specifying object-file format for both input and output object
362 files. @code{gld}'s mechanisms (the @code{-b} or @code{-format} options
363 for input files, the @code{TARGET} command in linker scripts for output
364 files, the @code{GNUTARGET} environment variable) are more flexible, but
365 but it accepts (and ignores) the @code{-F} option flag for compatibility
366 with scripts written to call the old linker.
369 @item -format @var{input-format}
370 Synonym for @code{-b} @var{input-format}.
374 Accepted, but ignored; provided for compatibility with other tools.
377 @cindex incremental link
379 Perform an incremental link (same as option @code{-r}).
381 @cindex archive files, from cmd line
384 Add an archive file @var{ar} to the list of files to link. This
385 option may be used any number of times. @code{ld} will search its
386 path-list for occurrences of @code{lib@var{ar}.a} for every @var{ar}
389 @cindex search directory, from cmd line
391 @item -L@var{searchdir}
392 This command adds path @var{searchdir} to the list of paths that
393 @code{gld} will search for archive libraries. You may use this option
396 The default set of paths searched (without being specified with
397 @code{-L}) depends on what emulation mode @code{gld} is using, and in
398 some cases also on how it was configured. @xref{Environment}. The
399 paths can also be specified in a link script with the @code{SEARCH_DIR}
407 Print (to the standard output file) a link map---diagnostic information
408 about where symbols are mapped by @code{ld}, and information on global
409 common storage allocation.
412 @c -N in older GNU linker, not in new
414 @cindex read/write from cmd line
417 specifies readable and writable @code{text} and @code{data} sections. If
418 the output format supports Unix style magic numbers, the output is
419 marked as @code{OMAGIC}.
424 @cindex read-only text
426 sets the text segment to be read only, and @code{NMAGIC} is written
429 @item -noinhibit-exec
430 @cindex output file after errors
431 @kindex -noinhibit-exec
432 Normally, the linker will not produce an output file if it encounters
433 errors during the link process. With this flag, you can specify that
434 you wish the output file retained even after non-fatal errors.
436 @item -o @var{output}
437 @kindex -o @var{output}
438 @cindex naming the output file
439 @var{output} is a name for the program produced by @code{ld}; if this
440 option is not specified, the name @samp{a.out} is used by default. The
441 script command @code{OUTPUT} can also specify the output file name.
443 @item -R @var{filename}
444 @kindex -R @var{file}
445 @cindex symbol-only input
446 Read symbol names and their addresses from @var{filename}, but do not
447 relocate it or include it in the output. This allows your output file
448 to refer symbolically to absolute locations of memory defined in other
453 @cindex synthesizing linker
454 @cindex relaxing addressing modes
455 An option with machine dependent effects. Currently this option is only
456 supported on the H8/300; see @ref{H8/300,,@code{gld} and the H8/300}.
458 On some platforms, use this option to perform global optimizations that
459 become possible when the linker resolves addressing in your program, such
460 as relaxing address modes and synthesizing new instructions in the
463 On platforms where this is not supported, @samp{-relax} is accepted, but
468 @cindex relocatable output
470 Generates relocatable output---i.e., generate an output file that can in
471 turn serve as input to @code{gld}. This is often called @dfn{partial
472 linking}. As a side effect, in environments that support standard Unix
473 magic numbers, this option also sets the output file's magic number to
476 If this option is not specified, an absolute file is produced. When
477 linking C++ programs, this option @emph{will not} resolve references to
478 constructors; @code{-Ur} is an alternative. @refill
480 This option does the same as @code{-i}.
484 @cindex strip debugger symbols
485 Omits debugger symbol information (but not all symbols) from the output file.
489 @cindex strip all symbols
490 Omits all symbol information from the output file.
492 @item @{ @var{script} @}
493 @kindex @{ @var{script} @}
494 @cindex scripts on command line
495 You can, if you wish, include a script of linker commands directly in
496 the command line instead of referring to it via an input file. When the
497 character @samp{@{} occurs on the command line, the linker switches to
498 interpreting the command language until the end of the list of commands
499 is reached---flagged with a closing brace @samp{@}}. Other command-line
500 options will not be recognized while parsing the script.
501 @xref{Commands} for a description of the command language.
503 @item -Tbss @var{org}
504 @kindex -Tbss @var{org}
505 @itemx -Tdata @var{org}
506 @kindex -Tdata @var{org}
507 @itemx -Ttext @var{org}
508 @kindex -Ttext @var{org}
509 @cindex segment origins, cmd line
510 Use @var{org} as the starting address for---respectively---the
511 @code{bss}, @code{data}, or the @code{text} segment of the output file.
512 @var{textorg} must be a hexadecimal integer.
514 @item -T @var{commandfile}
515 @itemx -T@var{commandfile}
516 @kindex -T @var{script}
517 Equivalent to @code{-c @var{commandfile}}; supported for compatibility with
523 @cindex input files, displaying
524 Prints names of input files as @code{ld} processes them.
528 @cindex undefined symbol
529 Forces @var{sym} to be entered in the output file as an undefined symbol.
530 This may, for example, trigger linking of additional modules from
531 standard libraries. @code{-u} may be repeated with different option
532 arguments to enter additional undefined symbols.
533 @c Nice idea, but no such command: This option is equivalent
534 @c to the @code{EXTERN} linker command.
539 For anything other than C++ programs, this option is equivalent to
540 @code{-r}: it generates relocatable output---i.e., an output file that can in
541 turn serve as input to @code{gld}. When linking C++ programs, @code{-Ur}
542 @emph{will} resolve references to constructors, unlike @code{-r}.
547 Display the version number for @code{gld}.
551 @cindex local symbols, deleting
552 @cindex L, deleting symbols beginning
553 If @code{-s} or @code{-S} is also specified, delete only local symbols
554 beginning with @samp{L}.
558 @cindex deleting local symbols
559 If @code{-s} or @code{-S} is also specified, delete all local symbols,
560 not just those beginning with @samp{L}.
563 @c -z in older GNU linker, not in new
566 @cindex read-only text
567 Specifies a read-only, demand pageable, and shared @code{text} segment.
568 If the output format supports Unix-style magic numbers, @code{-z} also
569 marks the output as @code{ZMAGIC}, the default.
571 @c why was following here?. Is it useful to say '-z -r' for
572 @c instance, or is this just a ref to other ways of setting
574 Specifying a relocatable output file (@code{-r}) will also set the magic
575 number to @code{OMAGIC}.
577 See description of @code{-N}.
582 @node Environment, , Options, Invocation
583 @section Environment Variables
585 You can condition the behavior of @code{gld} with two environment
586 variables: @code{GNUTARGET} and @code{LDEMULATION}. Depending on the
587 setting of the latter, other environment variables may be used as well.
590 @cindex default input format
591 @code{GNUTARGET} determines the input-file object format if you don't
592 use @code{-b} (or its synonym @code{-format}). Its value should be one
593 of the BFD names for an input format (@pxref{BFD}). If there is no
594 @code{GNUTARGET} in the environment, @code{gld} uses the natural format
595 of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
596 input format by examining binary input files; this method often
597 succeeds, but there are potential ambiguities, since there is no method
598 of ensuring that the magic number used to flag object-file formats is
599 unique. However, the configuration procedure for BFD on each system
600 places the conventional format for that system first in the search-list,
601 so ambiguities are resolved in favor of convention.
605 @cindex environment vars
606 @code{LDEMULATION} controls some aspects of @code{gld}'s dominant
607 personality. Although @code{gld} is flexible enough to permit its use
608 in many contexts regardless of configuration, you can use this variable
609 to make it act more like one or another older linker by default.
612 @cindex library paths, default
613 In particular, the value of @code{LDEMULATION} controls what default
614 linker script is used (thereby controlling the default input and output
615 formats; @pxref{BFD}); what default paths are searched for
616 archive libraries; and in some cases whether additional linker script
617 commands are available.
619 Here is the current set of emulations available:
622 @item LDEMULATION=gld
624 @cindex emulating old GNU linker
625 Emulate the older GNU linker. When this emulation is selected, the
626 default library search paths are
633 The default output format is set to @code{a.out-generic-big}, and the
634 default machine is the system's configured BFD default.
636 @item LDEMULATION=gld68k
639 A variant of the @code{gld} emulation; only differs in specifically
640 setting the default BFD machine as @code{m68k}.
642 @item LDEMULATION=gld960
643 @itemx LDEMULATION=lnk960
644 Emulate older linkers for the i960 family; see @ref{i960,,@code{gld} and
645 the Intel 960 family}, for details.
647 @item LDEMULATION=gldm88kbcs
648 Configure the linker for the Motorola 88K family.
649 @xref{m88k,,@code{gld} and the Motorola 880x0 family}, for details.
651 @item LDEMULATION=vanilla
653 @cindex emulation, disabling
654 @cindex disabling emulation
655 This is the least specific setting for @code{gld}. You can set
656 @code{LDEMULATION=vanilla} to disable emulation of other linkers. This
657 setting makes @code{gld} take the default machine from the BFD
658 configuration on your system; @code{a.out-generic-big} is the default
659 target. No other defaults are specified.
662 @node Commands, Machine Dependent, Invocation, Top
663 @chapter Command Language
665 @cindex command files
666 The command language allows explicit control over the link process,
667 allowing complete specification of the mapping between the linker's
668 input files and its output. This includes:
677 addresses of sections
679 placement of common blocks
682 You may supply a command file (also known as a link script) to the
683 linker either explicitly through the @code{-c} option, or implicitly as
684 an ordinary file. If the linker opens a file which it cannot recognize
685 as a supported object or archive format, it tries to interpret the file
688 You can also include a script directly on the @code{gld} command line,
689 delimited by the characters @samp{@{} and @samp{@}}.
692 * Scripts:: Linker Scripts
693 * Expressions:: Expressions
694 * MEMORY:: MEMORY Command
695 * SECTIONS:: SECTIONS Command
696 * Entry Point:: The Entry Point
697 * Other Commands:: Other Commands
700 @node Scripts, Expressions, Commands, Commands
701 @section Linker Scripts
702 The @code{gld} command language is a collection of statements; some are
703 simple keywords setting a particular flag, some are used to select and
704 group input files or name output files; and two particular statement
705 types have a fundamental and pervasive impact on the linking process.
707 @cindex fundamental script commands
708 @cindex commands, fundamental
709 @cindex output file layout
710 @cindex layout of output file
711 The most fundamental command of the @code{gld} command language is the
712 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
713 script must have a @code{SECTIONS} command: it specifies a
714 ``picture'' of the output file's layout, in varying degrees of detail.
715 No other command is required in all cases.
717 The @code{MEMORY} command complements @code{SECTIONS} by describing the
718 available memory in the target architecture. This command is optional;
719 if you don't use a @code{MEMORY} command, @code{gld} assumes sufficient
720 memory is available in a contiguous block for all output.
724 You may include comments in linker scripts just as in C: delimited
725 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
726 equivalent to whitespace.
728 @node Expressions, MEMORY, Scripts, Commands
730 @cindex expression syntax
732 Many useful commands involve arithmetic expressions. The syntax for
733 expressions in the command language is identical to that of C
734 expressions, with the following features:
737 All expressions evaluated as integers and
738 are of ``long'' or ``unsigned long'' type.
740 All constants are integers.
742 All of the C arithmetic operators are provided.
744 You may reference, define, and create global variables.
746 You may call special purpose built-in functions.
750 * Integers:: Integers
751 * Symbols:: Symbol Names
752 * Location Counter:: The Location Counter
753 * Operators:: Operators
754 * Evaluation:: Evaluation
755 * Assignment:: Assignment: Defining Symbols
756 * Built-ins:: Built-In Functions
759 @node Integers, Symbols, Expressions, Expressions
761 @cindex integer notation
762 @cindex octal integers
763 An octal integer is @samp{0} followed by zero or more of the octal
764 digits (@samp{01234567}).
769 @cindex decimal integers
770 A decimal integer starts with a non-zero digit followed by zero or
771 more digits (@samp{0123456789}).
776 @cindex hexadecimal integers
778 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
779 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
784 @cindex negative integers
785 Decimal integers have the usual values. To write a negative integer, use
786 the prefix operator @samp{-}; @pxref{Operators}.
791 @cindex scaled integers
792 @cindex K and M integer suffixes
793 @cindex M and K integer suffixes
794 @cindex suffixes for integers
795 @cindex integer suffixes
796 Additionally the suffixes @code{K} and @code{M} may be used to scale a
800 @c END TEXI2ROFF-KILL
801 @code{1024} or @code{1024*1024}
805 ${\rm 1024}$ or ${\rm 1024}^2$
807 @c END TEXI2ROFF-KILL
808 respectively. For example, the following all refer to the same quantity:@refill
816 @node Symbols, Location Counter, Integers, Expressions
817 @subsection Symbol Names
820 @cindex quoted symbol names
822 Unless quoted, symbol names start with a letter, underscore, point or
823 hyphen and may include any letters, underscores, digits, points,
824 and minus signs. Unquoted symbol names must not conflict with any
825 keywords. You can specify a symbol which contains odd characters or has
826 the same name as a keyword, by surrounding the symbol name in double quotes:
829 "with a space" = "also with a space" + 10;
832 @node Location Counter, Operators, Symbols, Expressions
833 @subsection The Location Counter
836 @cindex location counter
837 @cindex current output location
838 The special linker variable @dfn{dot} @samp{.} always contains the
839 current output location counter. Since the @code{.} always refers to
840 a location in an output section, it must always appear in an
841 expression within a @code{SECTIONS} command. The @code{.} symbol
842 may appear anywhere that an ordinary symbol is allowed in an
843 expression, but its assignments have a side effect. Assigning a value
844 to the @code{.} symbol will cause the location counter to be moved.
846 This may be used to create holes in the output section. The location
847 counter may never be moved backwards.
862 In the previous example, @code{file1} is located at the beginning of the
863 output section, then there is a 1000 byte gap. Then @code{file2}
864 appears, also with a 1000 byte gap following before @code{file3} is
865 loaded. The notation @samp{= 0x1234} specifies what data to write in
866 the gaps (@pxref{Section Options}).
868 @node Operators, Evaluation, Location Counter, Expressions
869 @subsection Operators
870 @cindex Operators for arithmetic
871 @cindex arithmetic operators
872 @cindex precedence in expressions
873 The linker recognizes the standard C set of arithmetic operators, with
874 the standard bindings and precedence levels:
877 @c END TEXI2ROFF-KILL
879 precedence associativity Operators Notes
885 5 left == != > < <= >=
891 11 right &= += -= *= /= (2)
896 (2) @xref{Assignment}
901 %"lispnarrowing" is the extra indent used generally for @example
902 \hskip\lispnarrowing\vbox{\offinterlineskip
905 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
906 height2pt&\omit&&\omit&&\omit&\cr
907 &Precedence&& Associativity &&{\rm Operators}&\cr
908 height2pt&\omit&&\omit&&\omit&\cr
910 height2pt&\omit&&\omit&&\omit&\cr
912 % '176 is tilde, '~' in tt font
913 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
917 &5&&left&&== != > < <= >=&\cr
923 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
925 height2pt&\omit&&\omit&&\omit&\cr}
930 @obeylines@parskip=0pt@parindent=0pt
931 @dag@quad Prefix operators.
932 @ddag@quad @xref{Assignment}.
935 @c END TEXI2ROFF-KILL
937 @node Evaluation, Assignment, Operators, Expressions
938 @subsection Evaluation
940 @cindex lazy evaluation
941 @cindex expression evaluation order
942 The linker uses ``lazy evaluation'' for expressions; it only calculates
943 an expression when absolutely necessary. The linker needs the value of
944 the start address, and the lengths of memory regions, in order to do any
945 linking at all; these values are computed as soon as possible when the
946 linker reads in the command file. However, other values (such as symbol
947 values) are not known or needed until after storage allocation. Such
948 values are evaluated later, when other information (such as the sizes of
949 output sections) is available for use in the symbol assignment
952 @node Assignment, Built-ins, Evaluation, Expressions
953 @subsection Assignment: Defining Symbols
954 @cindex assignment in scripts
955 @cindex symbol definition, scripts
956 @cindex variables, defining
957 You may create global symbols, and assign values (addresses) to global
958 symbols, using any of the C assignment operators:
961 @item @var{symbol} = @var{expression} ;
962 @itemx @var{symbol} &= @var{expression} ;
963 @itemx @var{symbol} += @var{expression} ;
964 @itemx @var{symbol} -= @var{expression} ;
965 @itemx @var{symbol} *= @var{expression} ;
966 @itemx @var{symbol} /= @var{expression} ;
969 Two things distinguish assignment from other operators in @code{gld}
973 Assignment may only be used at the root of an expression;
974 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
979 A trailing semicolon is required at the end of an assignment
983 Assignment statements may appear:
986 as commands in their own right in a @code{gld} script; or
988 as independent statements within a @code{SECTIONS} command; or
990 as part of the contents of a section definition in a
991 @code{SECTIONS} command.
994 The first two cases are equivalent in effect---both define a symbol with
995 an absolute address; the last case defines a symbol whose address is
996 relative to a particular section (@pxref{SECTIONS}).
998 @cindex absolute and relocatable symbols
999 @cindex relocatable and absolute symbols
1000 @cindex symbols, relocatable and absolute
1001 When a linker expression is evaluated and assigned to a variable, it is
1002 given either an absolute or a relocatable type. An absolute expression
1003 type is one in which the symbol contains the value that it will have in
1004 the output file, a relocateable expression type is one in which the
1005 value is expressed as a fixed offset from the base of a section.
1007 The type of the expression is controlled by its position in the script
1008 file. A symbol assigned within a section definition is created relative
1009 to the base of the section; a symbol assigned in any other place is
1010 created as an absolute symbol. Since a symbol created within a
1011 section definition is relative to the base of the section, it
1012 will remain relocatable if relocatable output is requested. A symbol
1013 may be created with an absolute value even when assigned to within a
1014 section definition by using the absolute assignment function
1015 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
1016 is the last byte of an output section named @code{.data}:
1022 _edata = ABSOLUTE(.) ;
1027 The linker tries to put off the evaluation of an assignment until all
1028 the terms in the source expression are known (@pxref{Evaluation}). For
1029 instance the sizes of sections cannot be known until after allocation,
1030 so assignments dependent upon these are not performed until after
1031 allocation. Some expressions, such as those depending upon the location
1032 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
1033 result of an expression is required, but the value is not available,
1034 then an error results. For example, a script like the following
1037 text 9+this_isnt_constant:
1042 @kindex Non constant expression
1044 will cause the error message ``@code{Non constant expression for initial
1047 @node Built-ins, , Assignment, Expressions
1048 @subsection Built-In Functions
1049 @cindex functions in expression language
1050 The command language includes a number of special purpose built-in
1051 functions for use in link script expressions.
1053 @item ABSOLUTE(@var{exp})
1054 @kindex ABSOLUTE(@var{exp})
1055 @cindex expression, absolute
1056 returns the absolute value of the expression @var{exp}. Primarily
1057 useful to assign an absolute value to a symbol within a section
1058 definition, where symbol values are normally section-relative.
1060 @item ADDR(@var{section})
1061 @kindex ADDR(@var{section})
1062 @cindex section address
1063 returns the absolute address of the named @var{section}. Your script must
1064 previously have defined the location of that section. In the following
1065 example the @code{symbol_1} and @code{symbol_2} are assigned identical
1071 start_of_output_1 = ABSOLUTE(.);
1076 symbol_1 = ADDR(.output1);
1077 symbol_2 = start_of_output_1;
1082 @item ALIGN(@var{exp})
1083 @kindex ALIGN(@var{exp})
1084 @cindex rounding up location counter
1085 returns the result of the current location counter (@code{.}) aligned to
1086 the next @var{exp} boundary. @var{exp} must be an expression whose
1087 value is a power of two. This is equivalent to
1089 (. + @var{exp} -1) & ~(@var{exp}-1)
1092 @code{ALIGN} doesn't change the value of the location counter---it just
1093 does arithmetic on it. As an example, to align the output @code{.data}
1094 section to the next @code{0x2000} byte boundary after the preceding
1095 section and to set a variable within the section to the next
1096 @code{0x8000} boundary after the input sections:
1099 .data ALIGN(0x2000): @{
1101 variable = ALIGN(0x8000);
1106 The first use of @code{ALIGN} in this example specifies the location of
1107 a section because it is used as the optional @var{start} attribute of a
1108 section definition (@pxref{Section Options}). The second use simply
1109 defines the value of a variable.
1111 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1113 @item DEFINED(@var{symbol})
1114 @kindex DEFINED(@var{symbol})
1115 @cindex symbol defaults
1116 Returns @code{1} if @var{symbol} is in the linker global symbol table and is
1117 defined, otherwise it returns @code{0}. You can use this to provide default
1118 values for symbols. For example, this command-file fragment shows how
1119 to set a global symbol @code{begin} to the first location in the
1120 @code{.text} section---but if a symbol called @code{begin} already
1121 existed, its value is preserved:
1125 begin = DEFINED(begin) ? begin : . ;
1131 @item NEXT(@var{exp})
1132 @kindex NEXT(@var{exp})
1133 @cindex unallocated address, next
1134 Returns the next unallocated address that is a multiple of @var{exp}.
1135 This command is closely related to @code{ALIGN(@var{exp})}; unless you
1136 use the @code{MEMORY} command to define discontinuous memory for the
1137 output file, the two commands are equivalent.
1139 @item SIZEOF(@var{section})
1140 @kindex SIZEOF(@var{section})
1141 @cindex section size
1142 returns the size in bytes of the named @var{section}, if the section has
1143 been allocated. In the following example the @code{symbol_1} and
1144 @code{symbol_2} are assigned identical values:
1152 symbol_1 = .end - .start;
1153 symbol_2 = SIZEOF(.output);
1158 @item SIZEOF_HEADERS
1159 @kindex SIZEOF_HEADERS
1161 @itemx sizeof_headers
1162 @kindex sizeof_headers
1163 the size in bytes of the output file's headers. You can use this number
1164 as the start address of the first section, if you choose, to facilitate
1169 @node MEMORY, SECTIONS, Expressions, Commands
1170 @section MEMORY Command
1172 @cindex regions of memory
1173 @cindex discontinuous memory
1174 @cindex allocating memory
1175 The linker's default configuration permits allocation of all memory.
1176 You can override this by using the @code{MEMORY} command. The
1177 @code{MEMORY} command describes the location and size of blocks of
1178 memory in the target. By using it carefully, you can describe which
1179 memory regions may be used by the linker, and which memory regions it
1180 must avoid. The linker does not shuffle sections to fit into the
1181 available regions, but does move the requested sections into the correct
1182 regions and issue errors when the regions become too full.
1184 Command files may contain at most one use of the @code{MEMORY}
1185 command; however, you can define as many blocks of memory within it as
1186 you wish. The syntax is:
1191 @var{name} (@var{attr}): ORIGIN = @var{origin}, LENGTH = @var{len}
1197 @cindex naming memory regions
1198 is a name used internally by the linker to refer to the region. Any
1199 symbol name may be used. The region names are stored in a separate
1200 name space, and will not conflict with symbols, filenames or section
1201 names. Use distinct names to specify multiple regions.
1203 @cindex memory region attributes
1204 is an optional list of attributes, permitted for compatibility with the
1205 AT&T linker but not used by @code{gld} beyond checking that the
1206 attribute list is valid. Valid attribute lists must be made up of the
1207 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1208 omit the parentheses around it as well.
1213 is the start address of the region in physical memory. It is expressed as
1214 an expression, which must evaluate to a constant before
1215 memory allocation is performed. The keyword @code{ORIGIN} may be
1216 abbreviated to @code{org} or @code{o}.
1221 is the size in bytes of the region (an expression).
1222 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1225 For example, to specify that memory has two regions available for
1226 allocation---one starting at @code{0} for 256 kilobytes, and the other
1227 starting at @code{0x40000000} for four megabytes:
1232 rom : ORIGIN= 0, LENGTH = 256K
1233 ram : org= 0x40000000, l = 4M
1237 Once you have defined a region of memory named @var{mem}, you can direct
1238 specific output sections there by using a command ending in
1239 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1240 Options}). If the combined output sections directed to a region are too
1241 big for the region, the linker will issue an error message.
1243 @node SECTIONS, Entry Point, MEMORY, Commands
1244 @section SECTIONS Command
1246 The @code{SECTIONS} command controls exactly where input sections are
1247 placed into output sections, their order and to which output sections
1250 You may use at most one @code{SECTIONS} command in a commands file,
1251 but you can have as many statements within it as you wish. Statements
1252 within the @code{SECTIONS} command can do one of three things:
1255 define the entry point;
1257 assign a value to a symbol;
1259 describe the placement of a named output section, and what input
1260 sections make it up.
1263 The first two possibilities---defining the entry point, and defining
1264 symbols---can also be done outside the @code{SECTIONS} command:
1265 @pxref{Entry Point}, @pxref{Assignment}. They are permitted here as
1266 well for your convenience in reading the script, so that symbols or the
1267 entry point can be defined at meaningful points in your output-file
1270 When no @code{SECTIONS} command is specified, the default action
1271 of the linker is to place each input section into an identically named
1272 output section in the order that the sections are first encountered in
1273 the input files; if all input sections are present in the first file,
1274 for example, the order of sections in the output file will match the
1275 order in the first input file.
1278 * Section Definition:: Section Definitions
1279 * Section Contents:: Section Contents
1280 * Section Options:: Optional Section Attributes
1283 @node Section Definition, Section Contents, SECTIONS, SECTIONS
1284 @subsection Section Definitions
1285 @cindex section definition
1286 The most frequently used statement in the @code{SECTIONS} command is
1287 the @dfn{section definition}, which you can use to specify the
1288 properties of an output section: its location, alignment, contents,
1289 fill pattern, and target memory region can all be specified. Most of
1290 these specifications are optional; the simplest form of a section
1299 @cindex naming output sections
1301 @var{secname} is the name of the output section, and @var{contents} a
1302 specification of what goes there---for example a list of input files or
1303 sections of input files. As you might assume, the whitespace shown is
1304 optional; you do need the colon @samp{:} and the braces @samp{@{@}},
1307 @var{secname} must meet the constraints of your output format. In
1308 formats which only support a limited number of sections, such as
1309 @code{a.out}, the name must be one of the names supported by the format
1310 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1311 @code{.bss}). If the output format supports any number of sections, but
1312 with numbers and not names (as is the case for Oasys), the name should be
1313 supplied as a quoted numeric string. A section name may consist of any
1314 sequence characters, but any name which does not conform to the standard
1315 @code{gld} symbol name syntax must be quoted.
1317 @node Section Contents, Section Options, Section Definition, SECTIONS
1318 @subsection Section Contents
1319 @cindex contents of a section
1320 In a section definition, you can specify the contents of an output section by
1321 listing particular object files; by listing particular input-file
1322 sections; or a combination of the two. You can also place arbitrary
1323 data in the section, and define symbols relative to the beginning of the
1326 The @var{contents} of a section definition may include any of the
1327 following kinds of statement. You can include as many of these as you
1328 like in a single section definition, separated from one another by
1332 @item @var{filename}
1333 @kindex @var{filename}
1334 @cindex input files, section defn
1335 @cindex files, including in output sections
1336 You may simply name a particular input file to be placed in the current
1337 output section; @emph{all} sections from that file are placed in the
1338 current section definition. To specify a list of particular files by
1341 .data: @{ afile.o bfile.o cfile.o @}
1344 The example also illustrates that multiple statements can be included in
1345 the contents of a section definition, since each filename is a separate
1348 If the file name has already been mentioned in another section
1349 definition, with an explicit section name list, then only those sections
1350 which have not yet been allocated are used.
1352 @item @var{filename}( @var{section} )
1353 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1354 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1355 @kindex @var{filename}(@var{section})
1356 @cindex files and sections, section defn
1357 You can name one or more sections from your input files, for
1358 insertion in the current output section. If you wish to specify a list
1359 of input-file sections inside the parentheses, you may separate the
1360 section names by either commas or whitespace.
1362 @item * (@var{section})
1363 @itemx * (@var{section}, @var{section}, @dots{})
1364 @itemx * (@var{section} @var{section} @dots{}
1365 @cindex input sections to output section
1366 @kindex *(@var{section})
1367 Instead of explicitly naming particular input files in a link control
1368 script, you can refer to @emph{all} files from the @code{gld} command
1369 line: use @samp{*} instead of a particular filename before the
1370 parenthesized input-file section list.
1372 For example, to copy sections @code{1} through @code{4} from a Oasys file
1373 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1374 and @code{14} into the @code{.data} section:
1387 If you have already explicitly included some files by name, @samp{*}
1388 refers to all @emph{remaining} files---those whose places in the output
1389 file have not yet been defined.
1391 @item [ @var{section} ]
1392 @itemx [ @var{section}, @var{section}, @dots{} ]
1393 @itemx [ @var{section} @var{section} @dots{} ]
1394 @kindex [ @var{sections} ]
1395 This is an alternate notation to specify named sections from all
1396 unallocated input files; its effect is exactly the same as that of
1397 @samp{* (@var{section}@dots{})}
1399 @item @var{filename}@code{( COMMON )}
1402 @cindex uninitialized data
1403 @cindex commons in output
1404 Specify where in your output file to place uninitialized data
1405 with this notation. @code{[COMMON]} by itself refers to all
1406 uninitialized data from all input files (so far as it is not yet
1407 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1408 from a particular file. Both are special cases of the general
1409 mechanisms for specifying where to place input-file sections:
1410 @code{gld} permits you to refer to uninitialized data as if it
1411 were in an input-file section named @code{COMMON}, regardless of the
1412 input file's format.
1415 For example, the following command script arranges the output file into
1416 three consecutive sections, named @code{.text}, @code{.data}, and
1417 @code{.bss}, taking the input for each from the correspondingly named
1418 sections of all the input files:
1421 .text: @{ *(.text) @}
1422 .data: @{ *(.data) @}
1423 .bss: @{ *(.bss) [COMMON] @}
1427 The following example reads all of the sections from file @code{all.o}
1428 and places them at the start of output section @code{outputa} which
1429 starts at location @code{0x10000}. All of section @code{.input1} from
1430 file @code{foo.o} follows immediately, in the same output section. All
1431 of section @code{.input2} from @code{foo.o} goes into output section
1432 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1433 All of the remaining @code{.input1} and @code{.input2} sections from any
1434 files are written to output section @code{outputc}.
1456 There are still more kinds of statements permitted in the contents of
1457 output section definitions. The foregoing statements permitted you to
1458 arrange, in your output file, data originating from your input files.
1459 You can also place data directly in an output section from the link
1460 command script. Most of these additional statements involve
1461 expressions; @pxref{Expressions}. Although these statements are shown
1462 separately here for ease of presentation, no such segregation is needed
1463 within a section definition in the @code{SECTIONS} command; you can
1464 intermix them freely with any of the statements we've just described.
1467 @item CREATE_OBJECT_SYMBOLS
1468 @kindex CREATE_OBJECT_SYMBOLS
1469 @cindex input filename symbols
1470 @cindex filename symbols
1471 instructs the linker to create a symbol for each input file
1472 in the current section, set with the address of the first byte of
1473 data written from the input file. For instance, with @code{a.out}
1474 files it is conventional to have a symbol for each input file. You can
1475 accomplish this by defining the output @code{.text} section as follows:
1480 CREATE_OBJECT_SYMBOLS
1482 _etext = ALIGN(0x2000);
1488 If @code{objsym} is a file containing this script, and @code{a.o},
1489 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1490 contents like the following---
1500 @samp{gld -M sample a.o b.o c.o d.o} would create a map like this,
1501 containing symbols matching the object file names:
1503 00000000 A __DYNAMIC
1506 00002020 T _afunction
1509 00002038 T _bfunction
1512 00002050 T _cfunction
1515 00002068 T _dfunction
1525 @item @var{symbol} = @var{expression} ;
1526 @kindex @var{symbol} = @var{expression} ;
1527 @itemx @var{symbol} @var{f}= @var{expression} ;
1528 @kindex @var{symbol} @var{f}= @var{expression} ;
1529 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1530 refers to any of the operators @code{&= += -= *= /=} which combine
1531 arithmetic and assignment.
1533 @cindex assignment, in section defn
1534 When you assign a value to a symbol within a particular section
1535 definition, the value is relative to the beginning of the section
1536 (@pxref{Assignment}). If you write
1541 .data: @{ @dots{} rel = 14 ; @dots{} @}
1542 abs2 = 14 + ADDR(.data);
1546 @c FIXME: Try above example!
1548 @code{abs} and @var{rel} do not have the same value; @code{rel} has the
1549 same value as @code{abs2}.
1551 @item BYTE(@var{expression})
1552 @kindex BYTE(@var{expression})
1553 @itemx SHORT(@var{expression})
1554 @kindex SHORT(@var{expression})
1555 @itemx LONG(@var{expression})
1556 @kindex LONG(@var{expression})
1557 @cindex direct output
1558 By including one of these three statements in a section definition, you
1559 can explicitly place one, two, or four bytes (respectively) at the
1560 current address of that section. Multiple-byte quantities are
1561 represented in whatever byte order is appropriate for the output file
1562 format (@pxref{BFD}).
1564 @item FILL(@var{expression})
1565 @kindex FILL(@var{expression})
1566 @cindex holes, filling
1567 @cindex unspecified memory
1568 Specifies the ``fill pattern'' for the current section. Any otherwise
1569 unspecified regions of memory within the section (for example, regions
1570 you skip over by assigning a new value to the location counter @samp{.})
1571 are filled with the two least significant bytes from the
1572 @var{expression} argument. A @code{FILL} statement covers memory
1573 locations @emph{after} the point it occurs in the section definition; by
1574 including more than one @code{FILL} statement, you can have different
1575 fill patterns in different parts of an output section.
1578 @node Section Options, , Section Contents, SECTIONS
1579 @subsection Optional Section Attributes
1580 @cindex section defn, full syntax
1581 Here is the full syntax of a section definition, including all the
1587 @var{secname} @var{start} BLOCK(@var{align}) : @{ @var{contents} @} =@var{fill} >@var{region}
1592 @var{secname} and @var{contents} are required. @xref{Section
1593 Definition}, and @pxref{Section Contents} for details on @var{contents}.
1594 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1595 @code{=@var{fill}}, and @code{>@var{region}}---are all optional.
1599 @cindex start address, section
1600 @cindex section start
1601 @cindex section address
1602 You can force the output section to be loaded at a specified address by
1603 specifying @var{start} immediately following the section name.
1604 @var{start} can be represented as any expression. The following
1605 example generates section @var{output} at location
1610 output 0x40000000: @{
1617 @item BLOCK(@var{align})
1618 @kindex BLOCK(@var{align})
1619 @cindex section alignment
1620 @cindex aligning sections
1621 You can include @code{BLOCK()} specification to advance the location of
1622 the location counter @code{.} prior to the beginning of the section, so
1623 that the section will begin at the specified alignment. @var{align} is
1628 @cindex section fill pattern
1629 @cindex fill pattern, entire section
1630 You may use any expression to specify @var{fill}. Including
1631 @code{=@var{fill}} in a section definition specifies the initial fill
1632 value for that section. Any unallocated holes in the current output
1633 section when written to the output file will be filled with the two
1634 least significant bytes of the value, repeated as necessary. You can
1635 also change the fill value with a @code{FILL} statement in the
1636 @var{contents} of a section definition.
1639 @kindex >@var{region}
1640 @cindex section, assigning to memory region
1641 @cindex memory regions and sections
1642 Assign this section to a previously defined region of memory.
1647 @node Entry Point, Other Commands, SECTIONS, Commands
1648 @section The Entry Point
1649 @kindex ENTRY(@var{symbol})
1650 @cindex start of execution
1651 @cindex first instruction
1652 The linker command language includes a command specifically for
1653 defining the first executable instruction in an output file (its
1654 @dfn{entry point}). Its argument is a symbol name:
1659 Like symbol assignments, the @code{ENTRY} command may be placed either
1660 as an independent command in the command file, or among the section
1661 definitions within the @code{SECTIONS} command---whatever makes the most
1662 sense for your layout.
1664 @cindex entry point, defaults
1665 @code{ENTRY} is only one of several ways of choosing the entry point.
1666 You may indicate it in any of the following ways (shown in descending
1667 order of priority: methods higher in the list override methods lower down).
1670 the @code{-e} @var{entry} command-line option;
1672 the @code{ENTRY(@var{symbol}} command in a linker control script;
1674 the value of the symbol @code{start}, if present;
1676 the value of the symbol @code{_main}, if present;
1678 the address of the first byte of the @code{.text} section, if present;
1680 The address @code{0}.
1683 For example, you can use these rules to generate an entry point with an
1684 assignment statement: if no symbol @code{start} is defined within your
1685 input files, you can simply define it, assigning it an appropriate
1692 The example shows an absolute address, but you can use any expression.
1693 For example, if your input object files use some other symbol-name
1694 convention for the entry point, you can just assign the value of
1695 whatever symbol contains the start address to @code{start}:
1697 start = other_symbol;
1700 @node Other Commands, , Entry Point, Commands
1701 @section Other Commands
1702 The command language includes a number of other commands that you can
1703 use for specialized purposes. They are similar in purpose to
1704 command-line options.
1711 These keywords were used in some older linkers to request a particular
1712 math subroutine library. @code{gld} doesn't use the keywords, assuming
1713 instead that any necessary subroutines are in libraries specified using
1714 the general mechanisms for linking to archives; but to permit the use of
1715 scripts that were written for the older linkers, the keywords
1716 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1718 @item FORCE_COMMON_ALLOCATION
1719 @kindex FORCE_COMMON_ALLOCATION
1720 @cindex common allocation
1721 This command has the same effect as the @code{-d} command-line option:
1722 to make @code{ld} assign space to common symbols even if a relocatable
1723 output file is specified (@code{-r}).
1725 @item INPUT ( @var{file}, @var{file}, @dots{} )
1726 @kindex INPUT ( @var{files} )
1727 @itemx INPUT ( @var{file} @var{file} @dots{} )
1728 @cindex binary input files
1729 Use this command to include binary input files in the link, without
1730 including them in a particular section definition. Files specified this
1731 way are treated identically to object files listed on the command line.
1734 @item MAP ( @var{name} )
1735 @kindex MAP ( @var{name} )
1736 @c MAP(...) appears to look for an F in the arg, ignoring all other
1737 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1738 @c checks map_option_f. Apparently a stub for the future...
1741 @item OUTPUT ( @var{filename} )
1742 @kindex OUTPUT ( @var{filename} )
1743 @cindex naming the output file
1744 Name the link output file @var{filename}. The effect of
1745 @code{OUTPUT(@var{filename})} is identical to the effect of
1746 @w{@code{-o @var{filename}}}, and whichever is encountered last will
1747 control the name actually used to name the output file. In particular,
1748 you can use this command to supply a default output-file name other than
1751 @item OUTPUT_ARCH ( @var{bfdname} )
1752 @kindex OUTPUT_ARCH ( @var{bfdname} )
1753 @cindex machine architecture, output
1754 Specify a particular output machine architecture, with one of the names
1755 used by the BFD back-end routines (@pxref{BFD}). This command is often
1756 unnecessary; the architecture is most often set implicitly by either the
1757 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1760 @item OUTPUT_FORMAT ( @var{bfdname} )
1761 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1762 @cindex format, output file
1763 Specify a particular output format, with one of the names used by the
1764 BFD back-end routines (@pxref{BFD}). This selection will only affect
1765 the output file; the related command @code{TARGET} affects primarily
1768 @item SEARCH_DIR ( @var{path} )
1769 @kindex SEARCH_DIR ( @var{path} )
1770 @cindex path for libraries
1771 @cindex search path, libraries
1772 Add @var{path} to the list of paths where @code{gld} looks for
1773 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1774 effect as @code{-L@var{path})} on the command line.
1776 @item STARTUP ( @var{filename} )
1777 @kindex STARTUP ( @var{filename} )
1778 @cindex first input file
1779 Ensure that @var{filename} is the first input file used in the link
1782 @item TARGET ( @var{format} )
1783 @cindex input file format
1784 @kindex TARGET ( @var{format} )
1785 Change the input-file object code format (like the command-line option
1786 @code{-b} or its synonym @code{-format}). The argument @var{format} is
1787 one of the strings used by BFD to name binary formats. In the current
1788 @code{gld} implementation, if @code{TARGET} is specified but
1789 @code{OUTPUT_FORMAT} is not, the last @code{TARGET} argument is also
1790 used as the default format for the @code{gld} output file.
1794 If you don't use the @code{TARGET} command, @code{gld} uses the value of
1795 the environment variable @code{GNUTARGET}, if available, to select the
1796 output file format. If that variable is also absent, @code{gld} uses
1797 the default format configured for your machine in the BFD libraries.
1801 @node Machine Dependent, BFD, Commands, Top
1802 @chapter Machine Dependent Features
1804 @cindex machine dependencies
1805 @code{gld} has additional features on some platforms; the following
1806 sections describe them. Machines where @code{gld} has no additional
1807 functionality are not listed.
1810 * H8/300:: @code{gld} and the H8/300
1811 * i960:: @code{gld} and the Intel 960 family
1812 * m68k:: @code{gld} and the Motorola 68000 family
1813 * m88k:: @code{gld} and the Motorola 880x0 family
1816 @node H8/300, i960, Machine Dependent, Machine Dependent
1817 @section @code{gld} and the H8/300
1819 @cindex H8/300 support
1820 For the H8/300, @code{gld} can perform these global optimizations when
1821 you specify the @samp{-relax} command-line option.
1824 @item relaxing address modes
1825 @cindex relaxing on i960
1826 @code{gld} finds all @code{jsr} and @code{jmp} instructions whose
1827 targets are within eight bits, and turns them into eight-bit
1828 program-counter relative @code{bsr} and @code{bra} instructions,
1831 @item synthesizing instructions
1832 @cindex synthesizing on i960
1833 @c FIXME: specifically mov.b, or any mov instructions really?
1834 @code{gld} finds all @code{mov.b} instructions which use the
1835 sixteen-bit absolute address form, but refer to the top
1836 page of memory, and changes them to use the eight-bit address form.
1837 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
1838 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
1839 top page of memory).
1842 @node i960, m68k, H8/300, Machine Dependent
1843 @section @code{gld} and the Intel 960 family
1845 @cindex i960 support
1847 * i960-arch:: Linking for a Specific i960 Architecture
1848 * i960-emulation:: Emulating Other i960 Linkers
1849 * i960-commands:: Command Language Extensions for i960
1852 @node i960-arch, i960-emulation, i960, i960
1853 @subsection Linking for a Specific i960 Architecture
1854 You can use the @samp{-A@var{architecture}} command line option to
1855 specify one of the two-letter names identifying members of the 960
1856 family; the option specifies the desired output target, and warns of any
1857 incompatible instructions in the input files. It also modifies the
1858 linker's search strategy for archive libraries, to support the use of
1859 libraries specific to each particular architecture, by including in the
1860 search loop names suffixed with the string identifying the architecture.
1862 For example, if your @code{gld} command line included @w{@samp{-ACA}} as
1863 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
1864 paths, and in any paths you specify with @code{-L}) for a library with
1873 The first two possibilities would be considered in any event; the last
1874 two are due to the use of @w{@samp{-ACA}}.
1876 You can meaningfully use @code{-A} more than once on a command line, since
1877 the 960 architecture family allows combination of target architectures; each
1878 use will add another pair of name variants to search for when @w{@code{-l}}
1879 specifies a library.
1881 @node i960-emulation, i960-commands, i960-arch, i960
1882 @subsection Emulating Other i960 Linkers
1883 You can set the @code{LDEMULATION} environment variable
1884 (@pxref{Environment,,Environment Variables}) to make
1885 @code{gld} more compatible with two older Intel 960 linkers:
1888 @item LDEMULATION=gld960
1893 Emulate the Intel port of the older @code{gld} for the i960
1894 architectures. The default library search paths are taken from two
1895 other environment variables, @code{G960LIB} and @code{G960BASE}. The
1896 default architecture is @code{i960}. The default output format is set
1897 to @code{b.out.big}, and in fact the default output file name (if
1898 @code{-o} is not specified) is @code{b.out}, to reflect this variant
1899 format, for this emulation.
1902 This emulation can behave slightly differently depending on the setting
1903 of the @code{gld} compile-time switch @code{GNU960}. If @code{gld} is
1904 compiled with @code{GNU960} defined, then an additional environment
1905 variable---@code{GNUTARGET}---is available; its value, if available,
1906 specifies some other default output format than @code{b.out.big}.
1908 @item LDEMULATION=lnk960
1911 @cindex Architectures, i960 family
1912 Emulate the Intel linker @code{lnk960}. The default output format is
1913 @code{coff-Intel-big}. With this emulation, @code{gld}
1914 supports the additional script commands @code{HLL} and @code{SYSLIB} for
1915 specification of library archives. This is the only emulation with
1916 extensive support for the @code{-A} (architecture) command-line option.
1917 By default, the architecture @code{CORE} is assumed, but you can choose
1918 additional features from the i960 architecture family by using one of
1919 the following with @code{-A} (or by using the @code{OUTPUT_ARCH} command
1932 The default libraries are chosen with some attention to the architecture
1933 selected; the core library @file{cg} is always included, but the library
1934 @code{fpg} is also used if you've specified any of the architectures
1935 @code{KA}, @code{SA}, or @code{CA}.
1938 Like @code{gld960}, this emulation uses additional environment variables
1939 to set the default library search paths. Also like @code{gld960}, the
1940 behavior of this emulation is slightly different depending on whether
1941 @code{gld} itself was compiled with @code{GNU960} defined.
1946 If your @code{gld} was compiled with @code{GNU960} defined, the default
1947 paths are taken from all three of @code{G960LIB}, @code{G960BASE}, and
1948 @code{I960BASE}. For the first two, paths you supply are automatically
1949 suffixed with @samp{/lib/libcoff}; for the last, your path is
1950 automatically suffixed with @samp{/lib}.
1952 If your @code{gld} was @emph{not} compiled with @code{GNU960} defined,
1953 the default paths are taken from @code{I960BASE}, and @code{G960BASE} is
1954 only consulted if @code{I960BASE} is undefined. In this case
1955 @code{G960LIB} is not used at all.
1958 @node i960-commands, , i960-emulation, i960
1959 @subsection Command Language Extensions for i960
1961 @code{gld} understands the following additional commands when
1962 @code{LDEMULATION} is set to @samp{lnk960}:
1965 @item HLL ( @var{file}, @var{file}, @dots{} )
1966 @itemx HLL ( @var{file} @var{file} @dots{} )
1968 @kindex HLL ( @var{files} )
1969 Include ``high-level libraries'' or archives as input files in the link.
1970 Using @code{HLL(@var{file}} in a linker script is equivalent to
1971 including @code{-l}@var{file} on the command line.
1973 @cindex @code{lnk960} command @code{HLL}
1974 The @code{HLL} command is only supported when @code{gld} emulates
1975 @code{lnk960}, as specified by the @code{LDEMULATION} environment
1978 @item SYSLIB ( @var{file}, @var{file}, @dots{} )
1979 @itemx SYSLIB ( @var{file} @var{file} @dots{} )
1980 @kindex SYSLIB ( @var{file}, @var{file}, @dots{} )
1981 Use the named @var{file}s as binary input files, searching for them in
1982 the same list of paths as archives.
1984 @cindex @code{lnk960} command @code{SYSLIB}
1985 The @code{SYSLIB} command is only supported when @code{gld} emulates
1986 @code{lnk960}, as specified by the @code{LDEMULATION} environment
1991 @node m68k, m88k, i960, Machine Dependent
1992 @section @code{gld} and the Motorola 680x0 family
1994 @cindex m68k support
1995 You can set the environment variable @code{LDEMULATION} to @samp{gld68k}
1996 for closer compatibility with the older GNU linker on Motorola 680x0
1997 platforms. This emulation is a variant of the @code{gld} emulation; it
1998 only differs in specifically setting the default BFD machine as
1999 @code{m68k}. @xref{Environment,,Environment Variables}.
2001 @node m88k, , m68k, Machine Dependent
2002 @section @code{gld} and the Motorola 880x0 family
2004 @cindex m88k support
2006 You can configure the linker to conform to the Motorola 88K BCS by
2007 setting the environment variable @code{LDEMULATION} to @samp{gldm88kbcs}.
2008 This sets the output format to @code{m88kbcs} and the architecture to
2009 @code{m88k}. Default library search paths are
2016 For other settings of @code{LDEMULATION}, consult
2017 @ref{Environment,,Environment Variables}.
2019 @node BFD, Index, Machine Dependent, Top
2023 @cindex object file management
2024 The linker accesses object and archive files using the BFD libraries.
2025 These libraries allow the linker to use the same routines to operate on
2026 object files whatever the object file format. A different object file
2027 format can be supported simply by creating a new BFD back end and adding
2028 it to the library. You can use @code{objdump -i}
2029 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
2030 list all the formats available for each architecture under BFD. This
2031 was the list of formats, and of architectures supported for each format,
2032 as of the time this manual was prepared:
2033 @cindex formats available
2034 @cindex architectures available
2036 BFD header file version 0.18
2038 (header big endian, data big endian)
2044 (header big endian, data big endian)
2050 (header big endian, data little endian)
2053 (header little endian, data little endian)
2056 (header big endian, data big endian)
2059 (header big endian, data big endian)
2062 (header little endian, data little endian)
2065 (header big endian, data little endian)
2068 (header little endian, data little endian)
2071 (header big endian, data big endian)
2074 (header big endian, data big endian)
2077 (header big endian, data big endian)
2080 (header little endian, data little endian)
2083 (header big endian, data big endian)
2095 (header little endian, data little endian)
2107 (header big endian, data big endian)
2119 (header big endian, data big endian)
2132 @cindex BFD requirements
2133 @cindex requirements for BFD
2134 As with most implementations, BFD is a compromise between
2135 several conflicting requirements. The major factor influencing
2136 BFD design was efficiency: any time used converting between
2137 formats is time which would not have been spent had BFD not
2138 been involved. This is partly offset by abstraction payback; since
2139 BFD simplifies applications and back ends, more time and care
2140 may be spent optimizing algorithms for a greater speed.
2142 One minor artifact of the BFD solution which you should bear in
2143 mind is the potential for information loss. There are two places where
2144 useful information can be lost using the BFD mechanism; during
2145 conversion and during output. @xref{BFD information loss}.
2148 * BFD outline:: How it works: an outline of BFD
2149 * BFD information loss:: Information Loss
2150 * Mechanism:: Mechanism
2153 @node BFD outline, BFD information loss, BFD, BFD
2154 @section How it works: an outline of BFD
2155 @cindex opening object files
2156 When an object file is opened, BFD subroutines automatically
2157 determine the format of the input object file, and build a descriptor in
2158 memory with pointers to routines that will be used to access elements of
2159 the object file's data structures.
2161 As different information from the the object files is required
2162 BFD reads from different sections of the file and processes them.
2163 For example a very common operation for the linker is processing symbol
2164 tables. Each BFD back end provides a routine for converting
2165 between the object file's representation of symbols and an internal
2166 canonical format. When the linker asks for the symbol table of an object
2167 file, it calls through the memory pointer to the relevant BFD
2168 back end routine which reads and converts the table into a canonical
2169 form. The linker then operates upon the common form. When the link is
2170 finished and the linker writes the symbol table of the output file,
2171 another BFD back end routine is called which takes the newly
2172 created symbol table and converts it into the chosen output format.
2174 @node BFD information loss, Mechanism, BFD outline, BFD
2175 @section Information Loss
2176 @emph{Information can be lost during output.} The output formats
2177 supported by BFD do not provide identical facilities, and
2178 information which may be described in one form has nowhere to go in
2179 another format. One example of this is alignment information in
2180 @code{b.out}. There is nowhere in an @code{a.out} format file to store
2181 alignment information on the contained data, so when a file is linked
2182 from @code{b.out} and an @code{a.out} image is produced, alignment
2183 information will not propagate to the output file. (The linker will
2184 still use the alignment information internally, so the link is performed
2187 Another example is COFF section names. COFF files may contain an
2188 unlimited number of sections, each one with a textual section name. If
2189 the target of the link is a format which does not have many sections (eg
2190 @code{a.out}) or has sections without names (eg the Oasys format) the
2191 link cannot be done simply. You can circumvent this problem by
2192 describing the desired input-to-output section mapping with the command
2195 @emph{Information can be lost during canonicalization.} The BFD
2196 internal canonical form of the external formats is not exhaustive; there
2197 are structures in input formats for which there is no direct
2198 representation internally. This means that the BFD back ends
2199 cannot maintain all possible data richness through the transformation
2200 between external to internal and back to external formats.
2202 This limitation is only a problem when using the linker to read one
2203 format and write another. Each BFD back end is responsible for
2204 maintaining as much data as possible, and the internal BFD
2205 canonical form has structures which are opaque to the BFD core,
2206 and exported only to the back ends. When a file is read in one format,
2207 the canonical form is generated for BFD and the linker. At the
2208 same time, the back end saves away any information which may otherwise
2209 be lost. If the data is then written back in the same format, the back
2210 end routine will be able to use the canonical form provided by the
2211 BFD core as well as the information it prepared earlier. Since
2212 there is a great deal of commonality between back ends, this mechanism
2213 is very useful. There is no information lost for this reason when
2214 linking big endian COFF to little endian COFF, or from @code{a.out} to
2215 @code{b.out}. When a mixture of formats is linked, the information is
2216 only lost from the files whose format differs from the destination.
2218 @node Mechanism, , BFD information loss, BFD
2220 The greatest potential for loss of information is when there is least
2221 overlap between the information provided by the source format, that
2222 stored by the canonical format, and the information needed by the
2223 destination format. A brief description of the canonical form may help
2224 you appreciate what kinds of data you can count on preserving across
2226 @cindex BFD canonical format
2227 @cindex internal object-file format
2231 Information on target machine architecture, particular implementation
2232 and format type are stored on a per-file basis. Other information
2233 includes a demand pageable bit and a write protected bit. Note that
2234 information like Unix magic numbers is not stored here---only the magic
2235 numbers' meaning, so a @code{ZMAGIC} file would have both the demand pageable
2236 bit and the write protected text bit set.
2238 The byte order of the target is stored on a per-file basis, so that big-
2239 and little-endian object files may be linked with one another.
2242 Each section in the input file contains the name of the section, the
2243 original address in the object file, various flags, size and alignment
2244 information and pointers into other BFD data structures.
2247 Each symbol contains a pointer to the object file which originally
2248 defined it, its name, its value, and various flag bits. When a
2249 BFD back end reads in a symbol table, the back end relocates all
2250 symbols to make them relative to the base of the section where they were
2251 defined. This ensures that each symbol points to its containing
2252 section. Each symbol also has a varying amount of hidden data to contain
2253 private data for the BFD back end. Since the symbol points to the
2254 original file, the private data format for that symbol is accessible.
2255 @code{gld} can operate on a collection of symbols of wildly different
2256 formats without problems.
2258 Normal global and simple local symbols are maintained on output, so an
2259 output file (no matter its format) will retain symbols pointing to
2260 functions and to global, static, and common variables. Some symbol
2261 information is not worth retaining; in @code{a.out} type information is
2262 stored in the symbol table as long symbol names. This information would
2263 be useless to most COFF debuggers and may be thrown away with
2264 appropriate command line switches. (The GNU debugger @code{gdb} does
2265 support @code{a.out} style debugging information in COFF).
2267 There is one word of type information within the symbol, so if the
2268 format supports symbol type information within symbols (for example COFF,
2269 IEEE, Oasys) and the type is simple enough to fit within one word
2270 (nearly everything but aggregates) the information will be preserved.
2272 @item relocation level
2273 Each canonical BFD relocation record contains a pointer to the symbol to
2274 relocate to, the offset of the data to relocate, the section the data
2275 is in and a pointer to a relocation type descriptor. Relocation is
2276 performed effectively by message passing through the relocation type
2277 descriptor and symbol pointer. It allows relocations to be performed
2278 on output data using a relocation method only available in one of the
2279 input formats. For instance, Oasys provides a byte relocation format.
2280 A relocation record requesting this relocation type would point
2281 indirectly to a routine to perform this, so the relocation may be
2282 performed on a byte being written to a COFF file, even though 68k COFF
2283 has no such relocation type.
2284 @c FIXME why specific reference to 68K above?
2287 Object formats can contain, for debugging purposes, some form of mapping
2288 between symbols, source line numbers, and addresses in the output file.
2289 These addresses have to be relocated along with the symbol information.
2290 Each symbol with an associated list of line number records points to the
2291 first record of the list. The head of a line number list consists of a
2292 pointer to the symbol, which allows divination of the address of the
2293 function whose line number is being described. The rest of the list is
2294 made up of pairs: offsets into the section and line numbers. Any format
2295 which can simply derive this information can pass it successfully
2296 between formats (COFF, IEEE and Oasys).
2299 @node Index, , BFD, Top
2305 % I think something like @colophon should be in texinfo. In the
2307 \long\def\colophon{\hbox to0pt{}\vfill
2308 \centerline{The body of this manual is set in}
2309 \centerline{\fontname\tenrm,}
2310 \centerline{with headings in {\bf\fontname\tenbf}}
2311 \centerline{and examples in {\tt\fontname\tentt}.}
2312 \centerline{{\it\fontname\tenit\/} and}
2313 \centerline{{\sl\fontname\tensl\/}}
2314 \centerline{are used for emphasis.}\vfill}
2316 % Blame: pesch@cygnus.com, 28mar91.