8 This file documents the GNU linker GLD.
10 Copyright (C) 1991 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of
13 this manual provided the copyright notice and this permission notice
14 are preserved on all copies.
17 Permission is granted to process this file through Tex and print the
18 results, provided the printed document carries copying permission
19 notice identical to this one except for the removal of this paragraph
20 (this paragraph not being relevant to the printed manual).
23 Permission is granted to copy and distribute modified versions of this
24 manual under the conditions for verbatim copying, provided also that the
25 section entitled ``GNU General Public License'' is included exactly as
26 in the original, and provided that the entire resulting derived work is
27 distributed under the terms of a permission notice identical to this
30 Permission is granted to copy and distribute translations of this manual
31 into another language, under the above conditions for modified versions,
32 except that the section entitled ``GNU General Public License'' may be
33 included in a translation approved by the author instead of in the
38 @setchapternewpage odd
39 @settitle GLD, the GNU linker
42 @subtitle The GNU linker
44 @subtitle Second Edition---@code{gld} version 2.0
46 @author Steve Chamberlain and Roland Pesch
47 @author Cygnus Support
51 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
52 \xdef\manvers{\$Revision$} % For use in headers, footers too
54 \hfill Cygnus Support\par
55 \hfill steve\@cygnus.com, pesch\@cygnus.com\par
56 \hfill {\it GLD, the GNU linker}, \manvers\par
57 \hfill \TeX{}info \texinfoversion\par
59 \global\parindent=0pt % Steve likes it this way.
62 @vskip 0pt plus 1filll
63 Copyright @copyright{} 1991 Free Software Foundation, Inc.
65 Permission is granted to make and distribute verbatim copies of
66 this manual provided the copyright notice and this permission notice
67 are preserved on all copies.
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided also that
71 the entire resulting derived work is distributed under the terms of a
72 permission notice identical to this one.
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions.
78 @c FIXME: Talk about importance of *order* of args, cmds to linker!
80 @node Top, Overview, (dir), (dir)
82 This file documents the GNU linker gld.
87 * Invocation:: Invocation
88 * Commands:: Command Language
92 --- The Detailed Node Listing ---
96 * Options:: Command Line Options
97 * Environment:: Environment Variables
101 * Scripts:: Linker Scripts
102 * Expressions:: Expressions
103 * MEMORY:: MEMORY Command
104 * SECTIONS:: SECTIONS Command
105 * Entry Point:: The Entry Point
106 * Other Commands:: Other Commands
110 * Integers:: Integers
111 * Symbols:: Symbol Names
112 * Location Counter:: The Location Counter
113 * Operators:: Operators
114 * Evaluation:: Evaluation
115 * Assignment:: Assignment: Defining Symbols
116 * Built-ins:: Built-In Functions
120 * Section Definition:: Section Definitions
121 * Section Contents:: Section Contents
122 * Section Options:: Optional Section Attributes
126 * BFD outline:: How it works: an outline of BFD
127 * BFD information loss:: Information Loss
128 * Mechanism:: Mechanism
131 @node Overview, Invocation, Top, Top
135 @cindex what is this?
136 @code{gld} combines a number of object and archive files, relocates
137 their data and ties up symbol references. Often the last step in
138 building a new compiled program to run is a call to @code{gld}.
140 @code{gld} accepts Linker Command Language files written in
141 a superset of AT&T's Link Editor Command Language syntax,
142 to provide explicit and total control over the linking process.
144 This version of @code{gld} uses the general purpose BFD libraries
145 to operate on object files. This allows @code{gld} to read, combine, and
146 write object files in many different formats---for example, COFF or
147 @code{a.out}. Different formats may be linked together to produce any
148 available kind of object file. @xref{BFD} for a list of formats
149 supported on various architectures.
151 Aside from its flexibility, the GNU linker is more helpful than other
152 linkers in providing diagnostic information. Many linkers abandon
153 execution immediately upon encountering an error; whenever possible,
154 @code{gld} continues executing, allowing you to identify other errors
155 (or, in some cases, to get an output file in spite of the error).
157 @node Invocation, Commands, Overview, Top
160 The GNU linker @code{gld} is meant to cover a broad range of situations,
161 and to be as compatible as possible with other linkers. As a result,
162 you have many choices to control its behavior through the command line,
163 and through environment variables.
166 * Options:: Command Line Options
167 * Environment:: Environment Variables
170 @node Options, Environment, Invocation, Invocation
171 @section Command Line Options
175 Here is a sketch of the options you can use on the @code{gld} command
179 gld [-o @var{output} ] @var{objfiles}@dots{}
180 [ -A@var{architecture} ] [ -b @var{input-format} ] [ -Bstatic ]
181 [ -c @var{commandfile} ] [ -d | -dc | -dp ]
182 [ -defsym @var{symbol} = @var{expression} ]
183 [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
184 @c -f was in old GNU linker, not currently in new
186 [ -format @var{input-format} ] [ -g ] [ -i ]
187 [ -l@var{ar} ] [ -L@var{searchdir} ] [ -M | -m ]
188 [ -n ] [ -noinhibit-exec ] [ -R @var{filename} ]
189 @c -N and -z were alternatives to -n in old GNU linker, not curr in new
190 @c [ -N | -n | -z ] [ -noinhibit-exec ] [ -R @var{filename} ]
191 [ -r | -Ur ] [ -S ] [ -s ] [ -T @var{commandfile} ]
192 [ -Ttext @var{textorg} ] [ -Tdata @var{dataorg} ] [ -Tbss @var{bssorg} ]
193 [ -t ] [ -u @var{sym}] [-v] [ -X ] [ -x ]
194 [ @{ @var{script} @} ]
197 This plethora of command-line options may seem intimidating, but in
198 actual practice few of them are used in any particular context.
199 @cindex standard Unix system
200 For instance, a frequent use of @code{gld} is to link standard Unix
201 object files on a standard, supported Unix system. On such a system, to
202 link a file @code{hello.o}:
204 $ gld -o output /lib/crt0.o hello.o -lc
206 This tells @code{gld} to produce a file called @code{output} as the
207 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
208 the library @code{libc.a} which will come from the standard search
211 The command-line options to @code{gld} may be specified in any order, and
212 may be repeated at will. For the most part, repeating an option with a
213 different argument will either have no further effect, or override prior
214 occurrences (those further to the left on the command line) of an
217 The exceptions---which may meaningfully be used more than once---are
218 @code{-A}, @code{-b} (or its synonym @code{-format}), @code{-defsym},
219 @code{-L}, @code{-l}, @code{-R}, and @code{-u}.
222 The list of object files to be linked together, shown as @var{objfiles},
223 may follow, precede, or be mixed in with command-line options; save that
224 an @var{objfiles} argument may not be placed between an option flag and
227 Usually the linker is invoked with at least one object file, but other
228 forms of binary input files can also be specified with @code{-l},
229 @code{-R}, and the script command language. If @emph{no} binary input
230 files at all are specified, the linker does not produce any output, and
231 issues the message @samp{No input files}.
233 Option arguments must either follow the option letter without intervening
234 whitespace, or be given as separate arguments immediately following the
235 option that requires them.
238 @item @var{objfiles}@dots{}
239 The object files @var{objfiles} to be linked.
241 @cindex architectures
243 @item -A@var{architecture}
244 In the current release of @code{gld}, this option is useful only for the
245 Intel 960 family of architectures. In that @code{gld} configuration, the
246 @var{architecture} argument is one of the two-letter names identifying
247 members of the 960 family; the option specifies the desired output
248 target, and warns of any incompatible instructions in the input files.
249 It also modifies the linker's search strategy for archive libraries, to
250 support the use of libraries specific to each particular
251 architecture, by including in the search loop names suffixed with the
252 string identifying the architecture.
254 For example, if your @code{gld} command line included @w{@samp{-ACA}} as
255 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
256 paths, and in any paths you specify with @code{-L}) for a library with
265 The first two possibilities would be considered in any event; the last
266 two are due to the use of @w{@samp{-ACA}}.
268 Future releases of @code{gld} may support similar functionality for
269 other architecture families.
271 You can meaningfully use @code{-A} more than once on a command line, if
272 an architecture family allows combination of target architectures; each
273 use will add another pair of name variants to search for when @w{@code{-l}}
276 @cindex binary input format
277 @kindex -b @var{format}
279 @item -b @var{input-format}
281 Specify the binary format for input object files that follow this option
282 on the command line. You don't usually need to specify this, as
283 @code{gld} is configured to expect as a default input format the most
284 usual format on each machine. @var{input-format} is a text string, the
285 name of a particular format supported by the BFD libraries. @xref{BFD}.
286 @code{-format @var{input-format}} has the same effect.@refill
288 You may want to use this option if you are linking files with an unusual
289 binary format. You can also use @code{-b} to switch formats explicitly (when
290 linking object files of different formats), by including
291 @code{-b @var{input-format}} before each group of object files in a
294 The default format is taken from the environment variable
295 @code{GNUTARGET}. @xref{Environment}. You can also define the input
296 format from a script, using the command @code{TARGET}.
300 This flag is accepted for command-line compatibility with the SunOS linker,
301 but has no effect on @code{gld}.
303 @kindex -c @var{cmdfile}
305 @item -c @var{commandfile}
306 Directs @code{gld} to read link commands from the file
307 @var{commandfile}. These commands will completely override @code{gld}'s
308 default link format (rather than adding to it); @var{commandfile} must
309 specify everything necessary to describe the target format.
312 You may also include a script of link commands directly in the command
313 line by bracketing it between @samp{@{} and @samp{@}} characters.
315 @cindex common allocation
322 These three options are equivalent; multiple forms are supported for
323 compatibility with other linkers. Use any of them to make @code{ld}
324 assign space to common symbols even if a relocatable output file is
325 specified (@code{-r}). The script command
326 @code{FORCE_COMMON_ALLOCATION} has the same effect.
328 @cindex symbols, from command line
329 @kindex -defsym @var{symbol}=@var{exp}
330 @item -defsym @var{symbol} = @var{expression}
331 Create a global symbol in the output file, containing the absolute
332 address given by @var{expression}. You may use this option as many
333 times as necessary to define multiple symbols in the command line. A
334 limited form of arithmetic is supported for the @var{expression} in this
335 context: you may give a hexadecimal constant or the name of an existing
336 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
337 constants or symbols. If you need more elaborate expressions, consider
338 using the linker command language from a script.
340 @cindex entry point, from command line
341 @kindex -e @var{entry}
343 Use @var{entry} as the explicit symbol for beginning execution of your
344 program, rather than the default entry point. @xref{Entry Point}, for a
345 discussion of defaults and other ways of specifying the
349 @cindex fill, from command line
350 @kindex -f @var{fill}
351 @c -f in older GNU linker, not in new
353 Sets the default fill pattern for ``holes'' in the output file to
354 the lowest two bytes of the expression specified. Holes are created
355 when you advance the location counter (@xref{Location Counter}), or when
356 there is a gap between explicitly specified section addresses
357 (@xref{Section Options}).
362 @itemx -F@var{format}
363 Some older linkers used this option throughout a compilation toolchain
364 for specifying object-file format for both input and output object
365 files. @code{gld}'s mechanisms (the @code{-b} or @code{-format} options
366 for input files, the @code{TARGET} command in linker scripts for output
367 files, the @code{GNUTARGET} environment variable) are more flexible, but
368 but it accepts (and ignores) the @code{-F} option flag for compatibility
369 with scripts written to call the old linker.
372 @item -format @var{input-format}
373 Synonym for @code{-b} @var{input-format}.
377 Accepted, but ignored; provided for compatibility with other tools.
380 @cindex incremental link
382 Perform an incremental link (same as option @code{-r}).
384 @cindex archive files, from cmd line
387 Add an archive file @var{ar} to the list of files to link. This
388 option may be used any number of times. @code{ld} will search its
389 path-list for occurrences of @code{lib@var{ar}.a} for every @var{ar}
392 @cindex search directory, from cmd line
394 @item -L@var{searchdir}
395 This command adds path @var{searchdir} to the list of paths that
396 @code{gld} will search for archive libraries. You may use this option
399 The default set of paths searched (without being specified with
400 @code{-L}) depends on what emulation mode @code{gld} is using, and in
401 some cases also on how it was configured. @xref{Environment}. The
402 paths can also be specified in a link script with the @code{SEARCH_DIR}
410 Print (to the standard output file) a link map---diagnostic information
411 about where symbols are mapped by @code{ld}, and information on global
412 common storage allocation.
415 @c -N in older GNU linker, not in new
417 @cindex read/write from cmd line
420 specifies readable and writable @code{text} and @code{data} sections. If
421 the output format supports Unix style magic numbers, the output is
422 marked as @code{OMAGIC}.
427 @cindex read-only text
429 sets the text segment to be read only, and @code{NMAGIC} is written
432 @item -noinhibit-exec
433 @cindex output file after errors
434 @kindex -noinhibit-exec
435 Normally, the linker will not produce an output file if it encounters
436 errors during the link process. With this flag, you can specify that
437 you wish the output file retained even after non-fatal errors.
439 @item -o @var{output}
440 @kindex -o @var{output}
441 @cindex naming the output file
442 @var{output} is a name for the program produced by @code{ld}; if this
443 option is not specified, the name @samp{a.out} is used by default. The
444 script command @code{OUTPUT} can also specify the output file name.
446 @item -R @var{filename}
447 @kindex -R @var{file}
448 @cindex symbol-only input
449 Read symbol names and their addresses from @var{filename}, but do not
450 relocate it or include it in the output. This allows your output file
451 to refer symbolically to absolute locations of memory defined in other
456 @cindex relocatable output
458 Generates relocatable output---i.e., generate an output file that can in
459 turn serve as input to @code{gld}. This is often called @dfn{partial
460 linking}. As a side effect, in environments that support standard Unix
461 magic numbers, this option also sets the output file's magic number to
464 If this option is not specified, an absolute file is produced. When
465 linking C++ programs, this option @emph{will not} resolve references to
466 constructors; @code{-Ur} is an alternative. @refill
468 This option does the same as @code{-i}.
472 @cindex strip debugger symbols
473 Omits debugger symbol information (but not all symbols) from the output file.
477 @cindex strip all symbols
478 Omits all symbol information from the output file.
480 @item @{ @var{script} @}
481 @kindex @{ @var{script} @}
482 @cindex scripts on command line
483 You can, if you wish, include a script of linker commands directly in
484 the command line instead of referring to it via an input file. When the
485 character @samp{@{} occurs on the command line, the linker switches to
486 interpreting the command language until the end of the list of commands
487 is reached---flagged with a closing brace @samp{@}}. Other command-line
488 options will not be recognized while parsing the script.
489 @xref{Commands} for a description of the command language.
491 @item -Tbss @var{org}
492 @kindex -Tbss @var{org}
493 @itemx -Tdata @var{org}
494 @kindex -Tdata @var{org}
495 @itemx -Ttext @var{org}
496 @kindex -Ttext @var{org}
497 @cindex segment origins, cmd line
498 Use @var{org} as the starting address for---respectively---the
499 @code{bss}, @code{data}, or the @code{text} segment of the output file.
500 @var{textorg} must be a hexadecimal integer.
502 @item -T @var{commandfile}
503 @itemx -T@var{commandfile}
504 @kindex -T @var{script}
505 Equivalent to @code{-c @var{commandfile}}; supported for compatibility with
511 @cindex input files, displaying
512 Prints names of input files as @code{ld} processes them.
516 @cindex undefined symbol
517 Forces @var{sym} to be entered in the output file as an undefined symbol.
518 This may, for example, trigger linking of additional modules from
519 standard libraries. @code{-u} may be repeated with different option
520 arguments to enter additional undefined symbols.
521 @c Nice idea, but no such command: This option is equivalent
522 @c to the @code{EXTERN} linker command.
527 For anything other than C++ programs, this option is equivalent to
528 @code{-r}: it generates relocatable output---i.e., an output file that can in
529 turn serve as input to @code{gld}. When linking C++ programs, @code{-Ur}
530 @emph{will} resolve references to constructors, unlike @code{-r}.
535 Display the version number for @code{gld}.
539 @cindex local symbols, deleting
540 @cindex L, deleting symbols beginning
541 If @code{-s} or @code{-S} is also specified, delete only local symbols
542 beginning with @samp{L}.
546 @cindex deleting local symbols
547 If @code{-s} or @code{-S} is also specified, delete all local symbols,
548 not just those beginning with @samp{L}.
551 @c -z in older GNU linker, not in new
554 @cindex read-only text
555 Specifies a read-only, demand pageable, and shared @code{text} segment.
556 If the output format supports Unix-style magic numbers, @code{-z} also
557 marks the output as @code{ZMAGIC}, the default.
559 @c why was following here?. Is it useful to say '-z -r' for
560 @c instance, or is this just a ref to other ways of setting
562 Specifying a relocatable output file (@code{-r}) will also set the magic
563 number to @code{OMAGIC}.
565 See description of @code{-N}.
570 @node Environment, , Options, Invocation
571 @section Environment Variables
573 @code{gld} always consults two environment variables: @code{GNUTARGET}
574 and @code{LDEMULATION}. Depending on the setting of the latter, other
575 environment variables may be used as well.
578 @cindex default input format
579 @code{GNUTARGET} determines the input-file object format if you don't
580 use @code{-b} (or its synonym @code{-format}). Its value should be one
581 of the BFD names for an input format (@pxref{BFD}). If there is no
582 @code{GNUTARGET} in the environment, @code{gld} uses the natural format
583 of the host. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
584 input format by examining binary input files; this method often
585 succeeds, but there are potential ambiguities, since there is no method
586 of ensuring that the magic number used to flag object-file formats is
587 unique. However, the configuration procedure for BFD on each system
588 places the conventional format for that system first in the search-list,
589 so ambiguities are resolved in favor of convention.
593 @cindex environment vars
594 @code{LDEMULATION} controls some aspects of @code{gld}'s dominant
595 personality. Although @code{gld} is flexible enough to permit its use
596 in many contexts regardless of configuration, you can use this variable
597 to make it act more like one or another older linker by default.
600 @cindex library paths, default
601 In particular, the value of @code{LDEMULATION} controls what default
602 linker script is used (thereby controlling the default input and output
603 formats; @pxref{BFD}); what default paths are searched for
604 archive libraries; and in some cases whether additional linker script
605 commands are available.
607 Here is the current set of emulations available:
610 @item LDEMULATION=gld
612 @cindex emulating old GNU linker
613 Emulate the older GNU linker. When this emulation is selected, the
614 default library search paths are
621 The default output format is set to @code{a.out-generic-big}, and the
622 default machine is the system's configured BFD default.
624 @item LDEMULATION=gld68k
627 A variant of the @code{gld} emulation; only differs in specifically
628 setting the default BFD machine as @code{m68k}.
630 @item LDEMULATION=gld960
635 Emulate the Intel port of the older @code{gld} for the i960
636 architectures. The default library search paths are taken from two
637 other environment variables, @code{G960LIB} and @code{G960BASE}. The
638 default architecture is @code{i960}. The default output format is set
639 to @code{b.out.big}, and in fact the default output file name (if
640 @code{-o} is not specified) is @code{b.out}, to reflect this variant
641 format, for this emulation.
644 This emulation can behave slightly differently depending on the setting
645 of the @code{gld} compile-time switch @code{GNU960}. If @code{gld} is
646 compiled with @code{GNU960} defined, then an additional environment
647 variable---@code{GNUTARGET}---is available; its value, if available,
648 specifies some other default output format than @code{b.out.big}.
650 @item LDEMULATION=gldm88kbcs
653 Sets the output format to @code{m88kbcs} and the architecture to
654 @code{m88k}. Default library search paths are
661 @item LDEMULATION=lnk960
664 @cindex Architectures, i960 family
665 Emulate the Intel linker @code{lnk960}. The default output format is
666 @code{coff-Intel-big}. With this emulation, @code{gld}
667 supports the additional script commands @code{HLL} and @code{SYSLIB} for
668 specification of library archives. This is the only emulation with
669 extensive support for the @code{-A} (architecture) command-line option.
670 By default, the architecture @code{CORE} is assumed, but you can choose
671 additional features from the i960 architecture family by using one of
672 the following with @code{-A} (or by using the @code{OUTPUT_ARCH} command
685 The default libraries are chosen with some attention to the architecture
686 selected; the core library @file{cg} is always included, but the library
687 @code{fpg} is also used if you've specified any of the architectures
688 @code{KA}, @code{SA}, or @code{CA}.
691 Like @code{gld960}, this emulation uses additional environment variables
692 to set the default library search paths. Also like @code{gld960}, the
693 behavior of this emulation is slightly different depending on whether
694 @code{gld} itself was compiled with @code{GNU960} defined.
699 If your @code{gld} was compiled with @code{GNU960} defined, the default
700 paths are taken from all three of @code{G960LIB}, @code{G960BASE}, and
701 @code{I960BASE}. For the first two, paths you supply are automatically
702 suffixed with @samp{/lib/libcoff}; for the last, your path is
703 automatically suffixed with @samp{/lib}.
705 If your @code{gld} was @emph{not} compiled with @code{GNU960} defined,
706 the default paths are taken from @code{I960BASE}, and @code{G960BASE} is
707 only consulted if @code{I960BASE} is undefined. In this case
708 @code{G960LIB} is not used at all.
710 @item LDEMULATION=vanilla
712 @cindex emulation, disabling
713 @cindex disabling emulation
714 This is the least specific setting for @code{gld}. You can set
715 @code{LDEMULATION=vanilla} to disable emulation of other linkers. This
716 setting makes @code{gld} take the default machine from the BFD
717 configuration on your system; @code{a.out-generic-big} is the default
718 target. No other defaults are specified.
722 @node Commands, BFD, Invocation, Top
723 @chapter Command Language
725 @cindex command files
726 The command language allows explicit control over the link process,
727 allowing complete specification of the mapping between the linker's
728 input files and its output. This includes:
737 addresses of sections
739 placement of common blocks
742 You may supply a command file (also known as a link script) to the
743 linker either explicitly through the @code{-c} option, or implicitly as
744 an ordinary file. If the linker opens a file which it cannot recognize
745 as a supported object or archive format, it tries to interpret the file
748 You can also include a script directly on the @code{gld} command line,
749 delimited by the characters @samp{@{} and @samp{@}}.
752 * Scripts:: Linker Scripts
753 * Expressions:: Expressions
754 * MEMORY:: MEMORY Command
755 * SECTIONS:: SECTIONS Command
756 * Entry Point:: The Entry Point
757 * Other Commands:: Other Commands
760 @node Scripts, Expressions, Commands, Commands
761 @section Linker Scripts
762 The @code{gld} command language is a collection of statements; some are
763 simple keywords setting a particular flag, some are used to select and
764 group input files or name output files; and two particular statement
765 types have a fundamental and pervasive impact on the linking process.
767 @cindex fundamental script commands
768 @cindex commands, fundamental
769 @cindex output file layout
770 @cindex layout of output file
771 The most fundamental command of the @code{gld} command language is the
772 @code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
773 script must have a @code{SECTIONS} command: it specifies a
774 ``picture'' of the output file's layout, in varying degrees of detail.
775 No other command is required in all cases.
777 The @code{MEMORY} command complements @code{SECTIONS} by describing the
778 available memory in the target architecture. This command is optional;
779 if you don't use a @code{MEMORY} command, @code{gld} assumes sufficient
780 memory is available in a contiguous block for all output.
784 You may include comments in linker scripts just as in C: delimited
785 by @samp{/*} and @samp{*/}. As in C, comments are syntactically
786 equivalent to whitespace.
788 @node Expressions, MEMORY, Scripts, Commands
790 @cindex expression syntax
792 Many useful commands involve arithmetic expressions. The syntax for
793 expressions in the command language is identical to that of C
794 expressions, with the following features:
797 All expressions evaluated as integers and
798 are of ``long'' or ``unsigned long'' type.
800 All constants are integers.
802 All of the C arithmetic operators are provided.
804 You may reference, define, and create global variables.
806 You may call special purpose built-in functions.
810 * Integers:: Integers
811 * Symbols:: Symbol Names
812 * Location Counter:: The Location Counter
813 * Operators:: Operators
814 * Evaluation:: Evaluation
815 * Assignment:: Assignment: Defining Symbols
816 * Built-ins:: Built-In Functions
819 @node Integers, Symbols, Expressions, Expressions
821 @cindex integer notation
822 @cindex octal integers
823 An octal integer is @samp{0} followed by zero or more of the octal
824 digits (@samp{01234567}).
829 @cindex decimal integers
830 A decimal integer starts with a non-zero digit followed by zero or
831 more digits (@samp{0123456789}).
836 @cindex hexadecimal integers
838 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
839 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
844 @cindex negative integers
845 Decimal integers have the usual values. To write a negative integer, use
846 the prefix operator @samp{-}; @pxref{Operators}.
851 @cindex scaled integers
852 @cindex K and M integer suffixes
853 @cindex M and K integer suffixes
854 @cindex suffixes for integers
855 @cindex integer suffixes
856 Additionally the suffixes @code{K} and @code{M} may be used to scale a
860 @c END TEXI2ROFF-KILL
861 @code{1024} or @code{1024*1024}
865 ${\rm 1024}$ or ${\rm 1024}^2$
867 @c END TEXI2ROFF-KILL
868 respectively. For example, the following all refer to the same quantity:@refill
876 @node Symbols, Location Counter, Integers, Expressions
877 @subsection Symbol Names
880 @cindex quoted symbol names
882 Unless quoted, symbol names start with a letter, underscore, point or
883 hyphen and may include any letters, underscores, digits, points,
884 and minus signs. Unquoted symbol names must not conflict with any
885 keywords. You can specify a symbol which contains odd characters or has
886 the same name as a keyword, by surrounding the symbol name in double quotes:
889 "with a space" = "also with a space" + 10;
892 @node Location Counter, Operators, Symbols, Expressions
893 @subsection The Location Counter
896 @cindex location counter
897 @cindex current output location
898 The special linker variable @dfn{dot} @samp{.} always contains the
899 current output location counter. Since the @code{.} always refers to
900 a location in an output section, it must always appear in an
901 expression within a @code{SECTIONS} command. The @code{.} symbol
902 may appear anywhere that an ordinary symbol is allowed in an
903 expression, but its assignments have a side effect. Assigning a value
904 to the @code{.} symbol will cause the location counter to be moved.
906 This may be used to create holes in the output section. The location
907 counter may never be moved backwards.
922 In the previous example, @code{file1} is located at the beginning of the
923 output section, then there is a 1000 byte gap. Then @code{file2}
924 appears, also with a 1000 byte gap following before @code{file3} is
925 loaded. The notation @samp{= 0x1234} specifies what data to write in
926 the gaps (@pxref{Section Options}).
928 @node Operators, Evaluation, Location Counter, Expressions
929 @subsection Operators
930 @cindex Operators for arithmetic
931 @cindex arithmetic operators
932 @cindex precedence in expressions
933 The linker recognizes the standard C set of arithmetic operators, with
934 the standard bindings and precedence levels:
937 @c END TEXI2ROFF-KILL
939 precedence associativity Operators Notes
945 5 left == != > < <= >=
951 11 right &= += -= *= /= (2)
956 (2) @xref{Assignment}
961 %"lispnarrowing" is the extra indent used generally for @example
962 \hskip\lispnarrowing\vbox{\offinterlineskip
965 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
966 height2pt&\omit&&\omit&&\omit&\cr
967 &Precedence&& Associativity &&{\rm Operators}&\cr
968 height2pt&\omit&&\omit&&\omit&\cr
970 height2pt&\omit&&\omit&&\omit&\cr
972 % '176 is tilde, '~' in tt font
973 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
977 &5&&left&&== != > < <= >=&\cr
983 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
985 height2pt&\omit&&\omit&&\omit&\cr}
990 @obeylines@parskip=0pt@parindent=0pt
991 @dag@quad Prefix operators.
992 @ddag@quad @xref{Assignment}.
995 @c END TEXI2ROFF-KILL
997 @node Evaluation, Assignment, Operators, Expressions
998 @subsection Evaluation
1000 @cindex lazy evaluation
1001 @cindex expression evaluation order
1002 The linker uses ``lazy evaluation'' for expressions; it only calculates
1003 an expression when absolutely necessary. The linker needs the value of
1004 the start address, and the lengths of memory regions, in order to do any
1005 linking at all; these values are computed as soon as possible when the
1006 linker reads in the command file. However, other values (such as symbol
1007 values) are not known or needed until after storage allocation. Such
1008 values are evaluated later, when other information (such as the sizes of
1009 output sections) is available for use in the symbol assignment
1012 @node Assignment, Built-ins, Evaluation, Expressions
1013 @subsection Assignment: Defining Symbols
1014 @cindex assignment in scripts
1015 @cindex symbol definition, scripts
1016 @cindex variables, defining
1017 You may create global symbols, and assign values (addresses) to global
1018 symbols, using any of the C assignment operators:
1021 @item @var{symbol} = @var{expression} ;
1022 @itemx @var{symbol} &= @var{expression} ;
1023 @itemx @var{symbol} += @var{expression} ;
1024 @itemx @var{symbol} -= @var{expression} ;
1025 @itemx @var{symbol} *= @var{expression} ;
1026 @itemx @var{symbol} /= @var{expression} ;
1029 Two things distinguish assignment from other operators in @code{gld}
1033 Assignment may only be used at the root of an expression;
1034 @samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
1039 A trailing semicolon is required at the end of an assignment
1043 Assignment statements may appear:
1046 as commands in their own right in a @code{gld} script; or
1048 as independent statements within a @code{SECTIONS} command; or
1050 as part of the contents of a section definition in a
1051 @code{SECTIONS} command.
1054 The first two cases are equivalent in effect---both define a symbol with
1055 an absolute address; the last case defines a symbol whose address is
1056 relative to a particular section (@pxref{SECTIONS}).
1058 @cindex absolute and relocatable symbols
1059 @cindex relocatable and absolute symbols
1060 @cindex symbols, relocatable and absolute
1061 When a linker expression is evaluated and assigned to a variable, it is
1062 given either an absolute or a relocatable type. An absolute expression
1063 type is one in which the symbol contains the value that it will have in
1064 the output file, a relocateable expression type is one in which the
1065 value is expressed as a fixed offset from the base of a section.
1067 The type of the expression is controlled by its position in the script
1068 file. A symbol assigned within a section definition is created relative
1069 to the base of the section; a symbol assigned in any other place is
1070 created as an absolute symbol. Since a symbol created within a
1071 section definition is relative to the base of the section, it
1072 will remain relocatable if relocatable output is requested. A symbol
1073 may be created with an absolute value even when assigned to within a
1074 section definition by using the absolute assignment function
1075 @code{ABSOLUTE}. For example, to create an absolute symbol whose address
1076 is the last byte of an output section named @code{.data}:
1082 _edata = ABSOLUTE(.) ;
1087 The linker tries to put off the evaluation of an assignment until all
1088 the terms in the source expression are known (@pxref{Evaluation}). For
1089 instance the sizes of sections cannot be known until after allocation,
1090 so assignments dependent upon these are not performed until after
1091 allocation. Some expressions, such as those depending upon the location
1092 counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
1093 result of an expression is required, but the value is not available,
1094 then an error results. For example, a script like the following
1097 text 9+this_isnt_constant:
1102 @kindex Non constant expression
1104 will cause the error message ``@code{Non constant expression for initial
1107 @node Built-ins, , Assignment, Expressions
1108 @subsection Built-In Functions
1109 @cindex functions in expression language
1110 The command language includes a number of special purpose built-in
1111 functions for use in link script expressions.
1113 @item ABSOLUTE(@var{exp})
1114 @kindex ABSOLUTE(@var{exp})
1115 @cindex expression, absolute
1116 returns the absolute value of the expression @var{exp}. Primarily
1117 useful to assign an absolute value to a symbol within a section
1118 definition, where symbol values are normally section-relative.
1120 @item ADDR(@var{section})
1121 @kindex ADDR(@var{section})
1122 @cindex section address
1123 returns the absolute address of the named @var{section}. Your script must
1124 previously have defined the location of that section. In the following
1125 example the @code{symbol_1} and @code{symbol_2} are assigned identical
1131 start_of_output_1 = ABSOLUTE(.);
1136 symbol_1 = ADDR(.output1);
1137 symbol_2 = start_of_output_1;
1142 @item ALIGN(@var{exp})
1143 @kindex ALIGN(@var{exp})
1144 @cindex rounding up location counter
1145 returns the result of the current location counter (@code{.}) aligned to
1146 the next @var{exp} boundary. @var{exp} must be an expression whose
1147 value is a power of two. This is equivalent to
1149 (. + @var{exp} -1) & ~(@var{exp}-1)
1152 @code{ALIGN} doesn't change the value of the location counter---it just
1153 does arithmetic on it. As an example, to align the output @code{.data}
1154 section to the next @code{0x2000} byte boundary after the preceding
1155 section and to set a variable within the section to the next
1156 @code{0x8000} boundary after the input sections:
1159 .data ALIGN(0x2000): @{
1161 variable = ALIGN(0x8000);
1166 The first use of @code{ALIGN} in this example specifies the location of
1167 a section because it is used as the optional @var{start} attribute of a
1168 section definition (@pxref{Section Options}). The second use simply
1169 defines the value of a variable.
1171 The built-in @code{NEXT} is closely related to @code{ALIGN}.
1173 @item DEFINED(@var{symbol})
1174 @kindex DEFINED(@var{symbol})
1175 @cindex symbol defaults
1176 Returns @code{1} if @var{symbol} is in the linker global symbol table and is
1177 defined, otherwise it returns @code{0}. You can use this to provide default
1178 values for symbols. For example, this command-file fragment shows how
1179 to set a global symbol @code{begin} to the first location in the
1180 @code{.text} section---but if a symbol called @code{begin} already
1181 existed, its value is preserved:
1185 begin = DEFINED(begin) ? begin : . ;
1191 @item NEXT(@var{exp})
1192 @kindex NEXT(@var{exp})
1193 @cindex unallocated address, next
1194 Returns the next unallocated address that is a multiple of @var{exp}.
1195 This command is closely related to @code{ALIGN(@var{exp})}; unless you
1196 use the @code{MEMORY} command to define discontinuous memory for the
1197 output file, the two commands are equivalent.
1199 @item SIZEOF(@var{section})
1200 @kindex SIZEOF(@var{section})
1201 @cindex section size
1202 returns the size in bytes of the named @var{section}, if the section has
1203 been allocated. In the following example the @code{symbol_1} and
1204 @code{symbol_2} are assigned identical values:
1212 symbol_1 = .end - .start;
1213 symbol_2 = SIZEOF(.output);
1218 @item SIZEOF_HEADERS
1219 @kindex SIZEOF_HEADERS
1221 @itemx sizeof_headers
1222 @kindex sizeof_headers
1223 the size in bytes of the output file's headers. You can use this number
1224 as the start address of the first section, if you choose, to facilitate
1229 @node MEMORY, SECTIONS, Expressions, Commands
1230 @section MEMORY Command
1232 @cindex regions of memory
1233 @cindex discontinuous memory
1234 @cindex allocating memory
1235 The linker's default configuration permits allocation of all memory.
1236 You can override this by using the @code{MEMORY} command. The
1237 @code{MEMORY} command describes the location and size of blocks of
1238 memory in the target. By using it carefully, you can describe which
1239 memory regions may be used by the linker, and which memory regions it
1240 must avoid. The linker does not shuffle sections to fit into the
1241 available regions, but does move the requested sections into the correct
1242 regions and issue errors when the regions become too full.
1244 Command files may contain at most one use of the @code{MEMORY}
1245 command; however, you can define as many blocks of memory within it as
1246 you wish. The syntax is:
1251 @var{name} (@var{attr}): ORIGIN = @var{origin}, LENGTH = @var{len}
1257 @cindex naming memory regions
1258 is a name used internally by the linker to refer to the region. Any
1259 symbol name may be used. The region names are stored in a separate
1260 name space, and will not conflict with symbols, filenames or section
1261 names. Use distinct names to specify multiple regions.
1263 @cindex memory region attributes
1264 is an optional list of attributes, permitted for compatibility with the
1265 AT&T linker but not used by @code{gld} beyond checking that the
1266 attribute list is valid. Valid attribute lists must be made up of the
1267 characters ``@code{LIRWX}''. If you omit the attribute list, you may
1268 omit the parentheses around it as well.
1273 is the start address of the region in physical memory. It is expressed as
1274 an expression, which must evaluate to a constant before
1275 memory allocation is performed. The keyword @code{ORIGIN} may be
1276 abbreviated to @code{org} or @code{o}.
1281 is the size in bytes of the region (an expression).
1282 The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
1285 For example, to specify that memory has two regions available for
1286 allocation---one starting at @code{0} for 256 kilobytes, and the other
1287 starting at @code{0x40000000} for four megabytes:
1292 rom : ORIGIN= 0, LENGTH = 256K
1293 ram : org= 0x40000000, l = 4M
1297 Once you have defined a region of memory named @var{mem}, you can direct
1298 specific output sections there by using a command ending in
1299 @samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
1300 Options}). If the combined output sections directed to a region are too
1301 big for the region, the linker will issue an error message.
1303 @node SECTIONS, Entry Point, MEMORY, Commands
1304 @section SECTIONS Command
1306 The @code{SECTIONS} command controls exactly where input sections are
1307 placed into output sections, their order and to which output sections
1310 You may use at most one @code{SECTIONS} command in a commands file,
1311 but you can have as many statements within it as you wish. Statements
1312 within the @code{SECTIONS} command can do one of three things:
1315 define the entry point;
1317 assign a value to a symbol;
1319 describe the placement of a named output section, and what input
1320 sections make it up.
1323 The first two possibilities---defining the entry point, and defining
1324 symbols---can also be done outside the @code{SECTIONS} command:
1325 @pxref{Entry Point}, @pxref{Assignment}. They are permitted here as
1326 well for your convenience in reading the script, so that symbols or the
1327 entry point can be defined at meaningful points in your output-file
1330 When no @code{SECTIONS} command is specified, the default action
1331 of the linker is to place each input section into an identically named
1332 output section in the order that the sections are first encountered in
1333 the input files; if all input sections are present in the first file,
1334 for example, the order of sections in the output file will match the
1335 order in the first input file.
1338 * Section Definition:: Section Definitions
1339 * Section Contents:: Section Contents
1340 * Section Options:: Optional Section Attributes
1343 @node Section Definition, Section Contents, SECTIONS, SECTIONS
1344 @subsection Section Definitions
1345 @cindex section definition
1346 The most frequently used statement in the @code{SECTIONS} command is
1347 the @dfn{section definition}, which you can use to specify the
1348 properties of an output section: its location, alignment, contents,
1349 fill pattern, and target memory region can all be specified. Most of
1350 these specifications are optional; the simplest form of a section
1359 @cindex naming output sections
1361 @var{secname} is the name of the output section, and @var{contents} a
1362 specification of what goes there---for example a list of input files or
1363 sections of input files. As you might assume, the whitespace shown is
1364 optional; you do need the colon @samp{:} and the braces @samp{@{@}},
1367 @var{secname} must meet the constraints of your output format. In
1368 formats which only support a limited number of sections, such as
1369 @code{a.out}, the name must be one of the names supported by the format
1370 (@code{a.out}, for example, allows only @code{.text}, @code{.data} or
1371 @code{.bss}). If the output format supports any number of sections, but
1372 with numbers and not names (as is the case for Oasys), the name should be
1373 supplied as a quoted numeric string. A section name may consist of any
1374 sequence characters, but any name which does not conform to the standard
1375 @code{gld} symbol name syntax must be quoted.
1377 @node Section Contents, Section Options, Section Definition, SECTIONS
1378 @subsection Section Contents
1379 @cindex contents of a section
1380 In a section definition, you can specify the contents of an output section by
1381 listing particular object files; by listing particular input-file
1382 sections; or a combination of the two. You can also place arbitrary
1383 data in the section, and define symbols relative to the beginning of the
1386 The @var{contents} of a section definition may include any of the
1387 following kinds of statement. You can include as many of these as you
1388 like in a single section definition, separated from one another by
1392 @item @var{filename}
1393 @kindex @var{filename}
1394 @cindex input files, section defn
1395 @cindex files, including in output sections
1396 You may simply name a particular input file to be placed in the current
1397 output section; @emph{all} sections from that file are placed in the
1398 current section definition. To specify a list of particular files by
1401 .data: @{ afile.o bfile.o cfile.o @}
1404 The example also illustrates that multiple statements can be included in
1405 the contents of a section definition, since each filename is a separate
1408 If the file name has already been mentioned in another section
1409 definition, with an explicit section name list, then only those sections
1410 which have not yet been allocated are used.
1412 @item @var{filename}( @var{section} )
1413 @itemx @var{filename}( @var{section}, @var{section}, @dots{} )
1414 @itemx @var{filename}( @var{section} @var{section} @dots{} )
1415 @kindex @var{filename}(@var{section})
1416 @cindex files and sections, section defn
1417 You can name one or more sections from your input files, for
1418 insertion in the current output section. If you wish to specify a list
1419 of input-file sections inside the parentheses, you may separate the
1420 section names by either commas or whitespace.
1422 @item * (@var{section})
1423 @itemx * (@var{section}, @var{section}, @dots{})
1424 @itemx * (@var{section} @var{section} @dots{}
1425 @cindex input sections to output section
1426 @kindex *(@var{section})
1427 Instead of explicitly naming particular input files in a link control
1428 script, you can refer to @emph{all} files from the @code{gld} command
1429 line: use @samp{*} instead of a particular filename before the
1430 parenthesized input-file section list.
1432 For example, to copy sections @code{1} through @code{4} from a Oasys file
1433 into the @code{.text} section of an @code{a.out} file, and sections @code{13}
1434 and @code{14} into the @code{.data} section:
1447 If you have already explicitly included some files by name, @samp{*}
1448 refers to all @emph{remaining} files---those whose places in the output
1449 file have not yet been defined.
1451 @item [ @var{section} ]
1452 @itemx [ @var{section}, @var{section}, @dots{} ]
1453 @itemx [ @var{section} @var{section} @dots{} ]
1454 @kindex [ @var{sections} ]
1455 This is an alternate notation to specify named sections from all
1456 unallocated input files; its effect is exactly the same as that of
1457 @samp{* (@var{section}@dots{})}
1459 @item @var{filename}@code{( COMMON )}
1462 @cindex uninitialized data
1463 @cindex commons in output
1464 Specify where in your output file to place uninitialized data
1465 with this notation. @code{[COMMON]} by itself refers to all
1466 uninitialized data from all input files (so far as it is not yet
1467 allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
1468 from a particular file. Both are special cases of the general
1469 mechanisms for specifying where to place input-file sections:
1470 @code{gld} permits you to refer to uninitialized data as if it
1471 were in an input-file section named @code{COMMON}, regardless of the
1472 input file's format.
1475 For example, the following command script arranges the output file into
1476 three consecutive sections, named @code{.text}, @code{.data}, and
1477 @code{.bss}, taking the input for each from the correspondingly named
1478 sections of all the input files:
1481 .text: @{ *(.text) @}
1482 .data: @{ *(.data) @}
1483 .bss: @{ *(.bss) [COMMON] @}
1487 The following example reads all of the sections from file @code{all.o}
1488 and places them at the start of output section @code{outputa} which
1489 starts at location @code{0x10000}. All of section @code{.input1} from
1490 file @code{foo.o} follows immediately, in the same output section. All
1491 of section @code{.input2} from @code{foo.o} goes into output section
1492 @code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
1493 All of the remaining @code{.input1} and @code{.input2} sections from any
1494 files are written to output section @code{outputc}.
1516 There are still more kinds of statements permitted in the contents of
1517 output section definitions. The foregoing statements permitted you to
1518 arrange, in your output file, data originating from your input files.
1519 You can also place data directly in an output section from the link
1520 command script. Most of these additional statements involve
1521 expressions; @pxref{Expressions}. Although these statements are shown
1522 separately here for ease of presentation, no such segregation is needed
1523 within a section definition in the @code{SECTIONS} command; you can
1524 intermix them freely with any of the statements we've just described.
1527 @item CREATE_OBJECT_SYMBOLS
1528 @kindex CREATE_OBJECT_SYMBOLS
1529 @cindex input filename symbols
1530 @cindex filename symbols
1531 instructs the linker to create a symbol for each input file
1532 in the current section, set with the address of the first byte of
1533 data written from the input file. For instance, with @code{a.out}
1534 files it is conventional to have a symbol for each input file. You can
1535 accomplish this by defining the output @code{.text} section as follows:
1540 CREATE_OBJECT_SYMBOLS
1542 _etext = ALIGN(0x2000);
1548 If @code{objsym} is a file containing this script, and @code{a.o},
1549 @code{b.o}, @code{c.o}, and @code{d.o} are four input files with
1550 contents like the following---
1560 @samp{gld -M sample a.o b.o c.o d.o} would create a map like this,
1561 containing symbols matching the object file names:
1563 00000000 A __DYNAMIC
1566 00002020 T _afunction
1569 00002038 T _bfunction
1572 00002050 T _cfunction
1575 00002068 T _dfunction
1585 @item @var{symbol} = @var{expression} ;
1586 @kindex @var{symbol} = @var{expression} ;
1587 @itemx @var{symbol} @var{f}= @var{expression} ;
1588 @kindex @var{symbol} @var{f}= @var{expression} ;
1589 @var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
1590 refers to any of the operators @code{&= += -= *= /=} which combine
1591 arithmetic and assignment.
1593 @cindex assignment, in section defn
1594 When you assign a value to a symbol within a particular section
1595 definition, the value is relative to the beginning of the section
1596 (@pxref{Assignment}). If you write
1601 .data: @{ @dots{} rel = 14 ; @dots{} @}
1602 abs2 = 14 + ADDR(.data);
1606 @c FIXME: Try above example!
1608 @code{abs} and @var{rel} do not have the same value; @code{rel} has the
1609 same value as @code{abs2}.
1611 @item BYTE(@var{expression})
1612 @kindex BYTE(@var{expression})
1613 @itemx SHORT(@var{expression})
1614 @kindex SHORT(@var{expression})
1615 @itemx LONG(@var{expression})
1616 @kindex LONG(@var{expression})
1617 @cindex direct output
1618 By including one of these three statements in a section definition, you
1619 can explicitly place one, two, or four bytes (respectively) at the
1620 current address of that section. Multiple-byte quantities are
1621 represented in whatever byte order is appropriate for the output file
1622 format (@pxref{BFD}).
1624 @item FILL(@var{expression})
1625 @kindex FILL(@var{expression})
1626 @cindex holes, filling
1627 @cindex unspecified memory
1628 Specifies the ``fill pattern'' for the current section. Any otherwise
1629 unspecified regions of memory within the section (for example, regions
1630 you skip over by assigning a new value to the location counter @samp{.})
1631 are filled with the two least significant bytes from the
1632 @var{expression} argument. A @code{FILL} statement covers memory
1633 locations @emph{after} the point it occurs in the section definition; by
1634 including more than one @code{FILL} statement, you can have different
1635 fill patterns in different parts of an output section.
1638 @node Section Options, , Section Contents, SECTIONS
1639 @subsection Optional Section Attributes
1640 @cindex section defn, full syntax
1641 Here is the full syntax of a section definition, including all the
1647 @var{secname} @var{start} BLOCK(@var{align}) : @{ @var{contents} @} =@var{fill} >@var{region}
1652 @var{secname} and @var{contents} are required. @xref{Section
1653 Definition}, and @pxref{Section Contents} for details on @var{contents}.
1654 The remaining elements---@var{start}, @code{BLOCK(@var{align)}},
1655 @code{=@var{fill}}, and @code{>@var{region}}---are all optional.
1659 @cindex start address, section
1660 @cindex section start
1661 @cindex section address
1662 You can force the output section to be loaded at a specified address by
1663 specifying @var{start} immediately following the section name.
1664 @var{start} can be represented as any expression. The following
1665 example generates section @var{output} at location
1670 output 0x40000000: @{
1677 @item BLOCK(@var{align})
1678 @kindex BLOCK(@var{align})
1679 @cindex section alignment
1680 @cindex aligning sections
1681 You can include @code{BLOCK()} specification to advance the location of
1682 the location counter @code{.} prior to the beginning of the section, so
1683 that the section will begin at the specified alignment. @var{align} is
1688 @cindex section fill pattern
1689 @cindex fill pattern, entire section
1690 You may use any expression to specify @var{fill}. Including
1691 @code{=@var{fill}} in a section definition specifies the initial fill
1692 value for that section. Any unallocated holes in the current output
1693 section when written to the output file will be filled with the two
1694 least significant bytes of the value, repeated as necessary. You can
1695 also change the fill value with a @code{FILL} statement in the
1696 @var{contents} of a section definition.
1699 @kindex >@var{region}
1700 @cindex section, assigning to memory region
1701 @cindex memory regions and sections
1702 Assign this section to a previously defined region of memory.
1707 @node Entry Point, Other Commands, SECTIONS, Commands
1708 @section The Entry Point
1709 @kindex ENTRY(@var{symbol})
1710 @cindex start of execution
1711 @cindex first instruction
1712 The linker command language includes a command specifically for
1713 defining the first executable instruction in an output file (its
1714 @dfn{entry point}). Its argument is a symbol name:
1719 Like symbol assignments, the @code{ENTRY} command may be placed either
1720 as an independent command in the command file, or among the section
1721 definitions within the @code{SECTIONS} command---whatever makes the most
1722 sense for your layout.
1724 @cindex entry point, defaults
1725 @code{ENTRY} is only one of several ways of choosing the entry point.
1726 You may indicate it in any of the following ways (shown in descending
1727 order of priority: methods higher in the list override methods lower down).
1730 the @code{-e} @var{entry} command-line option;
1732 the @code{ENTRY(@var{symbol}} command in a linker control script;
1734 the value of the symbol @code{start}, if present;
1736 the value of the symbol @code{_main}, if present;
1738 the address of the first byte of the @code{.text} section, if present;
1740 The address @code{0}.
1743 For example, you can use these rules to generate an entry point with an
1744 assignment statement: if no symbol @code{start} is defined within your
1745 input files, you can simply define it, assigning it an appropriate
1752 The example shows an absolute address, but you can use any expression.
1753 For example, if your input object files use some other symbol-name
1754 convention for the entry point, you can just assign the value of
1755 whatever symbol contains the start address to @code{start}:
1757 start = other_symbol;
1760 @node Other Commands, , Entry Point, Commands
1761 @section Other Commands
1762 The command language includes a number of other commands that you can
1763 use for specialized purposes. They are similar in purpose to
1764 command-line options.
1771 These keywords were used in some older linkers to request a particular
1772 math subroutine library. @code{gld} doesn't use the keywords, assuming
1773 instead that any necessary subroutines are in libraries specified using
1774 the general mechanisms for linking to archives; but to permit the use of
1775 scripts that were written for the older linkers, the keywords
1776 @code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
1778 @item FORCE_COMMON_ALLOCATION
1779 @kindex FORCE_COMMON_ALLOCATION
1780 @cindex common allocation
1781 This command has the same effect as the @code{-d} command-line option:
1782 to make @code{ld} assign space to common symbols even if a relocatable
1783 output file is specified (@code{-r}).
1785 @item HLL ( @var{file}, @var{file}, @dots{} )
1786 @kindex HLL ( @var{files} )
1787 @itemx HLL ( @var{file} @var{file} @dots{} )
1789 Include ``high-level libraries'' or archives as input files in the link.
1790 Using @code{HLL(@var{file}} in a linker script is equivalent to
1791 including @code{-l}@var{file} on the command line.
1793 @cindex @code{lnk960} command @code{HLL}
1794 The @code{HLL} command is only supported when @code{gld} emulates
1795 @code{lnk960}, as specified by the @code{LDEMULATION} environment
1798 @item INPUT ( @var{file}, @var{file}, @dots{} )
1799 @kindex INPUT ( @var{files} )
1800 @itemx INPUT ( @var{file} @var{file} @dots{} )
1801 @cindex binary input files
1802 Use this command to include binary input files in the link, without
1803 including them in a particular section definition. Files specified this
1804 way are treated identically to object files listed on the command line.
1807 @item MAP ( @var{name} )
1808 @kindex MAP ( @var{name} )
1809 @c MAP(...) appears to look for an F in the arg, ignoring all other
1810 @c chars; if it finds one, it sets "map_option_f" to true. But nothing
1811 @c checks map_option_f. Apparently a stub for the future...
1814 @item OUTPUT ( @var{filename} )
1815 @kindex OUTPUT ( @var{filename} )
1816 @cindex naming the output file
1817 Name the link output file @var{filename}. The effect of
1818 @code{OUTPUT(@var{filename})} is identical to the effect of
1819 @w{@code{-o @var{filename}}}, and whichever is encountered last will
1820 control the name actually used to name the output file. In particular,
1821 you can use this command to supply a default output-file name other than
1824 @item OUTPUT_ARCH ( @var{bfdname} )
1825 @kindex OUTPUT_ARCH ( @var{bfdname} )
1826 @cindex machine architecture, output
1827 Specify a particular output machine architecture, with one of the names
1828 used by the BFD back-end routines (@pxref{BFD}). This command is often
1829 unnecessary; the architecture is most often set implicitly by either the
1830 system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
1833 @item OUTPUT_FORMAT ( @var{bfdname} )
1834 @kindex OUTPUT_FORMAT ( @var{bfdname} )
1835 @cindex format, output file
1836 Specify a particular output format, with one of the names used by the
1837 BFD back-end routines (@pxref{BFD}). This selection will only affect
1838 the output file; the related command @code{TARGET} affects primarily
1841 @item SEARCH_DIR ( @var{path} )
1842 @kindex SEARCH_DIR ( @var{path} )
1843 @cindex path for libraries
1844 @cindex search path, libraries
1845 Add @var{path} to the list of paths where @code{gld} looks for
1846 archive libraries. @code{SEARCH_DIR(@var{path})} has the same
1847 effect as @code{-L@var{path})} on the command line.
1849 @item STARTUP ( @var{filename} )
1850 @kindex STARTUP ( @var{filename} )
1851 @cindex first input file
1852 Ensure that @var{filename} is the first input file used in the link
1855 @item SYSLIB ( @var{file}, @var{file}, @dots{} )
1856 @kindex SYSLIB ( @var{file}, @var{file}, @dots{} )
1857 @itemx SYSLIB ( @var{file} @var{file} @dots{} )
1858 Use the named @var{file}s as binary input files, searching for them in
1859 the same list of paths as archives.
1861 @cindex @code{lnk960} command @code{SYSLIB}
1862 The @code{SYSLIB} command is only supported when @code{gld} emulates
1863 @code{lnk960}, as specified by the @code{LDEMULATION} environment
1866 @item TARGET ( @var{format} )
1867 @cindex input file format
1868 @kindex TARGET ( @var{format} )
1869 Change the input-file object code format (like the command-line option
1870 @code{-b} or its synonym @code{-format}). The argument @var{format} is
1871 one of the strings used by BFD to name binary formats. In the current
1872 @code{gld} implementation, if @code{TARGET} is specified but
1873 @code{OUTPUT_FORMAT} is not, the last @code{TARGET} argument is also
1874 used as the default format for the @code{gld} output file.
1878 If you don't use the @code{TARGET} command, @code{gld} uses the value of
1879 the environment variable @code{GNUTARGET}, if available, to select the
1880 output file format. If that variable is also absent, @code{gld} uses
1881 the default format configured for your machine in the BFD libraries.
1885 @node BFD, Index, Commands, Top
1889 @cindex object file management
1890 The linker accesses object and archive files using the BFD libraries.
1891 These libraries allow the linker to use the same routines to operate on
1892 object files whatever the object file format. A different object file
1893 format can be supported simply by creating a new BFD back end and adding
1894 it to the library. BFD supports the following combinations of
1895 architectures (row labels below) and object formats (column headings):
1896 @cindex formats available
1897 @cindex architectures available
1900 @c END TEXI2ROFF-KILL
1904 | | |a.out-generic-little
1905 | | | |a.out-generic-big
1908 | | | | | | |coff-Intel-little
1909 | | | | | | | |coff-Intel-big
1910 | | | | | | | | |b.out.little
1911 | | | | | | | | | |b.out.big
1913 m68k|**|**| | | |**| | | |
1914 vax|**|**| | | |**| | | |
1915 i960|**|**| | | |**|**|**|**|**
1916 a29k|**|**|**|**| |**| | | |
1917 sparc|**|**|**|**| |**| | | |
1918 mips|**|**| | | |**| | | |
1919 i386|**|**|**|**| |**| | | |
1920 ns32k|**|**| | | |**| | | |
1921 tahoe|**|**| | | |**| | | |
1922 i860|**|**| | | |**| | | |
1923 romp|**|**| | | |**| | | |
1924 alliant|**|**| | | |**| | | |
1925 convex|**|**| | | |**| | | |
1926 m88k|**|**| | |**|**| | | |
1927 pyramid|**|**| | | |**| | | |
1928 H8/300|**|**| | | |**| | | |
1934 \def\sqbull{\vrule height12pt width 10pt depth 4pt}
1936 \vbox{\offinterlineskip
1938 {\strut\hfil #\ &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em
1939 &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#&\hskip .5em #\hskip .5em &\vrule#\cr
1940 &&\multispan{20}\quad\vbox{\hrule}\cr
1941 &&\multispan{20}\quad\code{ieee}\hfil\cr
1942 && &&\multispan{18}\quad\code{oasys}\hfil\cr
1943 && && &&\multispan{16}\quad\code{a.out-generic-little}\hfil\cr
1944 && && && &&\multispan{14}\quad\code{a.out-generic-big}\hfil\cr
1945 && && && && &&\multispan{12}\quad\code{m88kbcs}\hfil\cr
1946 && && && && && &&\multispan{10}\quad\code{srec}\hfil\cr
1947 && && && && && && &&\multispan8\quad\code{coff-Intel-little}\hfil\cr
1948 && && && && && && && &&\multispan6\quad\code{coff-Intel-big}\hfil\cr
1949 && && && && && && && &&
1950 &&\multispan4\quad\code{b.out.little}\hfil \cr
1951 && && && && && && && && && &&\multispan2\quad\code{b.out.big}\hidewidth\cr
1952 \code{m68k}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1953 \code{vax}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1954 \code{i960}&&\sqbull&&\sqbull&& && && &&\sqbull&&\sqbull&&\sqbull&&\sqbull&&\sqbull &\cr
1955 \code{a29k}&&\sqbull&&\sqbull&&\sqbull&&\sqbull&& &&\sqbull&& && && && &\cr
1956 \code{sparc}&&\sqbull&&\sqbull&&\sqbull&&\sqbull&& &&\sqbull&& && && && &\cr
1957 \code{mips}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1958 \code{i386}&&\sqbull&&\sqbull&&\sqbull&&\sqbull&& &&\sqbull&& && && && &\cr
1959 \code{ns32k}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1960 \code{tahoe}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1961 \code{i860}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1962 \code{romp}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1963 \code{alliant}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1964 \code{convex}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1965 \code{m88k}&&\sqbull&&\sqbull&& && &&\sqbull&&\sqbull&& && && && &\cr
1966 \code{pyramid}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1967 \code{H8/300}&&\sqbull&&\sqbull&& && && &&\sqbull&& && && && &\cr
1970 @c END TEXI2ROFF-KILL
1972 @cindex BFD requirements
1973 @cindex requirements for BFD
1974 As with most implementations, BFD is a compromise between
1975 several conflicting requirements. The major factor influencing
1976 BFD design was efficiency: any time used converting between
1977 formats is time which would not have been spent had BFD not
1978 been involved. This is partly offset by abstraction payback; since
1979 BFD simplifies applications and back ends, more time and care
1980 may be spent optimizing algorithms for a greater speed.
1982 One minor artifact of the BFD solution which you should bear in
1983 mind is the potential for information loss. There are two places where
1984 useful information can be lost using the BFD mechanism; during
1985 conversion and during output. @xref{BFD information loss}.
1988 * BFD outline:: How it works: an outline of BFD
1989 * BFD information loss:: Information Loss
1990 * Mechanism:: Mechanism
1993 @node BFD outline, BFD information loss, BFD, BFD
1994 @section How it works: an outline of BFD
1995 @cindex opening object files
1996 When an object file is opened, BFD subroutines automatically
1997 determine the format of the input object file, and build a descriptor in
1998 memory with pointers to routines that will be used to access elements of
1999 the object file's data structures.
2001 As different information from the the object files is required
2002 BFD reads from different sections of the file and processes them.
2003 For example a very common operation for the linker is processing symbol
2004 tables. Each BFD back end provides a routine for converting
2005 between the object file's representation of symbols and an internal
2006 canonical format. When the linker asks for the symbol table of an object
2007 file, it calls through the memory pointer to the relevant BFD
2008 back end routine which reads and converts the table into a canonical
2009 form. The linker then operates upon the common form. When the link is
2010 finished and the linker writes the symbol table of the output file,
2011 another BFD back end routine is called which takes the newly
2012 created symbol table and converts it into the chosen output format.
2014 @node BFD information loss, Mechanism, BFD outline, BFD
2015 @section Information Loss
2016 @emph{Information can be lost during output.} The output formats
2017 supported by BFD do not provide identical facilities, and
2018 information which may be described in one form has nowhere to go in
2019 another format. One example of this is alignment information in
2020 @code{b.out}. There is nowhere in an @code{a.out} format file to store
2021 alignment information on the contained data, so when a file is linked
2022 from @code{b.out} and an @code{a.out} image is produced, alignment
2023 information will not propagate to the output file. (The linker will
2024 still use the alignment information internally, so the link is performed
2027 Another example is COFF section names. COFF files may contain an
2028 unlimited number of sections, each one with a textual section name. If
2029 the target of the link is a format which does not have many sections (eg
2030 @code{a.out}) or has sections without names (eg the Oasys format) the
2031 link cannot be done simply. You can circumvent this problem by
2032 describing the desired input-to-output section mapping with the command
2035 @emph{Information can be lost during canonicalization.} The BFD
2036 internal canonical form of the external formats is not exhaustive; there
2037 are structures in input formats for which there is no direct
2038 representation internally. This means that the BFD back ends
2039 cannot maintain all possible data richness through the transformation
2040 between external to internal and back to external formats.
2042 This limitation is only a problem when using the linker to read one
2043 format and write another. Each BFD back end is responsible for
2044 maintaining as much data as possible, and the internal BFD
2045 canonical form has structures which are opaque to the BFD core,
2046 and exported only to the back ends. When a file is read in one format,
2047 the canonical form is generated for BFD and the linker. At the
2048 same time, the back end saves away any information which may otherwise
2049 be lost. If the data is then written back in the same format, the back
2050 end routine will be able to use the canonical form provided by the
2051 BFD core as well as the information it prepared earlier. Since
2052 there is a great deal of commonality between back ends, this mechanism
2053 is very useful. There is no information lost for this reason when
2054 linking big endian COFF to little endian COFF, or from @code{a.out} to
2055 @code{b.out}. When a mixture of formats is linked, the information is
2056 only lost from the files whose format differs from the destination.
2058 @node Mechanism, , BFD information loss, BFD
2060 The greatest potential for loss of information is when there is least
2061 overlap between the information provided by the source format, that
2062 stored by the canonical format, and the information needed by the
2063 destination format. A brief description of the canonical form may help
2064 you appreciate what kinds of data you can count on preserving across
2066 @cindex BFD canonical format
2067 @cindex internal object-file format
2071 Information on target machine architecture, particular implementation
2072 and format type are stored on a per-file basis. Other information
2073 includes a demand pageable bit and a write protected bit. Note that
2074 information like Unix magic numbers is not stored here---only the magic
2075 numbers' meaning, so a @code{ZMAGIC} file would have both the demand pageable
2076 bit and the write protected text bit set.
2078 The byte order of the target is stored on a per-file basis, so that big-
2079 and little-endian object files may be linked with one another.
2082 Each section in the input file contains the name of the section, the
2083 original address in the object file, various flags, size and alignment
2084 information and pointers into other BFD data structures.
2087 Each symbol contains a pointer to the object file which originally
2088 defined it, its name, its value, and various flag bits. When a
2089 BFD back end reads in a symbol table, the back end relocates all
2090 symbols to make them relative to the base of the section where they were
2091 defined. This ensures that each symbol points to its containing
2092 section. Each symbol also has a varying amount of hidden data to contain
2093 private data for the BFD back end. Since the symbol points to the
2094 original file, the private data format for that symbol is accessible.
2095 @code{gld} can operate on a collection of symbols of wildly different
2096 formats without problems.
2098 Normal global and simple local symbols are maintained on output, so an
2099 output file (no matter its format) will retain symbols pointing to
2100 functions and to global, static, and common variables. Some symbol
2101 information is not worth retaining; in @code{a.out} type information is
2102 stored in the symbol table as long symbol names. This information would
2103 be useless to most COFF debuggers and may be thrown away with
2104 appropriate command line switches. (The GNU debugger @code{gdb} does
2105 support @code{a.out} style debugging information in COFF).
2107 There is one word of type information within the symbol, so if the
2108 format supports symbol type information within symbols (for example COFF,
2109 IEEE, Oasys) and the type is simple enough to fit within one word
2110 (nearly everything but aggregates) the information will be preserved.
2112 @item relocation level
2113 Each canonical BFD relocation record contains a pointer to the symbol to
2114 relocate to, the offset of the data to relocate, the section the data
2115 is in and a pointer to a relocation type descriptor. Relocation is
2116 performed effectively by message passing through the relocation type
2117 descriptor and symbol pointer. It allows relocations to be performed
2118 on output data using a relocation method only available in one of the
2119 input formats. For instance, Oasys provides a byte relocation format.
2120 A relocation record requesting this relocation type would point
2121 indirectly to a routine to perform this, so the relocation may be
2122 performed on a byte being written to a COFF file, even though 68k COFF
2123 has no such relocation type.
2126 Object formats can contain, for debugging purposes, some form of mapping
2127 between symbols, source line numbers, and addresses in the output file.
2128 These addresses have to be relocated along with the symbol information.
2129 Each symbol with an associated list of line number records points to the
2130 first record of the list. The head of a line number list consists of a
2131 pointer to the symbol, which allows divination of the address of the
2132 function whose line number is being described. The rest of the list is
2133 made up of pairs: offsets into the section and line numbers. Any format
2134 which can simply derive this information can pass it successfully
2135 between formats (COFF, IEEE and Oasys).
2138 @node Index, , BFD, Top
2144 % I think something like @colophon should be in texinfo. In the
2146 \long\def\colophon{\hbox to0pt{}\vfill
2147 \centerline{The body of this manual is set in}
2148 \centerline{\fontname\tenrm,}
2149 \centerline{with headings in {\bf\fontname\tenbf}}
2150 \centerline{and examples in {\tt\fontname\tentt}.}
2151 \centerline{{\it\fontname\tenit\/} and}
2152 \centerline{{\sl\fontname\tensl\/}}
2153 \centerline{are used for emphasis.}\vfill}
2155 % Blame: pesch@cygnus.com, 28mar91.