4 @include configdoc.texi
5 @c (configdoc.texi is generated by the Makefile)
12 * Ld: (ld). The GNU linker.
18 This file documents the @sc{gnu} linker LD.
20 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
22 Permission is granted to make and distribute verbatim copies of
23 this manual provided the copyright notice and this permission notice
24 are preserved on all copies.
26 Permission is granted to copy and distribute modified versions of this
27 manual under the conditions for verbatim copying, provided also that
28 the entire resulting derived work is distributed under the terms of a
29 permission notice identical to this one.
31 Permission is granted to copy and distribute translations of this manual
32 into another language, under the above conditions for modified versions.
35 Permission is granted to process this file through Tex and print the
36 results, provided the printed document carries copying permission
37 notice identical to this one except for the removal of this paragraph
38 (this paragraph not being relevant to the printed manual).
44 @setchapternewpage odd
45 @settitle Using LD, the GNU linker
48 @subtitle The GNU linker
50 @subtitle @code{ld} version 2
52 @author Steve Chamberlain
53 @author Ian Lance Taylor
54 @author Cygnus Solutions
59 \hfill Cygnus Solutions\par
60 \hfill ian\@cygnus.com, doc\@cygnus.com\par
61 \hfill {\it Using LD, the GNU linker}\par
62 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
64 \global\parindent=0pt % Steve likes it this way.
67 @vskip 0pt plus 1filll
68 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
70 Permission is granted to make and distribute verbatim copies of
71 this manual provided the copyright notice and this permission notice
72 are preserved on all copies.
74 Permission is granted to copy and distribute modified versions of this
75 manual under the conditions for verbatim copying, provided also that
76 the entire resulting derived work is distributed under the terms of a
77 permission notice identical to this one.
79 Permission is granted to copy and distribute translations of this manual
80 into another language, under the above conditions for modified versions.
83 @c FIXME: Talk about importance of *order* of args, cmds to linker!
88 This file documents the @sc{gnu} linker ld.
92 * Invocation:: Invocation
93 * Scripts:: Linker Scripts
95 * Machine Dependent:: Machine Dependent Features
99 * H8/300:: ld and the H8/300
102 * Hitachi:: ld and other Hitachi micros
105 * i960:: ld and the Intel 960 family
108 @ifclear SingleFormat
111 @c Following blank line required for remaining bug in makeinfo conds/menus
113 * Reporting Bugs:: Reporting Bugs
114 * MRI:: MRI Compatible Script Files
122 @cindex @sc{gnu} linker
123 @cindex what is this?
124 @code{ld} combines a number of object and archive files, relocates
125 their data and ties up symbol references. Usually the last step in
126 compiling a program is to run @code{ld}.
128 @code{ld} accepts Linker Command Language files written in
129 a superset of AT&T's Link Editor Command Language syntax,
130 to provide explicit and total control over the linking process.
132 @ifclear SingleFormat
133 This version of @code{ld} uses the general purpose BFD libraries
134 to operate on object files. This allows @code{ld} to read, combine, and
135 write object files in many different formats---for example, COFF or
136 @code{a.out}. Different formats may be linked together to produce any
137 available kind of object file. @xref{BFD}, for more information.
140 Aside from its flexibility, the @sc{gnu} linker is more helpful than other
141 linkers in providing diagnostic information. Many linkers abandon
142 execution immediately upon encountering an error; whenever possible,
143 @code{ld} continues executing, allowing you to identify other errors
144 (or, in some cases, to get an output file in spite of the error).
149 The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations,
150 and to be as compatible as possible with other linkers. As a result,
151 you have many choices to control its behavior.
155 * Options:: Command Line Options
156 * Environment:: Environment Variables
160 @section Command Line Options
165 The linker supports a plethora of command-line options, but in actual
166 practice few of them are used in any particular context.
167 @cindex standard Unix system
168 For instance, a frequent use of @code{ld} is to link standard Unix
169 object files on a standard, supported Unix system. On such a system, to
170 link a file @code{hello.o}:
173 ld -o @var{output} /lib/crt0.o hello.o -lc
176 This tells @code{ld} to produce a file called @var{output} as the
177 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
178 the library @code{libc.a}, which will come from the standard search
179 directories. (See the discussion of the @samp{-l} option below.)
181 The command-line options to @code{ld} may be specified in any order, and
182 may be repeated at will. Repeating most options with a different
183 argument will either have no further effect, or override prior
184 occurrences (those further to the left on the command line) of that
185 option. Options which may be meaningfully specified more than once are
186 noted in the descriptions below.
189 Non-option arguments are objects files which are to be linked together.
190 They may follow, precede, or be mixed in with command-line options,
191 except that an object file argument may not be placed between an option
194 Usually the linker is invoked with at least one object file, but you can
195 specify other forms of binary input files using @samp{-l}, @samp{-R},
196 and the script command language. If @emph{no} binary input files at all
197 are specified, the linker does not produce any output, and issues the
198 message @samp{No input files}.
200 If the linker can not recognize the format of an object file, it will
201 assume that it is a linker script. A script specified in this way
202 augments the main linker script used for the link (either the default
203 linker script or the one specified by using @samp{-T}). This feature
204 permits the linker to link against a file which appears to be an object
205 or an archive, but actually merely defines some symbol values, or uses
206 @code{INPUT} or @code{GROUP} to load other objects. Note that
207 specifying a script in this way should only be used to augment the main
208 linker script; if you want to use some command that logically can only
209 appear once, such as the @code{SECTIONS} or @code{MEMORY} command, you
210 must replace the default linker script using the @samp{-T} option.
213 For options whose names are a single letter,
214 option arguments must either follow the option letter without intervening
215 whitespace, or be given as separate arguments immediately following the
216 option that requires them.
218 For options whose names are multiple letters, either one dash or two can
219 precede the option name; for example, @samp{--oformat} and
220 @samp{--oformat} are equivalent. Arguments to multiple-letter options
221 must either be separated from the option name by an equals sign, or be
222 given as separate arguments immediately following the option that
223 requires them. For example, @samp{--oformat srec} and
224 @samp{--oformat=srec} are equivalent. Unique abbreviations of the names
225 of multiple-letter options are accepted.
228 @kindex -a@var{keyword}
229 @item -a@var{keyword}
230 This option is supported for HP/UX compatibility. The @var{keyword}
231 argument must be one of the strings @samp{archive}, @samp{shared}, or
232 @samp{default}. @samp{-aarchive} is functionally equivalent to
233 @samp{-Bstatic}, and the other two keywords are functionally equivalent
234 to @samp{-Bdynamic}. This option may be used any number of times.
237 @cindex architectures
239 @item -A@var{architecture}
240 @kindex --architecture=@var{arch}
241 @itemx --architecture=@var{architecture}
242 In the current release of @code{ld}, this option is useful only for the
243 Intel 960 family of architectures. In that @code{ld} configuration, the
244 @var{architecture} argument identifies the particular architecture in
245 the 960 family, enabling some safeguards and modifying the
246 archive-library search path. @xref{i960,,@code{ld} and the Intel 960
247 family}, for details.
249 Future releases of @code{ld} may support similar functionality for
250 other architecture families.
253 @ifclear SingleFormat
254 @cindex binary input format
255 @kindex -b @var{format}
256 @kindex --format=@var{format}
259 @item -b @var{input-format}
260 @itemx --format=@var{input-format}
261 @code{ld} may be configured to support more than one kind of object
262 file. If your @code{ld} is configured this way, you can use the
263 @samp{-b} option to specify the binary format for input object files
264 that follow this option on the command line. Even when @code{ld} is
265 configured to support alternative object formats, you don't usually need
266 to specify this, as @code{ld} should be configured to expect as a
267 default input format the most usual format on each machine.
268 @var{input-format} is a text string, the name of a particular format
269 supported by the BFD libraries. (You can list the available binary
270 formats with @samp{objdump -i}.)
273 You may want to use this option if you are linking files with an unusual
274 binary format. You can also use @samp{-b} to switch formats explicitly (when
275 linking object files of different formats), by including
276 @samp{-b @var{input-format}} before each group of object files in a
279 The default format is taken from the environment variable
284 You can also define the input format from a script, using the command
285 @code{TARGET}; see @ref{Format Commands}.
288 @kindex -c @var{MRI-cmdfile}
289 @kindex --mri-script=@var{MRI-cmdfile}
290 @cindex compatibility, MRI
291 @item -c @var{MRI-commandfile}
292 @itemx --mri-script=@var{MRI-commandfile}
293 For compatibility with linkers produced by MRI, @code{ld} accepts script
294 files written in an alternate, restricted command language, described in
295 @ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
296 the option @samp{-c}; use the @samp{-T} option to run linker
297 scripts written in the general-purpose @code{ld} scripting language.
298 If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
299 specified by any @samp{-L} options.
301 @cindex common allocation
308 These three options are equivalent; multiple forms are supported for
309 compatibility with other linkers. They assign space to common symbols
310 even if a relocatable output file is specified (with @samp{-r}). The
311 script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
312 @xref{Miscellaneous Commands}.
314 @cindex entry point, from command line
315 @kindex -e @var{entry}
316 @kindex --entry=@var{entry}
318 @itemx --entry=@var{entry}
319 Use @var{entry} as the explicit symbol for beginning execution of your
320 program, rather than the default entry point. @xref{Entry Point}, for a
321 discussion of defaults and other ways of specifying the
324 @cindex dynamic symbol table
326 @kindex --export-dynamic
328 @itemx --export-dynamic
329 When creating a dynamically linked executable, add all symbols to the
330 dynamic symbol table. The dynamic symbol table is the set of symbols
331 which are visible from dynamic objects at run time.
333 If you do not use this option, the dynamic symbol table will normally
334 contain only those symbols which are referenced by some dynamic object
335 mentioned in the link.
337 If you use @code{dlopen} to load a dynamic object which needs to refer
338 back to the symbols defined by the program, rather than some other
339 dynamic object, then you will probably need to use this option when
340 linking the program itself.
345 @itemx --auxiliary @var{name}
346 When creating an ELF shared object, set the internal DT_AUXILIARY field
347 to the specified name. This tells the dynamic linker that the symbol
348 table of the shared object should be used as an auxiliary filter on the
349 symbol table of the shared object @var{name}.
351 If you later link a program against this filter object, then, when you
352 run the program, the dynamic linker will see the DT_AUXILIARY field. If
353 the dynamic linker resolves any symbols from the filter object, it will
354 first check whether there is a definition in the shared object
355 @var{name}. If there is one, it will be used instead of the definition
356 in the filter object. The shared object @var{name} need not exist.
357 Thus the shared object @var{name} may be used to provide an alternative
358 implementation of certain functions, perhaps for debugging or for
359 machine specific performance.
361 This option may be specified more than once. The DT_AUXILIARY entries
362 will be created in the order in which they appear on the command line.
367 @itemx --filter @var{name}
368 When creating an ELF shared object, set the internal DT_FILTER field to
369 the specified name. This tells the dynamic linker that the symbol table
370 of the shared object which is being created should be used as a filter
371 on the symbol table of the shared object @var{name}.
373 If you later link a program against this filter object, then, when you
374 run the program, the dynamic linker will see the DT_FILTER field. The
375 dynamic linker will resolve symbols according to the symbol table of the
376 filter object as usual, but it will actually link to the definitions
377 found in the shared object @var{name}. Thus the filter object can be
378 used to select a subset of the symbols provided by the object
381 Some older linkers used the @code{-F} option throughout a compilation
382 toolchain for specifying object-file format for both input and output
383 object files. The @sc{gnu} linker uses other mechanisms for this
384 purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the
385 @code{TARGET} command in linker scripts, and the @code{GNUTARGET}
386 environment variable. The @sc{gnu} linker will ignore the @code{-F}
387 option when not creating an ELF shared object.
389 @kindex --force-exe-suffix
390 @item --force-exe-suffix
391 Make sure that an output file has a .exe suffix.
393 If a successfully built fully linked output file does not have a
394 @code{.exe} or @code{.dll} suffix, this option forces the linker to copy
395 the output file to one of the same name with a @code{.exe} suffix. This
396 option is useful when using unmodified Unix makefiles on a Microsoft
397 Windows host, since some versions of Windows won't run an image unless
398 it ends in a @code{.exe} suffix.
402 Ignored. Provided for compatibility with other tools.
408 @itemx --gpsize=@var{value}
409 Set the maximum size of objects to be optimized using the GP register to
410 @var{size}. This is only meaningful for object file formats such as
411 MIPS ECOFF which supports putting large and small objects into different
412 sections. This is ignored for other object file formats.
414 @cindex runtime library name
416 @kindex -soname=@var{name}
418 @itemx -soname=@var{name}
419 When creating an ELF shared object, set the internal DT_SONAME field to
420 the specified name. When an executable is linked with a shared object
421 which has a DT_SONAME field, then when the executable is run the dynamic
422 linker will attempt to load the shared object specified by the DT_SONAME
423 field rather than the using the file name given to the linker.
426 @cindex incremental link
428 Perform an incremental link (same as option @samp{-r}).
430 @cindex archive files, from cmd line
431 @kindex -l@var{archive}
432 @kindex --library=@var{archive}
433 @item -l@var{archive}
434 @itemx --library=@var{archive}
435 Add archive file @var{archive} to the list of files to link. This
436 option may be used any number of times. @code{ld} will search its
437 path-list for occurrences of @code{lib@var{archive}.a} for every
438 @var{archive} specified.
440 On systems which support shared libraries, @code{ld} may also search for
441 libraries with extensions other than @code{.a}. Specifically, on ELF
442 and SunOS systems, @code{ld} will search a directory for a library with
443 an extension of @code{.so} before searching for one with an extension of
444 @code{.a}. By convention, a @code{.so} extension indicates a shared
447 The linker will search an archive only once, at the location where it is
448 specified on the command line. If the archive defines a symbol which
449 was undefined in some object which appeared before the archive on the
450 command line, the linker will include the appropriate file(s) from the
451 archive. However, an undefined symbol in an object appearing later on
452 the command line will not cause the linker to search the archive again.
454 See the @code{-(} option for a way to force the linker to search
455 archives multiple times.
457 You may list the same archive multiple times on the command line.
460 This type of archive searching is standard for Unix linkers. However,
461 if you are using @code{ld} on AIX, note that it is different from the
462 behaviour of the AIX linker.
465 @cindex search directory, from cmd line
467 @kindex --library-path=@var{dir}
468 @item -L@var{searchdir}
469 @itemx --library-path=@var{searchdir}
470 Add path @var{searchdir} to the list of paths that @code{ld} will search
471 for archive libraries and @code{ld} control scripts. You may use this
472 option any number of times. The directories are searched in the order
473 in which they are specified on the command line. Directories specified
474 on the command line are searched before the default directories. All
475 @code{-L} options apply to all @code{-l} options, regardless of the
476 order in which the options appear.
479 The default set of paths searched (without being specified with
480 @samp{-L}) depends on which emulation mode @code{ld} is using, and in
481 some cases also on how it was configured. @xref{Environment}.
484 The paths can also be specified in a link script with the
485 @code{SEARCH_DIR} command. Directories specified this way are searched
486 at the point in which the linker script appears in the command line.
489 @kindex -m @var{emulation}
490 @item -m@var{emulation}
491 Emulate the @var{emulation} linker. You can list the available
492 emulations with the @samp{--verbose} or @samp{-V} options.
494 If the @samp{-m} option is not used, the emulation is taken from the
495 @code{LDEMULATION} environment variable, if that is defined.
497 Otherwise, the default emulation depends upon how the linker was
505 Print a link map to the standard output. A link map provides
506 information about the link, including the following:
510 Where object files and symbols are mapped into memory.
512 How common symbols are allocated.
514 All archive members included in the link, with a mention of the symbol
515 which caused the archive member to be brought in.
519 @cindex read-only text
524 Set the text segment to be read only, and mark the output as
525 @code{NMAGIC} if possible.
529 @cindex read/write from cmd line
533 Set the text and data sections to be readable and writable. Also, do
534 not page-align the data segment. If the output format supports Unix
535 style magic numbers, mark the output as @code{OMAGIC}.
537 @kindex -o @var{output}
538 @kindex --output=@var{output}
539 @cindex naming the output file
540 @item -o @var{output}
541 @itemx --output=@var{output}
542 Use @var{output} as the name for the program produced by @code{ld}; if this
543 option is not specified, the name @file{a.out} is used by default. The
544 script command @code{OUTPUT} can also specify the output file name.
547 @cindex relocatable output
549 @kindex --relocateable
551 @itemx --relocateable
552 Generate relocatable output---i.e., generate an output file that can in
553 turn serve as input to @code{ld}. This is often called @dfn{partial
554 linking}. As a side effect, in environments that support standard Unix
555 magic numbers, this option also sets the output file's magic number to
558 If this option is not specified, an absolute file is produced. When
559 linking C++ programs, this option @emph{will not} resolve references to
560 constructors; to do that, use @samp{-Ur}.
562 This option does the same thing as @samp{-i}.
564 @kindex -R @var{file}
565 @kindex --just-symbols=@var{file}
566 @cindex symbol-only input
567 @item -R @var{filename}
568 @itemx --just-symbols=@var{filename}
569 Read symbol names and their addresses from @var{filename}, but do not
570 relocate it or include it in the output. This allows your output file
571 to refer symbolically to absolute locations of memory defined in other
572 programs. You may use this option more than once.
574 For compatibility with other ELF linkers, if the @code{-R} option is
575 followed by a directory name, rather than a file name, it is treated as
576 the @code{-rpath} option.
580 @cindex strip all symbols
583 Omit all symbol information from the output file.
586 @kindex --strip-debug
587 @cindex strip debugger symbols
590 Omit debugger symbol information (but not all symbols) from the output file.
594 @cindex input files, displaying
597 Print the names of the input files as @code{ld} processes them.
599 @kindex -T @var{script}
600 @kindex --script=@var{script}
602 @item -T @var{scriptfile}
603 @itemx --script=@var{scriptfile}
604 Use @var{scriptfile} as the linker script. This script replaces
605 @code{ld}'s default linker script (rather than adding to it), so
606 @var{commandfile} must specify everything necessary to describe the
607 output file. You must use this option if you want to use a command
608 which can only appear once in a linker script, such as the
609 @code{SECTIONS} or @code{MEMORY} command. @xref{Scripts}. If
610 @var{scriptfile} does not exist in the current directory, @code{ld}
611 looks for it in the directories specified by any preceding @samp{-L}
612 options. Multiple @samp{-T} options accumulate.
614 @kindex -u @var{symbol}
615 @kindex --undefined=@var{symbol}
616 @cindex undefined symbol
617 @item -u @var{symbol}
618 @itemx --undefined=@var{symbol}
619 Force @var{symbol} to be entered in the output file as an undefined symbol.
620 Doing this may, for example, trigger linking of additional modules from
621 standard libraries. @samp{-u} may be repeated with different option
622 arguments to enter additional undefined symbols.
623 @c Nice idea, but no such command: This option is equivalent
624 @c to the @code{EXTERN} linker command.
633 Display the version number for @code{ld}. The @code{-V} option also
634 lists the supported emulations.
637 @kindex --discard-all
638 @cindex deleting local symbols
641 Delete all local symbols.
644 @kindex --discard-locals
645 @cindex local symbols, deleting
646 @cindex L, deleting symbols beginning
648 @itemx --discard-locals
649 Delete all temporary local symbols. For most targets, this is all local
650 symbols whose names begin with @samp{L}.
652 @kindex -y @var{symbol}
653 @kindex --trace-symbol=@var{symbol}
654 @cindex symbol tracing
655 @item -y @var{symbol}
656 @itemx --trace-symbol=@var{symbol}
657 Print the name of each linked file in which @var{symbol} appears. This
658 option may be given any number of times. On many systems it is necessary
659 to prepend an underscore.
661 This option is useful when you have an undefined symbol in your link but
662 don't know where the reference is coming from.
664 @kindex -Y @var{path}
666 Add @var{path} to the default library search path. This option exists
667 for Solaris compatibility.
669 @kindex -z @var{keyword}
670 @item -z @var{keyword}
671 This option is ignored for Solaris compatibility.
674 @cindex groups of archives
675 @item -( @var{archives} -)
676 @itemx --start-group @var{archives} --end-group
677 The @var{archives} should be a list of archive files. They may be
678 either explicit file names, or @samp{-l} options.
680 The specified archives are searched repeatedly until no new undefined
681 references are created. Normally, an archive is searched only once in
682 the order that it is specified on the command line. If a symbol in that
683 archive is needed to resolve an undefined symbol referred to by an
684 object in an archive that appears later on the command line, the linker
685 would not be able to resolve that reference. By grouping the archives,
686 they all be searched repeatedly until all possible references are
689 Using this option has a significant performance cost. It is best to use
690 it only when there are unavoidable circular references between two or
693 @kindex -assert @var{keyword}
694 @item -assert @var{keyword}
695 This option is ignored for SunOS compatibility.
703 Link against dynamic libraries. This is only meaningful on platforms
704 for which shared libraries are supported. This option is normally the
705 default on such platforms. The different variants of this option are
706 for compatibility with various systems. You may use this option
707 multiple times on the command line: it affects library searching for
708 @code{-l} options which follow it.
718 Do not link against shared libraries. This is only meaningful on
719 platforms for which shared libraries are supported. The different
720 variants of this option are for compatibility with various systems. You
721 may use this option multiple times on the command line: it affects
722 library searching for @code{-l} options which follow it.
726 When creating a shared library, bind references to global symbols to the
727 definition within the shared library, if any. Normally, it is possible
728 for a program linked against a shared library to override the definition
729 within the shared library. This option is only meaningful on ELF
730 platforms which support shared libraries.
732 @cindex cross reference table
735 Output a cross reference table. If a linker map file is being
736 generated, the cross reference table is printed to the map file.
737 Otherwise, it is printed on the standard output.
739 The format of the table is intentionally simple, so that it may be
740 easily processed by a script if necessary. The symbols are printed out,
741 sorted by name. For each symbol, a list of file names is given. If the
742 symbol is defined, the first file listed is the location of the
743 definition. The remaining files contain references to the symbol.
745 @cindex symbols, from command line
746 @kindex --defsym @var{symbol}=@var{exp}
747 @item --defsym @var{symbol}=@var{expression}
748 Create a global symbol in the output file, containing the absolute
749 address given by @var{expression}. You may use this option as many
750 times as necessary to define multiple symbols in the command line. A
751 limited form of arithmetic is supported for the @var{expression} in this
752 context: you may give a hexadecimal constant or the name of an existing
753 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
754 constants or symbols. If you need more elaborate expressions, consider
755 using the linker command language from a script (@pxref{Assignments,,
756 Assignment: Symbol Definitions}). @emph{Note:} there should be no white
757 space between @var{symbol}, the equals sign (``@key{=}''), and
760 @cindex dynamic linker, from command line
761 @kindex --dynamic-linker @var{file}
762 @item --dynamic-linker @var{file}
763 Set the name of the dynamic linker. This is only meaningful when
764 generating dynamically linked ELF executables. The default dynamic
765 linker is normally correct; don't use this unless you know what you are
768 @cindex big-endian objects
772 Link big-endian objects. This affects the default output format.
774 @cindex little-endian objects
777 Link little-endian objects. This affects the default output format.
779 @cindex MIPS embedded PIC code
780 @kindex --embedded-relocs
781 @item --embedded-relocs
782 This option is only meaningful when linking MIPS embedded PIC code,
783 generated by the -membedded-pic option to the @sc{gnu} compiler and
784 assembler. It causes the linker to create a table which may be used at
785 runtime to relocate any data which was statically initialized to pointer
786 values. See the code in testsuite/ld-empic for details.
792 Print a summary of the command-line options on the standard output and exit.
795 @item -Map @var{mapfile}
796 Print a link map to the file @var{mapfile}. See the description of the
797 @samp{-M} option, above.
800 @kindex --no-keep-memory
801 @item --no-keep-memory
802 @code{ld} normally optimizes for speed over memory usage by caching the
803 symbol tables of input files in memory. This option tells @code{ld} to
804 instead optimize for memory usage, by rereading the symbol tables as
805 necessary. This may be required if @code{ld} runs out of memory space
806 while linking a large executable.
808 @kindex --no-warn-mismatch
809 @item --no-warn-mismatch
810 Normally @code{ld} will give an error if you try to link together input
811 files that are mismatched for some reason, perhaps because they have
812 been compiled for different processors or for different endiannesses.
813 This option tells @code{ld} that it should silently permit such possible
814 errors. This option should only be used with care, in cases when you
815 have taken some special action that ensures that the linker errors are
818 @kindex --no-whole-archive
819 @item --no-whole-archive
820 Turn off the effect of the @code{--whole-archive} option for subsequent
823 @cindex output file after errors
824 @kindex --noinhibit-exec
825 @item --noinhibit-exec
826 Retain the executable output file whenever it is still usable.
827 Normally, the linker will not produce an output file if it encounters
828 errors during the link process; it exits without writing an output file
829 when it issues any error whatsoever.
831 @ifclear SingleFormat
833 @item --oformat @var{output-format}
834 @code{ld} may be configured to support more than one kind of object
835 file. If your @code{ld} is configured this way, you can use the
836 @samp{--oformat} option to specify the binary format for the output
837 object file. Even when @code{ld} is configured to support alternative
838 object formats, you don't usually need to specify this, as @code{ld}
839 should be configured to produce as a default output format the most
840 usual format on each machine. @var{output-format} is a text string, the
841 name of a particular format supported by the BFD libraries. (You can
842 list the available binary formats with @samp{objdump -i}.) The script
843 command @code{OUTPUT_FORMAT} can also specify the output format, but
844 this option overrides it. @xref{BFD}.
849 This option is ignored for Linux compatibility.
853 This option is ignored for SVR4 compatibility.
856 @cindex synthesizing linker
857 @cindex relaxing addressing modes
859 An option with machine dependent effects.
861 This option is only supported on a few targets.
864 @xref{H8/300,,@code{ld} and the H8/300}.
867 @xref{i960,, @code{ld} and the Intel 960 family}.
870 On some platforms, the @samp{--relax} option performs global
871 optimizations that become possible when the linker resolves addressing
872 in the program, such as relaxing address modes and synthesizing new
873 instructions in the output object file.
876 On platforms where this is not supported, @samp{--relax} is accepted,
880 @cindex retaining specified symbols
881 @cindex stripping all but some symbols
882 @cindex symbols, retaining selectively
883 @item --retain-symbols-file @var{filename}
884 Retain @emph{only} the symbols listed in the file @var{filename},
885 discarding all others. @var{filename} is simply a flat file, with one
886 symbol name per line. This option is especially useful in environments
890 where a large global symbol table is accumulated gradually, to conserve
893 @samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
894 or symbols needed for relocations.
896 You may only specify @samp{--retain-symbols-file} once in the command
897 line. It overrides @samp{-s} and @samp{-S}.
900 @item -rpath @var{dir}
901 @cindex runtime library search path
903 Add a directory to the runtime library search path. This is used when
904 linking an ELF executable with shared objects. All @code{-rpath}
905 arguments are concatenated and passed to the runtime linker, which uses
906 them to locate shared objects at runtime. The @code{-rpath} option is
907 also used when locating shared objects which are needed by shared
908 objects explicitly included in the link; see the description of the
909 @code{-rpath-link} option. If @code{-rpath} is not used when linking an
910 ELF executable, the contents of the environment variable
911 @code{LD_RUN_PATH} will be used if it is defined.
913 The @code{-rpath} option may also be used on SunOS. By default, on
914 SunOS, the linker will form a runtime search patch out of all the
915 @code{-L} options it is given. If a @code{-rpath} option is used, the
916 runtime search path will be formed exclusively using the @code{-rpath}
917 options, ignoring the @code{-L} options. This can be useful when using
918 gcc, which adds many @code{-L} options which may be on NFS mounted
921 For compatibility with other ELF linkers, if the @code{-R} option is
922 followed by a directory name, rather than a file name, it is treated as
923 the @code{-rpath} option.
927 @cindex link-time runtime library search path
929 @item -rpath-link @var{DIR}
930 When using ELF or SunOS, one shared library may require another. This
931 happens when an @code{ld -shared} link includes a shared library as one
934 When the linker encounters such a dependency when doing a non-shared,
935 non-relocatable link, it will automatically try to locate the required
936 shared library and include it in the link, if it is not included
937 explicitly. In such a case, the @code{-rpath-link} option
938 specifies the first set of directories to search. The
939 @code{-rpath-link} option may specify a sequence of directory names
940 either by specifying a list of names separated by colons, or by
941 appearing multiple times.
943 The linker uses the following search paths to locate required shared
947 Any directories specified by @code{-rpath-link} options.
949 Any directories specified by @code{-rpath} options. The difference
950 between @code{-rpath} and @code{-rpath-link} is that directories
951 specified by @code{-rpath} options are included in the executable and
952 used at runtime, whereas the @code{-rpath-link} option is only effective
955 On an ELF system, if the @code{-rpath} and @code{rpath-link} options
956 were not used, search the contents of the environment variable
959 On SunOS, if the @code{-rpath} option was not used, search any
960 directories specified using @code{-L} options.
962 For a native linker, the contents of the environment variable
963 @code{LD_LIBRARY_PATH}.
965 The default directories, normally @file{/lib} and @file{/usr/lib}.
968 If the required shared library is not found, the linker will issue a
969 warning and continue with the link.
976 @cindex shared libraries
977 Create a shared library. This is currently only supported on ELF, XCOFF
978 and SunOS platforms. On SunOS, the linker will automatically create a
979 shared library if the @code{-e} option is not used and there are
980 undefined symbols in the link.
983 @kindex --sort-common
984 This option tells @code{ld} to sort the common symbols by size when it
985 places them in the appropriate output sections. First come all the one
986 byte symbols, then all the two bytes, then all the four bytes, and then
987 everything else. This is to prevent gaps between symbols due to
988 alignment constraints.
990 @kindex --split-by-file
991 @item --split-by-file
992 Similar to @code{--split-by-reloc} but creates a new output section for
995 @kindex --split-by-reloc
996 @item --split-by-reloc @var{count}
997 Trys to creates extra sections in the output file so that no single
998 output section in the file contains more than @var{count} relocations.
999 This is useful when generating huge relocatable for downloading into
1000 certain real time kernels with the COFF object file format; since COFF
1001 cannot represent more than 65535 relocations in a single section. Note
1002 that this will fail to work with object file formats which do not
1003 support arbitrary sections. The linker will not split up individual
1004 input sections for redistribution, so if a single input section contains
1005 more than @var{count} relocations one output section will contain that
1010 Compute and display statistics about the operation of the linker, such
1011 as execution time and memory usage.
1013 @kindex --traditional-format
1014 @cindex traditional format
1015 @item --traditional-format
1016 For some targets, the output of @code{ld} is different in some ways from
1017 the output of some existing linker. This switch requests @code{ld} to
1018 use the traditional format instead.
1021 For example, on SunOS, @code{ld} combines duplicate entries in the
1022 symbol string table. This can reduce the size of an output file with
1023 full debugging information by over 30 percent. Unfortunately, the SunOS
1024 @code{dbx} program can not read the resulting program (@code{gdb} has no
1025 trouble). The @samp{--traditional-format} switch tells @code{ld} to not
1026 combine duplicate entries.
1028 @kindex -Tbss @var{org}
1029 @kindex -Tdata @var{org}
1030 @kindex -Ttext @var{org}
1031 @cindex segment origins, cmd line
1032 @item -Tbss @var{org}
1033 @itemx -Tdata @var{org}
1034 @itemx -Ttext @var{org}
1035 Use @var{org} as the starting address for---respectively---the
1036 @code{bss}, @code{data}, or the @code{text} segment of the output file.
1037 @var{org} must be a single hexadecimal integer;
1038 for compatibility with other linkers, you may omit the leading
1039 @samp{0x} usually associated with hexadecimal values.
1042 @cindex constructors
1044 For anything other than C++ programs, this option is equivalent to
1045 @samp{-r}: it generates relocatable output---i.e., an output file that can in
1046 turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
1047 @emph{does} resolve references to constructors, unlike @samp{-r}.
1048 It does not work to use @samp{-Ur} on files that were themselves linked
1049 with @samp{-Ur}; once the constructor table has been built, it cannot
1050 be added to. Use @samp{-Ur} only for the last partial link, and
1051 @samp{-r} for the others.
1056 Display the version number for @code{ld} and list the linker emulations
1057 supported. Display which input files can and cannot be opened. Display
1058 the linker script if using a default builtin script.
1060 @kindex --version-script=@var{version-scriptfile}
1061 @cindex version script, symbol versions
1062 @itemx --version-script=@var{version-scriptfile}
1063 Specify the name of a version script to the linker. This is typically
1064 used when creating shared libraries to specify additional information
1065 about the version heirarchy for the library being created. This option
1066 is only meaningful on ELF platforms which support shared libraries.
1069 @kindex --warn-comon
1070 @cindex warnings, on combining symbols
1071 @cindex combining symbols, warnings on
1073 Warn when a common symbol is combined with another common symbol or with
1074 a symbol definition. Unix linkers allow this somewhat sloppy practice,
1075 but linkers on some other operating systems do not. This option allows
1076 you to find potential problems from combining global symbols.
1077 Unfortunately, some C libraries use this practice, so you may get some
1078 warnings about symbols in the libraries as well as in your programs.
1080 There are three kinds of global symbols, illustrated here by C examples:
1084 A definition, which goes in the initialized data section of the output
1088 An undefined reference, which does not allocate space.
1089 There must be either a definition or a common symbol for the
1093 A common symbol. If there are only (one or more) common symbols for a
1094 variable, it goes in the uninitialized data area of the output file.
1095 The linker merges multiple common symbols for the same variable into a
1096 single symbol. If they are of different sizes, it picks the largest
1097 size. The linker turns a common symbol into a declaration, if there is
1098 a definition of the same variable.
1101 The @samp{--warn-common} option can produce five kinds of warnings.
1102 Each warning consists of a pair of lines: the first describes the symbol
1103 just encountered, and the second describes the previous symbol
1104 encountered with the same name. One or both of the two symbols will be
1109 Turning a common symbol into a reference, because there is already a
1110 definition for the symbol.
1112 @var{file}(@var{section}): warning: common of `@var{symbol}'
1113 overridden by definition
1114 @var{file}(@var{section}): warning: defined here
1118 Turning a common symbol into a reference, because a later definition for
1119 the symbol is encountered. This is the same as the previous case,
1120 except that the symbols are encountered in a different order.
1122 @var{file}(@var{section}): warning: definition of `@var{symbol}'
1124 @var{file}(@var{section}): warning: common is here
1128 Merging a common symbol with a previous same-sized common symbol.
1130 @var{file}(@var{section}): warning: multiple common
1132 @var{file}(@var{section}): warning: previous common is here
1136 Merging a common symbol with a previous larger common symbol.
1138 @var{file}(@var{section}): warning: common of `@var{symbol}'
1139 overridden by larger common
1140 @var{file}(@var{section}): warning: larger common is here
1144 Merging a common symbol with a previous smaller common symbol. This is
1145 the same as the previous case, except that the symbols are
1146 encountered in a different order.
1148 @var{file}(@var{section}): warning: common of `@var{symbol}'
1149 overriding smaller common
1150 @var{file}(@var{section}): warning: smaller common is here
1154 @kindex --warn-constructors
1155 @item --warn-constructors
1156 Warn if any global constructors are used. This is only useful for a few
1157 object file formats. For formats like COFF or ELF, the linker can not
1158 detect the use of global constructors.
1160 @kindex --warn-multiple-gp
1161 @item --warn-multiple-gp
1162 Warn if multiple global pointer values are required in the output file.
1163 This is only meaningful for certain processors, such as the Alpha.
1164 Specifically, some processors put large-valued constants in a special
1165 section. A special register (the global pointer) points into the middle
1166 of this section, so that constants can be loaded efficiently via a
1167 base-register relative addressing mode. Since the offset in
1168 base-register relative mode is fixed and relatively small (e.g., 16
1169 bits), this limits the maximum size of the constant pool. Thus, in
1170 large programs, it is often necessary to use multiple global pointer
1171 values in order to be able to address all possible constants. This
1172 option causes a warning to be issued whenever this case occurs.
1175 @cindex warnings, on undefined symbols
1176 @cindex undefined symbols, warnings on
1178 Only warn once for each undefined symbol, rather than once per module
1181 @kindex --warn-section-align
1182 @cindex warnings, on section alignment
1183 @cindex section alignment, warnings on
1184 @item --warn-section-align
1185 Warn if the address of an output section is changed because of
1186 alignment. Typically, the alignment will be set by an input section.
1187 The address will only be changed if it not explicitly specified; that
1188 is, if the @code{SECTIONS} command does not specify a start address for
1189 the section (@pxref{SECTIONS}).
1191 @kindex --whole-archive
1192 @cindex including an entire archive
1193 @item --whole-archive
1194 For each archive mentioned on the command line after the
1195 @code{--whole-archive} option, include every object file in the archive
1196 in the link, rather than searching the archive for the required object
1197 files. This is normally used to turn an archive file into a shared
1198 library, forcing every object to be included in the resulting shared
1199 library. This option may be used more than once.
1202 @item --wrap @var{symbol}
1203 Use a wrapper function for @var{symbol}. Any undefined reference to
1204 @var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
1205 undefined reference to @code{__real_@var{symbol}} will be resolved to
1208 This can be used to provide a wrapper for a system function. The
1209 wrapper function should be called @code{__wrap_@var{symbol}}. If it
1210 wishes to call the system function, it should call
1211 @code{__real_@var{symbol}}.
1213 Here is a trivial example:
1217 __wrap_malloc (int c)
1219 printf ("malloc called with %ld\n", c);
1220 return __real_malloc (c);
1224 If you link other code with this file using @code{--wrap malloc}, then
1225 all calls to @code{malloc} will call the function @code{__wrap_malloc}
1226 instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
1227 call the real @code{malloc} function.
1229 You may wish to provide a @code{__real_malloc} function as well, so that
1230 links without the @code{--wrap} option will succeed. If you do this,
1231 you should not put the definition of @code{__real_malloc} in the same
1232 file as @code{__wrap_malloc}; if you do, the assembler may resolve the
1233 call before the linker has a chance to wrap it to @code{malloc}.
1239 @section Environment Variables
1241 You can change the behavior of @code{ld} with the environment variables
1242 @code{GNUTARGET} and @code{LDEMULATION}.
1245 @cindex default input format
1246 @code{GNUTARGET} determines the input-file object format if you don't
1247 use @samp{-b} (or its synonym @samp{--format}). Its value should be one
1248 of the BFD names for an input format (@pxref{BFD}). If there is no
1249 @code{GNUTARGET} in the environment, @code{ld} uses the natural format
1250 of the target. If @code{GNUTARGET} is set to @code{default} then BFD
1251 attempts to discover the input format by examining binary input files;
1252 this method often succeeds, but there are potential ambiguities, since
1253 there is no method of ensuring that the magic number used to specify
1254 object-file formats is unique. However, the configuration procedure for
1255 BFD on each system places the conventional format for that system first
1256 in the search-list, so ambiguities are resolved in favor of convention.
1259 @cindex default emulation
1260 @cindex emulation, default
1261 @code{LDEMULATION} determines the default emulation if you don't use the
1262 @samp{-m} option. The emulation can affect various aspects of linker
1263 behaviour, particularly the default linker script. You can list the
1264 available emulations with the @samp{--verbose} or @samp{-V} options. If
1265 the @samp{-m} option is not used, and the @code{LDEMULATION} environment
1266 variable is not defined, the default emulation depends upon how the
1267 linker was configured.
1271 @chapter Linker Scripts
1274 @cindex linker scripts
1275 @cindex command files
1276 Every link is controlled by a @dfn{linker script}. This script is
1277 written in the linker command language.
1279 The main purpose of the linker script is to describe how the sections in
1280 the input files should be mapped into the output file, and to control
1281 the memory layout of the output file. Most linker scripts do nothing
1282 more than this. However, when necessary, the linker script can also
1283 direct the linker to perform many other operations, using the commands
1286 The linker always uses a linker script. If you do not supply one
1287 yourself, the linker will use a default script that is compiled into the
1288 linker executable. You can use the @samp{--verbose} command line option
1289 to display the default linker script. Certain command line options,
1290 such as @samp{-r} or @samp{-N}, will affect the default linker script.
1292 You may supply your own linker script by using the @samp{-T} command
1293 line option. When you do this, your linker script will replace the
1294 default linker script.
1296 You may also use linker scripts implicitly by naming them as input files
1297 to the linker, as though they were files to be linked. @xref{Implicit
1301 * Basic Script Concepts:: Basic Linker Script Concepts
1302 * Script Format:: Linker Script Format
1303 * Simple Example:: Simple Linker Script Example
1304 * Simple Commands:: Simple Linker Script Commands
1305 * Assignments:: Assigning Values to Symbols
1306 * SECTIONS:: SECTIONS Command
1307 * MEMORY:: MEMORY Command
1308 * PHDRS:: PHDRS Command
1309 * VERSION:: VERSION Command
1310 * Expressions:: Expressions in Linker Scripts
1311 * Implicit Linker Scripts:: Implicit Linker Scripts
1314 @node Basic Script Concepts
1315 @section Basic Linker Script Concepts
1316 @cindex linker script concepts
1317 We need to define some basic concepts and vocabulary in order to
1318 describe the linker script language.
1320 The linker combines input files into a single output file. The output
1321 file and each input file are in a special data format known as an
1322 @dfn{object file format}. Each file is called an @dfn{object file}.
1323 The output file is often called an @dfn{executable}, but for our
1324 purposes we will also call it an object file. Each object file has,
1325 among other things, a list of @dfn{sections}. We sometimes refer to a
1326 section in an input file as an @dfn{input section}; similarly, a section
1327 in the output file is an @dfn{output section}.
1329 Each section in an object file has a name and a size. Most sections
1330 also have an associated block of data, known as the @dfn{section
1331 contents}. A section may be marked as @dfn{loadable}, which mean that
1332 the contents should be loaded into memory when the output file is run.
1333 A section with no contents may be @dfn{allocatable}, which means that an
1334 area in memory should be set aside, but nothing in particular should be
1335 loaded there (in some cases this memory must be zeroed out). A section
1336 which is neither loadable nor allocatable typically contains some sort
1337 of debugging information.
1339 Every loadable or allocatable output section has two addresses. The
1340 first is the @dfn{VMA}, or virtual memory address. This is the address
1341 the section will have when the output file is run. The second is the
1342 @dfn{LMA}, or load memory address. This is the address at which the
1343 section will be loaded. In most cases the two addresses will be the
1344 same. An example of when they might be different is when a data section
1345 is loaded into ROM, and then copied into RAM when the program starts up
1346 (this technique is often used to initialize global variables in a ROM
1347 based system). In this case the ROM address would be the LMA, and the
1348 RAM address would be the VMA.
1350 You can see the sections in an object file by using the @code{objdump}
1351 program with the @samp{-h} option.
1353 Every object file also has a list of @dfn{symbols}, known as the
1354 @dfn{symbol table}. A symbol may be defined or undefined. Each symbol
1355 has a name, and each defined symbol has an address, among other
1356 information. If you compile a C or C++ program into an object file, you
1357 will get a defined symbol for every defined function and global or
1358 static variable. Every undefined function or global variable which is
1359 referenced in the input file will become an undefined symbol.
1361 You can see the symbols in an object file by using the @code{nm}
1362 program, or by using the @code{objdump} program with the @samp{-t}
1366 @section Linker Script Format
1367 @cindex linker script format
1368 Linker scripts are text files.
1370 You write a linker script as a series of commands. Each command is
1371 either a keyword, possibly followed by arguments, or an assignment to a
1372 symbol. You may separate commands using semicolons. Whitespace is
1375 Strings such as file or format names can normally be entered directly.
1376 If the file name contains a character such as a comma which would
1377 otherwise serve to separate file names, you may put the file name in
1378 double quotes. There is no way to use a double quote character in a
1381 You may include comments in linker scripts just as in C, delimited by
1382 @samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
1385 @node Simple Example
1386 @section Simple Linker Script Example
1387 @cindex linker script example
1388 @cindex example of linker script
1389 Many linker scripts are fairly simple.
1391 The simplest possible linker script has just one command:
1392 @samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
1393 memory layout of the output file.
1395 The @samp{SECTIONS} command is a powerful command. Here we will
1396 describe a simple use of it. Let's assume your program consists only of
1397 code, initialized data, and uninitialized data. These will be in the
1398 @samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
1399 Let's assume further that these are the only sections which appear in
1402 For this example, let's say that the code should be loaded at address
1403 0x10000, and that the data should start at address 0x8000000. Here is a
1404 linker script which will do that:
1409 .text : @{ *(.text) @}
1411 .data : @{ *(.data) @}
1412 .bss : @{ *(.bss) @}
1416 You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
1417 followed by a series of symbol assignments and output section
1418 descriptions enclosed in curly braces.
1420 The first line in the above example sets the special symbol @samp{.},
1421 which is the location counter. If you do not specify the address of an
1422 output section in some other way (other ways are described later), the
1423 address is set from the current value of the location counter. The
1424 location counter is then incremented by the size of the output section.
1426 The first line inside the @samp{SECTIONS} command of the above example
1427 sets the value of the special symbol @samp{.}, which is the location
1428 counter. If you do not specify the address of an output section in some
1429 other way (other ways are described later), the address is set from the
1430 current value of the location counter. The location counter is then
1431 incremented by the size of the output section. At the start of the
1432 @samp{SECTIONS} command, the location counter has the value @samp{0}.
1434 The second line defines an output section, @samp{.text}. The colon is
1435 required syntax which may be ignored for now. Within the curly braces
1436 after the output section name, you list the names of the input sections
1437 which should be placed into this output section. The @samp{*} is a
1438 wildcard which matches any file name. The expression @samp{*(.text)}
1439 means all @samp{.text} input sections in all input files.
1441 Since the location counter is @samp{0x10000} when the output section
1442 @samp{.text} is defined, the linker will set the address of the
1443 @samp{.text} section in the output file to be @samp{0x10000}.
1445 The remaining lines define the @samp{.data} and @samp{.bss} sections in
1446 the output file. The linker will place the @samp{.data} output section
1447 at address @samp{0x8000000}. After the linker places the @samp{.data}
1448 output section, the value of the location counter will be
1449 @samp{0x8000000} plus the size of the @samp{.data} output section. The
1450 effect is that the linker will place the @samp{.bss} output section
1451 immediately after the @samp{.data} output section in memory
1453 The linker will ensure that each output section has the required
1454 alignment, by increasing the location counter if necessary. In this
1455 example, the specified addresses for the @samp{.text} and @samp{.data}
1456 sections will probably satisfy any alignment constraints, but the linker
1457 may have to create a small gap between the @samp{.data} and @samp{.bss}
1460 That's it! That's a simple and complete linker script.
1462 @node Simple Commands
1463 @section Simple Linker Script Commands
1464 @cindex linker script simple commands
1465 In this section we describe the simple linker script commands.
1468 * Entry Point:: Setting the entry point
1469 * File Commands:: Commands dealing with files
1470 @ifclear SingleFormat
1471 * Format Commands:: Commands dealing with object file formats
1474 * Miscellaneous Commands:: Other linker script commands
1478 @subsection Setting the entry point
1479 @kindex ENTRY(@var{symbol})
1480 @cindex start of execution
1481 @cindex first instruction
1483 The first instruction to execute in a program is called the @dfn{entry
1484 point}. You can use the @code{ENTRY} linker script command to set the
1485 entry point. The argument is a symbol name:
1490 There are several ways to set the entry point. The linker will set the
1491 entry point by trying each of the following methods in order, and
1492 stopping when one of them succeeds:
1495 the @samp{-e} @var{entry} command-line option;
1497 the @code{ENTRY(@var{symbol})} command in a linker script;
1499 the value of the symbol @code{start}, if defined;
1501 the address of the first byte of the @samp{.text} section, if present;
1503 The address @code{0}.
1507 @subsection Commands dealing with files
1508 @cindex linker script file commands
1509 Several linker script commands deal with files.
1512 @item INCLUDE @var{filename}
1513 @kindex INCLUDE @var{filename}
1514 @cindex including a linker script
1515 Include the linker script @var{filename} at this point. The file will
1516 be searched for in the current directory, and in any directory specified
1517 with the @code{-L} option. You can nest calls to @code{INCLUDE} up to
1520 @item INPUT(@var{file}, @var{file}, @dots{})
1521 @itemx INPUT(@var{file} @var{file} @dots{})
1522 @kindex INPUT(@var{files})
1523 @cindex input files in linker scripts
1524 @cindex input object files in linker scripts
1525 @cindex linker script input object files
1526 The @code{INPUT} command directs the linker to include the named files
1527 in the link, as though they were named on the command line.
1529 For example, if you always want to include @file{subr.o} any time you do
1530 a link, but you can't be bothered to put it on every link command line,
1531 then you can put @samp{INPUT (subr.o)} in your linker script.
1533 In fact, if you like, you can list all of your input files in the linker
1534 script, and then invoke the linker with nothing but a @samp{-T} option.
1536 The linker will first try to open the file in the current directory. If
1537 it is not found, the linker will search through the archive library
1538 search path. See the description of @samp{-L} in @ref{Options,,Command
1541 If you use @samp{INPUT (-l@var{file})}, @code{ld} will transform the
1542 name to @code{lib@var{file}.a}, as with the command line argument
1545 When you use the @code{INPUT} command in an implicit linker script, the
1546 files will be included in the link at the point at which the linker
1547 script file is included. This can affect archive searching.
1549 @item GROUP(@var{file}, @var{file}, @dots{})
1550 @itemx GROUP(@var{file} @var{file} @dots{})
1551 @kindex GROUP(@var{files})
1552 @cindex grouping input files
1553 The @code{GROUP} command is like @code{INPUT}, except that the named
1554 files should all be archives, and they are searched repeatedly until no
1555 new undefined references are created. See the description of @samp{-(}
1556 in @ref{Options,,Command Line Options}.
1558 @item OUTPUT(@var{filename})
1559 @kindex OUTPUT(@var{filename})
1560 @cindex output file name in linker scripot
1561 The @code{OUTPUT} command names the output file. Using
1562 @code{OUTPUT(@var{filename})} in the linker script is exactly like using
1563 @samp{-o @var{filename}} on the command line (@pxref{Options,,Command
1564 Line Options}). If both are used, the command line option takes
1567 You can use the @code{OUTPUT} command to define a default name for the
1568 output file other than the usual default of @file{a.out}.
1570 @item SEARCH_DIR(@var{path})
1571 @kindex SEARCH_DIR(@var{path})
1572 @cindex library search path in linker script
1573 @cindex archive search path in linker script
1574 @cindex search path in linker script
1575 The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
1576 @code{ld} looks for archive libraries. Using
1577 @code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
1578 on the command line (@pxref{Options,,Command Line Options}). If both
1579 are used, then the linker will search both paths. Paths specified using
1580 the command line option are searched first.
1582 @item STARTUP(@var{filename})
1583 @kindex STARTUP(@var{filename})
1584 @cindex first input file
1585 The @code{STARTUP} command is just like the @code{INPUT} command, except
1586 that @var{filename} will become the first input file to be linked, as
1587 though it were specified first on the command line. This may be useful
1588 when using a system in which the entry point is always the start of the
1592 @ifclear SingleFormat
1593 @node Format Commands
1594 @subsection Commands dealing with object file formats
1595 A couple of linker script commands deal with object file formats.
1598 @item OUTPUT_FORMAT(@var{bfdname})
1599 @itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
1600 @kindex OUTPUT_FORMAT(@var{bfdname})
1601 @cindex output file format in linker script
1602 The @code{OUTPUT_FORMAT} command names the BFD format to use for the
1603 output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
1604 exactly like using @samp{-oformat @var{bfdname}} on the command line
1605 (@pxref{Options,,Command Line Options}). If both are used, the command
1606 line option takes precedence.
1608 You can use @code{OUTPUT_FORMAT} with three arguments to use different
1609 formats based on the @samp{-EB} and @samp{-EL} command line options.
1610 This permits the linker script to set the output format based on the
1613 If neither @samp{-EB} nor @samp{-EL} are used, then the output format
1614 will be the first argument, @var{default}. If @samp{-EB} is used, the
1615 output format will be the second argument, @var{big}. If @samp{-EL} is
1616 used, the output format will be the third argument, @var{little}.
1618 For example, the default linker script for the MIPS ELF target uses this
1621 OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
1623 This says that the default format for the output file is
1624 @samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line
1625 option, the output file will be created in the @samp{elf32-littlemips}
1628 @item TARGET(@var{bfdname})
1629 @kindex TARGET(@var{bfdname})
1630 @cindex input file format in linker script
1631 The @code{TARGET} command names the BFD format to use when reading input
1632 files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
1633 This command is like using @samp{-b @var{bfdname}} on the command line
1634 (@pxref{Options,,Command Line Options}). If the @code{TARGET} command
1635 is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
1636 command is also used to set the format for the output file. @xref{BFD}.
1640 @node Miscellaneous Commands
1641 @subsection Other linker script commands
1642 There are a few other linker scripts commands.
1645 @item FORCE_COMMON_ALLOCATION
1646 @kindex FORCE_COMMON_ALLOCATION
1647 @cindex common allocation in linker script
1648 This command has the same effect as the @samp{-d} command-line option:
1649 to make @code{ld} assign space to common symbols even if a relocatable
1650 output file is specified (@samp{-r}).
1652 @item NOCROSSREFS(@var{section} @var{section} @dots{})
1653 @kindex NOCROSSREFS(@var{sections})
1654 @cindex cross references
1655 This command may be used to tell @code{ld} to issue an error about any
1656 references among certain output sections.
1658 In certain types of programs, particularly on embedded systems when
1659 using overlays, when one section is loaded into memory, another section
1660 will not be. Any direct references between the two sections would be
1661 errors. For example, it would be an error if code in one section called
1662 a function defined in the other section.
1664 The @code{NOCROSSREFS} command takes a list of output section names. If
1665 @code{ld} detects any cross references between the sections, it reports
1666 an error and returns a non-zero exit status. Note that the
1667 @code{NOCROSSREFS} command uses output section names, not input section
1670 @ifclear SingleFormat
1671 @item OUTPUT_ARCH(@var{bfdarch})
1672 @kindex OUTPUT_ARCH(@var{bfdarch})
1673 @cindex machine architecture
1674 @cindex architecture
1675 Specify a particular output machine architecture. The argument is one
1676 of the names used by the BFD library (@pxref{BFD}). You can see the
1677 architecture of an object file by using the @code{objdump} program with
1678 the @samp{-f} option.
1683 @section Assigning Values to Symbols
1684 @cindex assignment in scripts
1685 @cindex symbol definition, scripts
1686 @cindex variables, defining
1687 You may assign a value to a symbol in a linker script. This will define
1688 the symbol as a global symbol.
1691 * Simple Assignments:: Simple Assignments
1695 @node Simple Assignments
1696 @subsection Simple Assignments
1698 You may assign to a symbol using any of the C assignment operators:
1701 @item @var{symbol} = @var{expression} ;
1702 @itemx @var{symbol} += @var{expression} ;
1703 @itemx @var{symbol} -= @var{expression} ;
1704 @itemx @var{symbol} *= @var{expression} ;
1705 @itemx @var{symbol} /= @var{expression} ;
1706 @itemx @var{symbol} <<= @var{expression} ;
1707 @itemx @var{symbol} >>= @var{expression} ;
1708 @itemx @var{symbol} &= @var{expression} ;
1709 @itemx @var{symbol} |= @var{expression} ;
1712 The first case will define @var{symbol} to the value of
1713 @var{expression}. In the other cases, @var{symbol} must already be
1714 defined, and the value will be adjusted accordingly.
1716 The special symbol name @samp{.} indicates the location counter. You
1717 may only use this within a @code{SECTIONS} command.
1719 The semicolon after @var{expression} is required.
1721 Expressions are defined below; see @ref{Expressions}.
1723 You may write symbol assignments as commands in their own right, or as
1724 statements within a @code{SECTIONS} command, or as part of an output
1725 section description in a @code{SECTIONS} command.
1727 The section of the symbol will be set from the section of the
1728 expression; for more information, see @ref{Expression Section}.
1730 Here is an example showing the three different places that symbol
1731 assignments may be used:
1742 _bdata = (. + 3) & ~ 4;
1743 .data : @{ *(.data) @}
1747 In this example, the symbol @samp{floating_point} will be defined as
1748 zero. The symbol @samp{_etext} will be defined as the address following
1749 the last @samp{.text} input section. The symbol @samp{_bdata} will be
1750 defined as the address following the @samp{.text} output section aligned
1751 upward to a 4 byte boundary.
1756 In some cases, it is desirable for a linker script to define a symbol
1757 only if it is referenced and is not defined by any object included in
1758 the link. For example, traditional linkers defined the symbol
1759 @samp{etext}. However, ANSI C requires that the user be able to use
1760 @samp{etext} as a function name without encountering an error. The
1761 @code{PROVIDE} keyword may be used to define a symbol, such as
1762 @samp{etext}, only if it is referenced but not defined. The syntax is
1763 @code{PROVIDE(@var{symbol} = @var{expression})}.
1765 Here is an example of using @code{PROVIDE} to define @samp{etext}:
1778 In this example, if the program defines @samp{_etext} (with a leading
1779 underscore), the linker will give a multiple definition error. If, on
1780 the other hand, the program defines @samp{etext} (with no leading
1781 underscore), the linker will silently use the definition in the program.
1782 If the program references @samp{etext} but does not define it, the
1783 linker will use the definition in the linker script.
1786 @section SECTIONS command
1788 The @code{SECTIONS} command tells the linker how to map input sections
1789 into output sections, and how to place the output sections in memory.
1791 The format of the @code{SECTIONS} command is:
1795 @var{sections-command}
1796 @var{sections-command}
1801 Each @var{sections-command} may of be one of the following:
1805 an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
1807 a symbol assignment (@pxref{Assignments})
1809 an output section description
1811 an overlay description
1814 The @code{ENTRY} command and symbol assignments are permitted inside the
1815 @code{SECTIONS} command for convenience in using the location counter in
1816 those commands. This can also make the linker script easier to
1817 understand because you can use those commands at meaningful points in
1818 the layout of the output file.
1820 Output section descriptions and overlay descriptions are described
1823 If you do not use a @code{SECTIONS} command in your linker script, the
1824 linker will place each input section into an identically named output
1825 section in the order that the sections are first encountered in the
1826 input files. If all input sections are present in the first file, for
1827 example, the order of sections in the output file will match the order
1828 in the first input file. The first section will be at address zero.
1831 * Output Section Description:: Output section description
1832 * Output Section Name:: Output section name
1833 * Output Section Address:: Output section address
1834 * Input Section:: Input section description
1835 * Output Section Data:: Output section data
1836 * Output Section Keywords:: Output section keywords
1837 * Output Section Discarding:: Output section discarding
1838 * Output Section Attributes:: Output section attributes
1839 * Overlay Description:: Overlay description
1842 @node Output Section Description
1843 @subsection Output section description
1844 The full description of an output section looks like this:
1847 @var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
1849 @var{output-section-command}
1850 @var{output-section-command}
1852 @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
1856 Most output sections do not use most of the optional section attributes.
1858 The whitespace around @var{section} is required, so that the section
1859 name is unambiguous. The colon and the curly braces are also required.
1860 The line breaks and other white space are optional.
1862 Each @var{output-section-command} may be one of the following:
1866 a symbol assignment (@pxref{Assignments})
1868 an input section description (@pxref{Input Section})
1870 data values to include directly (@pxref{Output Section Data})
1872 a special output section keyword (@pxref{Output Section Keywords})
1875 @node Output Section Name
1876 @subsection Output section name
1877 @cindex name, section
1878 @cindex section name
1879 The name of the output section is @var{section}. @var{section} must
1880 meet the constraints of your output format. In formats which only
1881 support a limited number of sections, such as @code{a.out}, the name
1882 must be one of the names supported by the format (@code{a.out}, for
1883 example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
1884 output format supports any number of sections, but with numbers and not
1885 names (as is the case for Oasys), the name should be supplied as a
1886 quoted numeric string. A section name may consist of any sequence of
1887 characters, but a name which contains any unusual characters such as
1888 commas must be quoted.
1890 The output section name @samp{/DISCARD/} is special; @ref{Output Section
1893 @node Output Section Address
1894 @subsection Output section address
1895 @cindex address, section
1896 @cindex section address
1897 The @var{address} is an expression for the VMA (the virtual memory
1898 address) of the output section. If you do not provide @var{address},
1899 the linker will set it based on @var{region} if present, or otherwise
1900 based on the current value of the location counter.
1902 If you provide @var{address}, the address of the output section will be
1903 set to precisely that. If you provide neither @var{address} nor
1904 @var{region}, then the address of the output section will be set to the
1905 current value of the location counter aligned to the alignment
1906 requirements of the output section. The alignment requirement of the
1907 output section is the strictest alignment of any input section contained
1908 within the output section.
1912 .text . : @{ *(.text) @}
1917 .text : @{ *(.text) @}
1920 are subtly different. The first will set the address of the
1921 @samp{.text} output section to the current value of the location
1922 counter. The second will set it to the current value of the location
1923 counter aligned to the strictest alignment of a @samp{.text} input
1926 The @var{address} may be an arbitrary expression; @ref{Expressions}.
1927 For example, if you want to align the section on a 0x10 byte boundary,
1928 so that the lowest four bits of the section address are zero, you could
1929 do something like this:
1931 .text ALIGN(0x10) : @{ *(.text) @}
1934 This works because @code{ALIGN} returns the current location counter
1935 aligned upward to the specified value.
1937 Specifying @var{address} for a section will change the value of the
1941 @subsection Input section description
1942 @cindex input sections
1943 @cindex mapping input sections to output sections
1944 The most common output section command is an input section description.
1946 The input section description is the most basic linker script operation.
1947 You use output sections to tell the linker how to lay out your program
1948 in memory. You use input section descriptions to tell the linker how to
1949 map the input files into your memory layout.
1952 * Input Section Basics:: Input section basics
1953 * Input Section Wildcards:: Input section wildcard patterns
1954 * Input Section Common:: Input section for common symbols
1955 * Input Section Example:: Input section example
1958 @node Input Section Basics
1959 @subsubsection Input section basics
1960 @cindex input section basics
1961 An input section description consists of a file name optionally followed
1962 by a list of section names in parentheses.
1964 The file name and the section name may be wildcard patterns, which we
1965 describe further below (@pxref{Input Section Wildcards}).
1967 The most common input section description is to include all input
1968 sections with a particular name in the output section. For example, to
1969 include all input @samp{.text} sections, you would write:
1974 Here the @samp{*} is a wildcard which matches any file name.
1976 There are two ways to include more than one section:
1982 The difference between these is the order in which the @samp{.text} and
1983 @samp{.rdata} input sections will appear in the output section. In the
1984 first example, they will be intermingled. In the second example, all
1985 @samp{.text} input sections will appear first, followed by all
1986 @samp{.rdata} input sections.
1988 You can specify a file name to include sections from a particular file.
1989 You would do this if one or more of your files contain special data that
1990 needs to be at a particular location in memory. For example:
1995 If you use a file name without a list of sections, then all sections in
1996 the input file will be included in the output section. This is not
1997 commonly done, but it may by useful on occasion. For example:
2002 When you use a file name which does not contain any wild card
2003 characters, the linker will first see if you also specified the file
2004 name on the linker command line or in an @code{INPUT} command. If you
2005 did not, the linker will attempt to open the file as an input file, as
2006 though it appeared on the command line. Note that this differs from an
2007 @code{INPUT} command, because the linker will not search for the file in
2008 the archive search path.
2010 @node Input Section Wildcards
2011 @subsubsection Input section wildcard patterns
2012 @cindex input section wildcards
2013 @cindex wildcard file name patterns
2014 @cindex file name wildcard patterns
2015 @cindex section name wildcard patterns
2016 In an input section description, either the file name or the section
2017 name or both may be wildcard patterns.
2019 The file name of @samp{*} seen in many examples is a simple wildcard
2020 pattern for the file name.
2022 The wildcard patterns are like those used by the Unix shell.
2026 matches any number of characters
2028 matches any single character
2030 matches a single instance of any of the @var{chars}; the @samp{-}
2031 character may be used to specify a range of characters, as in
2032 @samp{[a-z]} to match any lower case letter
2034 quotes the following character
2037 When a file name is matched with a wildcard, the wildcard characters
2038 will not match a @samp{/} character (used to separate directory names on
2039 Unix). A pattern consisting of a single @samp{*} character is an
2040 exception; it will always match any file name, whether it contains a
2041 @samp{/} or not. In a section name, the wildcard characters will match
2042 a @samp{/} character.
2044 File name wildcard patterns only match files which are explicitly
2045 specified on the command line or in an @code{INPUT} command. The linker
2046 does not search directories to expand wildcards.
2048 If a file name matches more than one wildcard pattern, or if a file name
2049 appears explicitly and is also matched by a wildcard pattern, the linker
2050 will use the first match in the linker script. For example, this
2051 sequence of input section descriptions is probably in error, because the
2052 @file{data.o} rule will not be used:
2054 .data : @{ *(.data) @}
2055 .data1 : @{ data.o(.data) @}
2058 If you ever get confused about where input sections are going, use the
2059 @samp{-M} linker option to generate a map file. The map file shows
2060 precisely how input sections are mapped to output sections.
2062 This example shows how wildcard patterns might be used to partition
2063 files. This linker script directs the linker to place all @samp{.text}
2064 sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
2065 The linker will place the @samp{.data} section from all files beginning
2066 with an upper case character in @samp{.DATA}; for all other files, the
2067 linker will place the @samp{.data} section in @samp{.data}.
2071 .text : @{ *(.text) @}
2072 .DATA : @{ [A-Z]*(.data) @}
2073 .data : @{ *(.data) @}
2074 .bss : @{ *(.bss) @}
2079 @node Input Section Common
2080 @subsubsection Input section for common symbols
2081 @cindex common symbol placement
2082 @cindex uninitialized data placement
2083 A special notation is needed for common symbols, because in many object
2084 file formats common symbols do not have a particular input section. The
2085 linker treats common symbols as though they are in an input section
2086 named @samp{COMMON}.
2088 You may use file names with the @samp{COMMON} section just as with any
2089 other input sections. You can use this to place common symbols from a
2090 particular input file in one section while common symbols from other
2091 input files are placed in another section.
2093 In most cases, common symbols in input files will be placed in the
2094 @samp{.bss} section in the output file. For example:
2096 .bss @{ *(.bss) *(COMMON) @}
2099 @cindex scommon section
2100 @cindex small common symbols
2101 Some object file formats have more than one type of common symbol. For
2102 example, the MIPS ELF object file format distinguishes standard common
2103 symbols and small common symbols. In this case, the linker will use a
2104 different special section name for other types of common symbols. In
2105 the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
2106 symbols and @samp{.scommon} for small common symbols. This permits you
2107 to map the different types of common symbols into memory at different
2111 You will sometimes see @samp{[COMMON]} in old linker scripts. This
2112 notation is now considered obsolete. It is equivalent to
2115 @node Input Section Example
2116 @subsubsection Input section example
2117 The following example is a complete linker script. It tells the linker
2118 to read all of the sections from file @file{all.o} and place them at the
2119 start of output section @samp{outputa} which starts at location
2120 @samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
2121 follows immediately, in the same output section. All of section
2122 @samp{.input2} from @file{foo.o} goes into output section
2123 @samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
2124 All of the remaining @samp{.input1} and @samp{.input2} sections from any
2125 files are written to output section @samp{outputc}.
2149 @node Output Section Data
2150 @subsection Output section data
2152 @cindex section data
2153 @cindex output section data
2154 @kindex BYTE(@var{expression})
2155 @kindex SHORT(@var{expression})
2156 @kindex LONG(@var{expression})
2157 @kindex QUAD(@var{expression})
2158 @kindex SQUAD(@var{expression})
2159 You can include explicit bytes of data in an output section by using
2160 @code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
2161 an output section command. Each keyword is followed by an expression in
2162 parentheses providing the value to store (@pxref{Expressions}). The
2163 value of the expression is stored at the current value of the location
2166 The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
2167 store one, two, four, and eight bytes (respectively). After storing the
2168 bytes, the location counter is incremented by the number of bytes
2171 For example, this will store the byte 1 followed by the four byte value
2172 of the symbol @samp{addr}:
2178 When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
2179 same; they both store an 8 byte, or 64 bit, value. When both host and
2180 target are 32 bits, an expression is computed as 32 bits. In this case
2181 @code{QUAD} stores a 32 bit value zero extended to 64 bits, and
2182 @code{SQUAD} stores a 32 bit value sign extended to 64 bits.
2184 If the object file format of the output file has an explicit endianness,
2185 which is the normal case, the value will be stored in that endianness.
2186 When the object file format does not have an explicit endianness, as is
2187 true of, for example, S-records, the value will be stored in the
2188 endianness of the first input object file.
2190 @kindex FILL(@var{expression})
2191 @cindex holes, filling
2192 @cindex unspecified memory
2193 You may use the @code{FILL} command to set the fill pattern for the
2194 current section. It is followed by an expression in parentheses. Any
2195 otherwise unspecified regions of memory within the section (for example,
2196 gaps left due to the required alignment of input sections) are filled
2197 with the two least significant bytes of the expression, repeated as
2198 necessary. A @code{FILL} statement covers memory locations after the
2199 point at which it occurs in the section definition; by including more
2200 than one @code{FILL} statement, you can have different fill patterns in
2201 different parts of an output section.
2203 This example shows how to fill unspecified regions of memory with the
2204 value @samp{0x9090}:
2209 The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
2210 section attribute (@pxref{Output Section Fill}), but it only affects the
2211 part of the section following the @code{FILL} command, rather than the
2212 entire section. If both are used, the @code{FILL} command takes
2215 @node Output Section Keywords
2216 @subsection Output section keywords
2217 There are a couple of keywords which can appear as output section
2221 @kindex CREATE_OBJECT_SYMBOLS
2222 @cindex input filename symbols
2223 @cindex filename symbols
2224 @item CREATE_OBJECT_SYMBOLS
2225 The command tells the linker to create a symbol for each input file.
2226 The name of each symbol will be the name of the corresponding input
2227 file. The section of each symbol will be the output section in which
2228 the @code{CREATE_OBJECT_SYMBOLS} command appears.
2230 This is conventional for the a.out object file format. It is not
2231 normally used for any other object file format.
2233 @kindex CONSTRUCTORS
2234 @cindex C++ constructors, arranging in link
2235 @cindex constructors, arranging in link
2237 When linking using the a.out object file format, the linker uses an
2238 unusual set construct to support C++ global constructors and
2239 destructors. When linking object file formats which do not support
2240 arbitrary sections, such as ECOFF and XCOFF, the linker will
2241 automatically recognize C++ global constructors and destructors by name.
2242 For these object file formats, the @code{CONSTRUCTORS} command tells the
2243 linker to place constructor information in the output section where the
2244 @code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
2245 ignored for other object file formats.
2247 The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
2248 constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The
2249 first word in the list is the number of entries, followed by the address
2250 of each constructor or destructor, followed by a zero word. The
2251 compiler must arrange to actually run the code. For these object file
2252 formats @sc{gnu} C++ normally calls constructors from a subroutine
2253 @code{__main}; a call to @code{__main} is automatically inserted into
2254 the startup code for @code{main}. @sc{gnu} C++ normally runs
2255 destructors either by using @code{atexit}, or directly from the function
2258 For object file formats such as @code{COFF} or @code{ELF} which support
2259 arbitrary section names, @sc{gnu} C++ will normally arrange to put the
2260 addresses of global constructors and destructors into the @code{.ctors}
2261 and @code{.dtors} sections. Placing the following sequence into your
2262 linker script will build the sort of table which the @sc{gnu} C++
2263 runtime code expects to see.
2267 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
2272 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
2278 Normally the compiler and linker will handle these issues automatically,
2279 and you will not need to concern yourself with them. However, you may
2280 need to consider this if you are using C++ and writing your own linker
2284 @node Output Section Discarding
2285 @subsection Output section discarding
2286 @cindex discarding sections
2287 @cindex sections, discarding
2288 @cindex removing sections
2289 The linker will not create output section which do not have any
2290 contents. This is for convenience when referring to input sections that
2291 may or may not be present in any of the input files. For example:
2296 will only create a @samp{.foo} section in the output file if there is a
2297 @samp{.foo} section in at least one input file.
2299 If you use anything other than an input section description as an output
2300 section command, such as a symbol assignment, then the output section
2301 will always be created, even if there are no matching input sections.
2303 The special output section name @samp{/DISCARD/} may be used to discard
2304 input sections. Any input sections which are assigned to an output
2305 section named @samp{/DISCARD/} are not included in the output file.
2307 @node Output Section Attributes
2308 @subsection Output section attributes
2309 @cindex output section attributes
2310 We showed above that the full description of an output section looked
2314 @var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
2316 @var{output-section-command}
2317 @var{output-section-command}
2319 @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
2322 We've already described @var{section}, @var{address}, and
2323 @var{output-section-command}. In this section we will describe the
2324 remaining section attributes.
2327 * Output Section Type:: Output section type
2328 * Output Section LMA:: Output section LMA
2329 * Output Section Region:: Output section region
2330 * Output Section Phdr:: Output section phdr
2331 * Output Section Fill:: Output section fill
2334 @node Output Section Type
2335 @subsubsection Output section type
2336 Each output section may have a type. The type is a keyword in
2337 parentheses. The following types are defined:
2341 The section should be marked as not loadable, so that it will not be
2342 loaded into memory when the program is run.
2347 These type names are supported for backward compatibility, and are
2348 rarely used. They all have the same effect: the section should be
2349 marked as not allocatable, so that no memory is allocated for the
2350 section when the program is run.
2354 @cindex prevent unnecessary loading
2355 @cindex loading, preventing
2356 The linker normally sets the attributes of an output section based on
2357 the input sections which map into it. You can override this by using
2358 the section type. For example, in the script sample below, the
2359 @samp{ROM} section is addressed at memory location @samp{0} and does not
2360 need to be loaded when the program is run. The contents of the
2361 @samp{ROM} section will appear in the linker output file as usual.
2365 ROM 0 (NOLOAD) : @{ @dots{} @}
2371 @node Output Section LMA
2372 @subsubsection Output section LMA
2373 @kindex AT(@var{lma})
2374 @cindex load address
2375 @cindex section load address
2376 Every section has a virtual address (VMA) and a load address (LMA); see
2377 @ref{Basic Script Concepts}. The address expression which may appear in
2378 an output section description sets the VMA (@pxref{Output Section
2381 The linker will normally set the LMA equal to the VMA. You can change
2382 that by using the @code{AT} keyword. The expression @var{lma} that
2383 follows the @code{AT} keyword specifies the load address of the section.
2385 @cindex ROM initialized data
2386 @cindex initialized data in ROM
2387 This feature is designed to make it easy to build a ROM image. For
2388 example, the following linker script creates three output sections: one
2389 called @samp{.text}, which starts at @code{0x1000}, one called
2390 @samp{.mdata}, which is loaded at the end of the @samp{.text} section
2391 even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
2392 uninitialized data at address @code{0x3000}. The symbol @code{_data} is
2393 defined with the value @code{0x2000}, which shows that the location
2394 counter holds the VMA value, not the LMA value.
2400 .text 0x1000 : @{ *(.text) _etext = . ; @}
2402 AT ( ADDR (.text) + SIZEOF (.text) )
2403 @{ _data = . ; *(.data); _edata = . ; @}
2405 @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
2410 The run-time initialization code for use with a program generated with
2411 this linker script would include something like the following, to copy
2412 the initialized data from the ROM image to its runtime address. Notice
2413 how this code takes advantage of the symbols defined by the linker
2418 extern char _etext, _data, _edata, _bstart, _bend;
2419 char *src = &_etext;
2422 /* ROM has data at end of text; copy it. */
2423 while (dst < &_edata) @{
2428 for (dst = &_bstart; dst< &_bend; dst++)
2433 @node Output Section Region
2434 @subsubsection Output section region
2435 @kindex >@var{region}
2436 @cindex section, assigning to memory region
2437 @cindex memory regions and sections
2438 You can assign a section to a previously defined region of memory by
2439 using @samp{>@var{region}}. @xref{MEMORY}.
2441 Here is a simple example:
2444 MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
2445 SECTIONS @{ ROM : @{ *(.text) @} >rom @}
2449 @node Output Section Phdr
2450 @subsubsection Output section phdr
2452 @cindex section, assigning to program header
2453 @cindex program headers and sections
2454 You can assign a section to a previously defined program segment by
2455 using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
2456 one or more segments, then all subsequent allocated sections will be
2457 assigned to those segments as well, unless they use an explicitly
2458 @code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
2459 linker to not put the section in any segment at all.
2461 Here is a simple example:
2464 PHDRS @{ text PT_LOAD ; @}
2465 SECTIONS @{ .text : @{ *(.text) @} :text @}
2469 @node Output Section Fill
2470 @subsubsection Output section fill
2471 @kindex =@var{fillexp}
2472 @cindex section fill pattern
2473 @cindex fill pattern, entire section
2474 You can set the fill pattern for an entire section by using
2475 @samp{=@var{fillexp}}. @var{fillexp} is an expression
2476 (@pxref{Expressions}). Any otherwise unspecified regions of memory
2477 within the output section (for example, gaps left due to the required
2478 alignment of input sections) will be filled with the two least
2479 significant bytes of the value, repeated as necessary.
2481 You can also change the fill value with a @code{FILL} command in the
2482 output section commands; see @ref{Output Section Data}.
2484 Here is a simple example:
2487 SECTIONS @{ .text : @{ *(.text) @} =0x9090 @}
2491 @node Overlay Description
2492 @subsection Overlay description
2495 An overlay description provides an easy way to describe sections which
2496 are to be loaded as part of a single memory image but are to be run at
2497 the same memory address. At run time, some sort of overlay manager will
2498 copy the overlaid sections in and out of the runtime memory address as
2499 required, perhaps by simply manipulating addressing bits. This approach
2500 can be useful, for example, when a certain region of memory is faster
2503 Overlays are described using the @code{OVERLAY} command. The
2504 @code{OVERLAY} command is used within a @code{SECTIONS} command, like an
2505 output section description. The full syntax of the @code{OVERLAY}
2506 command is as follows:
2509 OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
2513 @var{output-section-command}
2514 @var{output-section-command}
2516 @} [:@var{phdr}@dots{}] [=@var{fill}]
2519 @var{output-section-command}
2520 @var{output-section-command}
2522 @} [:@var{phdr}@dots{}] [=@var{fill}]
2524 @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
2528 Everything is optional except @code{OVERLAY} (a keyword), and each
2529 section must have a name (@var{secname1} and @var{secname2} above). The
2530 section definitions within the @code{OVERLAY} construct are identical to
2531 those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
2532 except that no addresses and no memory regions may be defined for
2533 sections within an @code{OVERLAY}.
2535 The sections are all defined with the same starting address. The load
2536 addresses of the sections are arranged such that they are consecutive in
2537 memory starting at the load address used for the @code{OVERLAY} as a
2538 whole (as with normal section definitions, the load address is optional,
2539 and defaults to the start address; the start address is also optional,
2540 and defaults to the current value of the location counter).
2542 If the @code{NOCROSSREFS} keyword is used, and there any references
2543 among the sections, the linker will report an error. Since the sections
2544 all run at the same address, it normally does not make sense for one
2545 section to refer directly to another. @xref{Miscellaneous Commands,
2548 For each section within the @code{OVERLAY}, the linker automatically
2549 defines two symbols. The symbol @code{__load_start_@var{secname}} is
2550 defined as the starting load address of the section. The symbol
2551 @code{__load_stop_@var{secname}} is defined as the final load address of
2552 the section. Any characters within @var{secname} which are not legal
2553 within C identifiers are removed. C (or assembler) code may use these
2554 symbols to move the overlaid sections around as necessary.
2556 At the end of the overlay, the value of the location counter is set to
2557 the start address of the overlay plus the size of the largest section.
2559 Here is an example. Remember that this would appear inside a
2560 @code{SECTIONS} construct.
2563 OVERLAY 0x1000 : AT (0x4000)
2565 .text0 @{ o1/*.o(.text) @}
2566 .text1 @{ o2/*.o(.text) @}
2571 This will define both @samp{.text0} and @samp{.text1} to start at
2572 address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
2573 @samp{.text1} will be loaded immediately after @samp{.text0}. The
2574 following symbols will be defined: @code{__load_start_text0},
2575 @code{__load_stop_text0}, @code{__load_start_text1},
2576 @code{__load_stop_text1}.
2578 C code to copy overlay @code{.text1} into the overlay area might look
2583 extern char __load_start_text1, __load_stop_text1;
2584 memcpy ((char *) 0x1000, &__load_start_text1,
2585 &__load_stop_text1 - &__load_start_text1);
2589 Note that the @code{OVERLAY} command is just syntactic sugar, since
2590 everything it does can be done using the more basic commands. The above
2591 example could have been written identically as follows.
2595 .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
2596 __load_start_text0 = LOADADDR (.text0);
2597 __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
2598 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
2599 __load_start_text1 = LOADADDR (.text1);
2600 __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
2601 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
2606 @section MEMORY command
2608 @cindex memory regions
2609 @cindex regions of memory
2610 @cindex allocating memory
2611 @cindex discontinuous memory
2612 The linker's default configuration permits allocation of all available
2613 memory. You can override this by using the @code{MEMORY} command.
2615 The @code{MEMORY} command describes the location and size of blocks of
2616 memory in the target. You can use it to describe which memory regions
2617 may be used by the linker, and which memory regions it must avoid. You
2618 can then assign sections to particular memory regions. The linker will
2619 set section addresses based on the memory regions, and will warn about
2620 regions that become too full. The linker will not shuffle sections
2621 around to fit into the available regions.
2623 A linker script may contain at most one use of the @code{MEMORY}
2624 command. However, you can define as many blocks of memory within it as
2625 you wish. The syntax is:
2630 @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
2636 The @var{name} is a name used in the linker script to refer to the
2637 region. The region name has no meaning outside of the linker script.
2638 Region names are stored in a separate name space, and will not conflict
2639 with symbol names, file names, or section names. Each memory region
2640 must have a distinct name.
2642 @cindex memory region attributes
2643 The @var{attr} string is an optional list of attributes that specify
2644 whether to use a particular memory region for an input section which is
2645 not explicitly mapped in the linker script. As described in
2646 @ref{SECTIONS}, if you do not specify an output section for some input
2647 section, the linker will create an output section with the same name as
2648 the input section. If you define region attributes, the linker will use
2649 them to select the memory region for the output section that it creates.
2651 The @var{attr} string must consist only of the following characters:
2666 Invert the sense of any of the preceding attributes
2669 If a unmapped section matches any of the listed attributes other than
2670 @samp{!}, it will be placed in the memory region. The @samp{!}
2671 attribute reverses this test, so that an unmapped section will be placed
2672 in the memory region only if it does not match any of the listed
2678 The @var{origin} is an expression for the start address of the memory
2679 region. The expression must evaluate to a constant before memory
2680 allocation is performed, which means that you may not use any section
2681 relative symbols. The keyword @code{ORIGIN} may be abbreviated to
2682 @code{org} or @code{o} (but not, for example, @code{ORG}).
2687 The @var{len} is an expression for the size in bytes of the memory
2688 region. As with the @var{origin} expression, the expression must
2689 evaluate to a constant before memory allocation is performed. The
2690 keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
2692 In the following example, we specify that there are two memory regions
2693 available for allocation: one starting at @samp{0} for 256 kilobytes,
2694 and the other starting at @samp{0x40000000} for four megabytes. The
2695 linker will place into the @samp{rom} memory region every section which
2696 is not explicitly mapped into a memory region, and is either read-only
2697 or executable. The linker will place other sections which are not
2698 explicitly mapped into a memory region into the @samp{ram} memory
2705 rom (rx) : ORIGIN = 0, LENGTH = 256K
2706 ram (!rx) : org = 0x40000000, l = 4M
2711 Once you define a memory region, you can direct the linker to place
2712 specific output sections into that memory region by using the
2713 @samp{>@var{region}} output section attribute. For example, if you have
2714 a memory region named @samp{mem}, you would use @samp{>mem} in the
2715 output section definition. @xref{Output Section Region}. If no address
2716 was specified for the output section, the linker will set the address to
2717 the next available address within the memory region. If the combined
2718 output sections directed to a memory region are too large for the
2719 region, the linker will issue an error message.
2722 @section PHDRS Command
2724 @cindex program headers
2725 @cindex ELF program headers
2726 @cindex program segments
2727 @cindex segments, ELF
2728 The ELF object file format uses @dfn{program headers}, also knows as
2729 @dfn{segments}. The program headers describe how the program should be
2730 loaded into memory. You can print them out by using the @code{objdump}
2731 program with the @samp{-p} option.
2733 When you run an ELF program on a native ELF system, the system loader
2734 reads the program headers in order to figure out how to load the
2735 program. This will only work if the program headers are set correctly.
2736 This manual does not describe the details of how the system loader
2737 interprets program headers; for more information, see the ELF ABI.
2739 The linker will create reasonable program headers by default. However,
2740 in some cases, you may need to specify the program headers more
2741 precisely. You may use the @code{PHDRS} command for this purpose. When
2742 the linker sees the @code{PHDRS} command in the linker script, it will
2743 not create any program headers other than the ones specified.
2745 The linker only pays attention to the @code{PHDRS} command when
2746 generating an ELF output file. In other cases, the linker will simply
2747 ignore @code{PHDRS}.
2749 This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
2750 @code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
2756 @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
2757 [ FLAGS ( @var{flags} ) ] ;
2762 The @var{name} is used only for reference in the @code{SECTIONS} command
2763 of the linker script. It is not put into the output file. Program
2764 header names are stored in a separate name space, and will not conflict
2765 with symbol names, file names, or section names. Each program header
2766 must have a distinct name.
2768 Certain program header types describe segments of memory which the
2769 system loader will load from the file. In the linker script, you
2770 specify the contents of these segments by placing allocatable output
2771 sections in the segments. You use the @samp{:@var{phdr}} output section
2772 attribute to place a section in a particular segment. @xref{Output
2775 It is normal to put certain sections in more than one segment. This
2776 merely implies that one segment of memory contains another. You may
2777 repeat @samp{:@var{phdr}}, using it once for each segment which should
2778 contain the section.
2780 If you place a section in one or more segments using @samp{:@var{phdr}},
2781 then the linker will place all subsequent allocatable sections which do
2782 not specify @samp{:@var{phdr}} in the same segments. This is for
2783 convenience, since generally a whole set of contiguous sections will be
2784 placed in a single segment. You can use @code{:NONE} to override the
2785 default segment and tell the linker to not put the section in any
2790 You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after
2791 the program header type to further describe the contents of the segment.
2792 The @code{FILEHDR} keyword means that the segment should include the ELF
2793 file header. The @code{PHDRS} keyword means that the segment should
2794 include the ELF program headers themselves.
2796 The @var{type} may be one of the following. The numbers indicate the
2797 value of the keyword.
2800 @item @code{PT_NULL} (0)
2801 Indicates an unused program header.
2803 @item @code{PT_LOAD} (1)
2804 Indicates that this program header describes a segment to be loaded from
2807 @item @code{PT_DYNAMIC} (2)
2808 Indicates a segment where dynamic linking information can be found.
2810 @item @code{PT_INTERP} (3)
2811 Indicates a segment where the name of the program interpreter may be
2814 @item @code{PT_NOTE} (4)
2815 Indicates a segment holding note information.
2817 @item @code{PT_SHLIB} (5)
2818 A reserved program header type, defined but not specified by the ELF
2821 @item @code{PT_PHDR} (6)
2822 Indicates a segment where the program headers may be found.
2824 @item @var{expression}
2825 An expression giving the numeric type of the program header. This may
2826 be used for types not defined above.
2829 You can specify that a segment should be loaded at a particular address
2830 in memory by using an @code{AT} expression. This is identical to the
2831 @code{AT} command used as an output section attribute (@pxref{Output
2832 Section LMA}). The @code{AT} command for a program header overrides the
2833 output section attribute.
2835 The linker will normally set the segment flags based on the sections
2836 which comprise the segment. You may use the @code{FLAGS} keyword to
2837 explicitly specify the segment flags. The value of @var{flags} must be
2838 an integer. It is used to set the @code{p_flags} field of the program
2841 Here is an example of @code{PHDRS}. This shows a typical set of program
2842 headers used on a native ELF system.
2848 headers PT_PHDR PHDRS ;
2850 text PT_LOAD FILEHDR PHDRS ;
2852 dynamic PT_DYNAMIC ;
2858 .interp : @{ *(.interp) @} :text :interp
2859 .text : @{ *(.text) @} :text
2860 .rodata : @{ *(.rodata) @} /* defaults to :text */
2862 . = . + 0x1000; /* move to a new page in memory */
2863 .data : @{ *(.data) @} :data
2864 .dynamic : @{ *(.dynamic) @} :data :dynamic
2871 @section VERSION Command
2872 @kindex VERSION @{script text@}
2873 @cindex symbol versions
2874 @cindex version script
2875 @cindex versions of symbols
2876 The linker supports symbol versions when using ELF. Symbol versions are
2877 only useful when using shared libraries. The dynamic linker can use
2878 symbol versions to select a specific version of a function when it runs
2879 a program that may have been linked against an earlier version of the
2882 You can include a version script directly in the main linker script, or
2883 you can supply the version script as an implicit linker script. You can
2884 also use the @samp{--version-script} linker option.
2886 The syntax of the @code{VERSION} command is simply
2888 VERSION @{ version-script-commands @}
2891 The format of the version script commands is identical to that used by
2892 Sun's linker in Solaris 2.5. The version script defines a tree of
2893 version nodes. You specify the node names and interdependencies in the
2894 version script. You can specify which symbols are bound to which
2895 version nodes, and you can reduce a specified set of symbols to local
2896 scope so that they are not globally visible outside of the shared
2899 The easiest way to demonstrate the version script language is with a few
2921 This example version script defines three version nodes. The first
2922 version node defined is @samp{VERS_1.1}; it has no other dependencies.
2923 The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
2924 a number of symbols to local scope so that they are not visible outside
2925 of the shared library.
2927 Next, the version script defines node @samp{VERS_1.2}. This node
2928 depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
2929 to the version node @samp{VERS_1.2}.
2931 Finally, the version script defines node @samp{VERS_2.0}. This node
2932 depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
2933 and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
2935 When the linker finds a symbol defined in a library which is not
2936 specifically bound to a version node, it will effectively bind it to an
2937 unspecified base version of the library. You can bind all otherwise
2938 unspecified symbols to a given version node by using @samp{global: *}
2939 somewhere in the version script.
2941 The names of the version nodes have no specific meaning other than what
2942 they might suggest to the person reading them. The @samp{2.0} version
2943 could just as well have appeared in between @samp{1.1} and @samp{1.2}.
2944 However, this would be a confusing way to write a version script.
2946 When you link an application against a shared library that has versioned
2947 symbols, the application itself knows which version of each symbol it
2948 requires, and it also knows which version nodes it needs from each
2949 shared library it is linked against. Thus at runtime, the dynamic
2950 loader can make a quick check to make sure that the libraries you have
2951 linked against do in fact supply all of the version nodes that the
2952 application will need to resolve all of the dynamic symbols. In this
2953 way it is possible for the dynamic linker to know with certainty that
2954 all external symbols that it needs will be resolvable without having to
2955 search for each symbol reference.
2957 The symbol versioning is in effect a much more sophisticated way of
2958 doing minor version checking that SunOS does. The fundamental problem
2959 that is being addressed here is that typically references to external
2960 functions are bound on an as-needed basis, and are not all bound when
2961 the application starts up. If a shared library is out of date, a
2962 required interface may be missing; when the application tries to use
2963 that interface, it may suddenly and unexpectedly fail. With symbol
2964 versioning, the user will get a warning when they start their program if
2965 the libraries being used with the application are too old.
2967 There are several GNU extensions to Sun's versioning approach. The
2968 first of these is the ability to bind a symbol to a version node in the
2969 source file where the symbol is defined instead of in the versioning
2970 script. This was done mainly to reduce the burden on the library
2971 maintainer. You can do this by putting something like:
2973 __asm__(".symver original_foo,foo@@VERS_1.1");
2976 in the C source file. This renames the function @samp{original_foo} to
2977 be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
2978 The @samp{local:} directive can be used to prevent the symbol
2979 @samp{original_foo} from being exported.
2981 The second GNU extension is to allow multiple versions of the same
2982 function to appear in a given shared library. In this way you can make
2983 an incompatible change to an interface without increasing the major
2984 version number of the shared library, while still allowing applications
2985 linked against the old interface to continue to function.
2987 To do this, you must use multiple @samp{.symver} directives in the
2988 source file. Here is an example:
2991 __asm__(".symver original_foo,foo@@");
2992 __asm__(".symver old_foo,foo@@VERS_1.1");
2993 __asm__(".symver old_foo1,foo@@VERS_1.2");
2994 __asm__(".symver new_foo,foo@@@@VERS_2.0");
2997 In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
2998 unspecified base version of the symbol. The source file that contains this
2999 example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
3000 @samp{old_foo1}, and @samp{new_foo}.
3002 When you have multiple definitions of a given symbol, there needs to be
3003 some way to specify a default version to which external references to
3004 this symbol will be bound. You can do this with the
3005 @samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
3006 declare one version of a symbol as the default in this manner; otherwise
3007 you would effectively have multiple definitions of the same symbol.
3009 If you wish to bind a reference to a specific version of the symbol
3010 within the shared library, you can use the aliases of convenience
3011 (i.e. @samp{old_foo}), or you can use the @samp{.symver} directive to
3012 specifically bind to an external version of the function in question.
3015 @section Expressions in Linker Scripts
3018 The syntax for expressions in the linker script language is identical to
3019 that of C expressions. All expressions are evaluated as integers. All
3020 expressions are evaluated in the same size, which is 32 bits if both the
3021 host and target are 32 bits, and is otherwise 64 bits.
3023 You can use and set symbol values in expressions.
3025 The linker defines several special purpose builtin functions for use in
3029 * Constants:: Constants
3030 * Symbols:: Symbol Names
3031 * Location Counter:: The Location Counter
3032 * Operators:: Operators
3033 * Evaluation:: Evaluation
3034 * Expression Section:: The Section of an Expression
3035 * Builtin Functions:: Builtin Functions
3039 @subsection Constants
3040 @cindex integer notation
3041 @cindex constants in linker scripts
3042 All constants are integers.
3044 As in C, the linker considers an integer beginning with @samp{0} to be
3045 octal, and an integer beginning with @samp{0x} or @samp{0X} to be
3046 hexadecimal. The linker considers other integers to be decimal.
3048 @cindex scaled integers
3049 @cindex K and M integer suffixes
3050 @cindex M and K integer suffixes
3051 @cindex suffixes for integers
3052 @cindex integer suffixes
3053 In addition, you can use the suffixes @code{K} and @code{M} to scale a
3057 @c END TEXI2ROFF-KILL
3058 @code{1024} or @code{1024*1024}
3062 ${\rm 1024}$ or ${\rm 1024}^2$
3064 @c END TEXI2ROFF-KILL
3065 respectively. For example, the following all refer to the same quantity:
3073 @subsection Symbol Names
3074 @cindex symbol names
3076 @cindex quoted symbol names
3078 Unless quoted, symbol names start with a letter, underscore, or period
3079 and may include letters, digits, underscores, periods, and hyphens.
3080 Unquoted symbol names must not conflict with any keywords. You can
3081 specify a symbol which contains odd characters or has the same name as a
3082 keyword by surrounding the symbol name in double quotes:
3085 "with a space" = "also with a space" + 10;
3088 Since symbols can contain many non-alphabetic characters, it is safest
3089 to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
3090 whereas @samp{A - B} is an expression involving subtraction.
3092 @node Location Counter
3093 @subsection The Location Counter
3096 @cindex location counter
3097 @cindex current output location
3098 The special linker variable @dfn{dot} @samp{.} always contains the
3099 current output location counter. Since the @code{.} always refers to a
3100 location in an output section, it may only appear in an expression
3101 within a @code{SECTIONS} command. The @code{.} symbol may appear
3102 anywhere that an ordinary symbol is allowed in an expression.
3105 Assigning a value to @code{.} will cause the location counter to be
3106 moved. This may be used to create holes in the output section. The
3107 location counter may never be moved backwards.
3123 In the previous example, the @samp{.text} section from @file{file1} is
3124 located at the beginning of the output section @samp{output}. It is
3125 followed by a 1000 byte gap. Then the @samp{.text} section from
3126 @file{file2} appears, also with a 1000 byte gap following before the
3127 @samp{.text} section from @file{file3}. The notation @samp{= 0x1234}
3128 specifies what data to write in the gaps (@pxref{Output Section Fill}).
3132 @subsection Operators
3133 @cindex operators for arithmetic
3134 @cindex arithmetic operators
3135 @cindex precedence in expressions
3136 The linker recognizes the standard C set of arithmetic operators, with
3137 the standard bindings and precedence levels:
3140 @c END TEXI2ROFF-KILL
3142 precedence associativity Operators Notes
3148 5 left == != > < <= >=
3154 11 right &= += -= *= /= (2)
3158 (1) Prefix operators
3159 (2) @xref{Assignments}.
3163 \vskip \baselineskip
3164 %"lispnarrowing" is the extra indent used generally for smallexample
3165 \hskip\lispnarrowing\vbox{\offinterlineskip
3168 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
3169 height2pt&\omit&&\omit&&\omit&\cr
3170 &Precedence&& Associativity &&{\rm Operators}&\cr
3171 height2pt&\omit&&\omit&&\omit&\cr
3173 height2pt&\omit&&\omit&&\omit&\cr
3175 % '176 is tilde, '~' in tt font
3176 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
3177 &2&&left&&* / \%&\cr
3180 &5&&left&&== != > < <= >=&\cr
3183 &8&&left&&{\&\&}&\cr
3186 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
3188 height2pt&\omit&&\omit&&\omit&\cr}
3193 @obeylines@parskip=0pt@parindent=0pt
3194 @dag@quad Prefix operators.
3195 @ddag@quad @xref{Assignments}.
3198 @c END TEXI2ROFF-KILL
3201 @subsection Evaluation
3202 @cindex lazy evaluation
3203 @cindex expression evaluation order
3204 The linker evaluates expressions lazily. It only computes the value of
3205 an expression when absolutely necessary.
3207 The linker needs some information, such as the value of the start
3208 address of the first section, and the origins and lengths of memory
3209 regions, in order to do any linking at all. These values are computed
3210 as soon as possible when the linker reads in the linker script.
3212 However, other values (such as symbol values) are not known or needed
3213 until after storage allocation. Such values are evaluated later, when
3214 other information (such as the sizes of output sections) is available
3215 for use in the symbol assignment expression.
3217 The sizes of sections cannot be known until after allocation, so
3218 assignments dependent upon these are not performed until after
3221 Some expressions, such as those depending upon the location counter
3222 @samp{.}, must be evaluated during section allocation.
3224 If the result of an expression is required, but the value is not
3225 available, then an error results. For example, a script like the
3231 .text 9+this_isnt_constant :
3237 will cause the error message @samp{non constant expression for initial
3240 @node Expression Section
3241 @subsection The Section of an Expression
3242 @cindex expression sections
3243 @cindex absolute expressions
3244 @cindex relative expressions
3245 @cindex absolute and relocatable symbols
3246 @cindex relocatable and absolute symbols
3247 @cindex symbols, relocatable and absolute
3248 When the linker evaluates an expression, the result is either absolute
3249 or relative to some section. A relative expression is expressed as a
3250 fixed offset from the base of a section.
3252 The position of the expression within the linker script determines
3253 whether it is absolute or relative. An expression which appears within
3254 an output section definition is relative to the base of the output
3255 section. An expression which appears elsewhere will be absolute.
3257 A symbol set to a relative expression will be relocatable if you request
3258 relocatable output using the @samp{-r} option. That means that a
3259 further link operation may change the value of the symbol. The symbol's
3260 section will be the section of the relative expression.
3262 A symbol set to an absolute expression will retain the same value
3263 through any further link operation. The symbol will be absolute, and
3264 will not have any particular associated section.
3266 You can use the builtin function @code{ABSOLUTE} to force an expression
3267 to be absolute when it would otherwise be relative. For example, to
3268 create an absolute symbol set to the address of the end of the output
3269 section @samp{.data}:
3273 .data : @{ *(.data) _edata = ABSOLUTE(.); @}
3277 If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
3278 @samp{.data} section.
3280 @node Builtin Functions
3281 @subsection Builtin Functions
3282 @cindex functions in expressions
3283 The linker script language includes a number of builtin functions for
3284 use in linker script expressions.
3287 @item ABSOLUTE(@var{exp})
3288 @kindex ABSOLUTE(@var{exp})
3289 @cindex expression, absolute
3290 Return the absolute (non-relocatable, as opposed to non-negative) value
3291 of the expression @var{exp}. Primarily useful to assign an absolute
3292 value to a symbol within a section definition, where symbol values are
3293 normally section relative. @xref{Expression Section}.
3295 @item ADDR(@var{section})
3296 @kindex ADDR(@var{section})
3297 @cindex section address in expression
3298 Return the absolute address (the VMA) of the named @var{section}. Your
3299 script must previously have defined the location of that section. In
3300 the following example, @code{symbol_1} and @code{symbol_2} are assigned
3307 start_of_output_1 = ABSOLUTE(.);
3312 symbol_1 = ADDR(.output1);
3313 symbol_2 = start_of_output_1;
3319 @item ALIGN(@var{exp})
3320 @kindex ALIGN(@var{exp})
3321 @cindex round up location counter
3322 @cindex align location counter
3323 Return the location counter (@code{.}) aligned to the next @var{exp}
3324 boundary. @var{exp} must be an expression whose value is a power of
3325 two. This is equivalent to
3327 (. + @var{exp} - 1) & ~(@var{exp} - 1)
3330 @code{ALIGN} doesn't change the value of the location counter---it just
3331 does arithmetic on it. Here is an example which aligns the output
3332 @code{.data} section to the next @code{0x2000} byte boundary after the
3333 preceding section and sets a variable within the section to the next
3334 @code{0x8000} boundary after the input sections:
3338 .data ALIGN(0x2000): @{
3340 variable = ALIGN(0x8000);
3346 The first use of @code{ALIGN} in this example specifies the location of
3347 a section because it is used as the optional @var{address} attribute of
3348 a section definition (@pxref{Output Section Address}). The second use
3349 of @code{ALIGN} is used to defines the value of a symbol.
3351 The builtin function @code{NEXT} is closely related to @code{ALIGN}.
3353 @item BLOCK(@var{exp})
3354 @kindex BLOCK(@var{exp})
3355 This is a synonym for @code{ALIGN}, for compatibility with older linker
3356 scripts. It is most often seen when setting the address of an output
3359 @item DEFINED(@var{symbol})
3360 @kindex DEFINED(@var{symbol})
3361 @cindex symbol defaults
3362 Return 1 if @var{symbol} is in the linker global symbol table and is
3363 defined, otherwise return 0. You can use this function to provide
3364 default values for symbols. For example, the following script fragment
3365 shows how to set a global symbol @samp{begin} to the first location in
3366 the @samp{.text} section---but if a symbol called @samp{begin} already
3367 existed, its value is preserved:
3373 begin = DEFINED(begin) ? begin : . ;
3380 @item LOADADDR(@var{section})
3381 @kindex LOADADDR(@var{section})
3382 @cindex section load address in expression
3383 Return the absolute LMA of the named @var{section}. This is normally
3384 the same as @code{ADDR}, but it may be different if the @code{AT}
3385 attribute is used in the output section definition (@pxref{Output
3389 @item MAX(@var{exp1}, @var{exp2})
3390 Returns the maximum of @var{exp1} and @var{exp2}.
3393 @item MIN(@var{exp1}, @var{exp2})
3394 Returns the minimum of @var{exp1} and @var{exp2}.
3396 @item NEXT(@var{exp})
3397 @kindex NEXT(@var{exp})
3398 @cindex unallocated address, next
3399 Return the next unallocated address that is a multiple of @var{exp}.
3400 This function is closely related to @code{ALIGN(@var{exp})}; unless you
3401 use the @code{MEMORY} command to define discontinuous memory for the
3402 output file, the two functions are equivalent.
3404 @item SIZEOF(@var{section})
3405 @kindex SIZEOF(@var{section})
3406 @cindex section size
3407 Return the size in bytes of the named @var{section}, if that section has
3408 been allocated. If the section has not been allocated when this is
3409 evaluated, the linker will report an error. In the following example,
3410 @code{symbol_1} and @code{symbol_2} are assigned identical values:
3419 symbol_1 = .end - .start ;
3420 symbol_2 = SIZEOF(.output);
3425 @item SIZEOF_HEADERS
3426 @itemx sizeof_headers
3427 @kindex SIZEOF_HEADERS
3429 Return the size in bytes of the output file's headers. This is
3430 information which appears at the start of the output file. You can use
3431 this number when setting the start address of the first section, if you
3432 choose, to facilitate paging.
3434 @cindex not enough room for program headers
3435 @cindex program headers, not enough room
3436 When producing an ELF output file, if the linker script uses the
3437 @code{SIZEOF_HEADERS} builtin function, the linker must compute the
3438 number of program headers before it has determined all the section
3439 addresses and sizes. If the linker later discovers that it needs
3440 additional program headers, it will report an error @samp{not enough
3441 room for program headers}. To avoid this error, you must avoid using
3442 the @code{SIZEOF_HEADERS} function, or you must rework your linker
3443 script to avoid forcing the linker to use additional program headers, or
3444 you must define the program headers yourself using the @code{PHDRS}
3445 command (@pxref{PHDRS}).
3448 @node Implicit Linker Scripts
3449 @section Implicit Linker Scripts
3450 @cindex implicit linker scripts
3451 If you specify a linker input file which the linker can not recognize as
3452 an object file or an archive file, it will try to read the file as a
3453 linker script. If the file can not be parsed as a linker script, the
3454 linker will report an error.
3456 An implicit linker script will not replace the default linker script.
3458 Typically an implicit linker script would contain only symbol
3459 assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
3462 Any input files read because of an implicit linker script will be read
3463 at the position in the command line where the implicit linker script was
3464 read. This can affect archive searching.
3467 @node Machine Dependent
3468 @chapter Machine Dependent Features
3470 @cindex machine dependencies
3471 @code{ld} has additional features on some platforms; the following
3472 sections describe them. Machines where @code{ld} has no additional
3473 functionality are not listed.
3476 * H8/300:: @code{ld} and the H8/300
3477 * i960:: @code{ld} and the Intel 960 family
3481 @c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict
3482 @c between those and node-defaulting.
3488 @section @code{ld} and the H8/300
3490 @cindex H8/300 support
3491 For the H8/300, @code{ld} can perform these global optimizations when
3492 you specify the @samp{--relax} command-line option.
3495 @cindex relaxing on H8/300
3496 @item relaxing address modes
3497 @code{ld} finds all @code{jsr} and @code{jmp} instructions whose
3498 targets are within eight bits, and turns them into eight-bit
3499 program-counter relative @code{bsr} and @code{bra} instructions,
3502 @cindex synthesizing on H8/300
3503 @item synthesizing instructions
3504 @c FIXME: specifically mov.b, or any mov instructions really?
3505 @code{ld} finds all @code{mov.b} instructions which use the
3506 sixteen-bit absolute address form, but refer to the top
3507 page of memory, and changes them to use the eight-bit address form.
3508 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
3509 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
3510 top page of memory).
3519 @c This stuff is pointless to say unless you're especially concerned
3520 @c with Hitachi chips; don't enable it for generic case, please.
3522 @chapter @code{ld} and other Hitachi chips
3524 @code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No
3525 special features, commands, or command-line options are required for
3535 @section @code{ld} and the Intel 960 family
3537 @cindex i960 support
3539 You can use the @samp{-A@var{architecture}} command line option to
3540 specify one of the two-letter names identifying members of the 960
3541 family; the option specifies the desired output target, and warns of any
3542 incompatible instructions in the input files. It also modifies the
3543 linker's search strategy for archive libraries, to support the use of
3544 libraries specific to each particular architecture, by including in the
3545 search loop names suffixed with the string identifying the architecture.
3547 For example, if your @code{ld} command line included @w{@samp{-ACA}} as
3548 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
3549 paths, and in any paths you specify with @samp{-L}) for a library with
3562 The first two possibilities would be considered in any event; the last
3563 two are due to the use of @w{@samp{-ACA}}.
3565 You can meaningfully use @samp{-A} more than once on a command line, since
3566 the 960 architecture family allows combination of target architectures; each
3567 use will add another pair of name variants to search for when @w{@samp{-l}}
3568 specifies a library.
3570 @cindex @code{--relax} on i960
3571 @cindex relaxing on i960
3572 @code{ld} supports the @samp{--relax} option for the i960 family. If
3573 you specify @samp{--relax}, @code{ld} finds all @code{balx} and
3574 @code{calx} instructions whose targets are within 24 bits, and turns
3575 them into 24-bit program-counter relative @code{bal} and @code{cal}
3576 instructions, respectively. @code{ld} also turns @code{cal}
3577 instructions into @code{bal} instructions when it determines that the
3578 target subroutine is a leaf routine (that is, the target subroutine does
3579 not itself call any subroutines).
3586 @ifclear SingleFormat
3591 @cindex object file management
3592 @cindex object formats available
3594 The linker accesses object and archive files using the BFD libraries.
3595 These libraries allow the linker to use the same routines to operate on
3596 object files whatever the object file format. A different object file
3597 format can be supported simply by creating a new BFD back end and adding
3598 it to the library. To conserve runtime memory, however, the linker and
3599 associated tools are usually configured to support only a subset of the
3600 object file formats available. You can use @code{objdump -i}
3601 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
3602 list all the formats available for your configuration.
3604 @cindex BFD requirements
3605 @cindex requirements for BFD
3606 As with most implementations, BFD is a compromise between
3607 several conflicting requirements. The major factor influencing
3608 BFD design was efficiency: any time used converting between
3609 formats is time which would not have been spent had BFD not
3610 been involved. This is partly offset by abstraction payback; since
3611 BFD simplifies applications and back ends, more time and care
3612 may be spent optimizing algorithms for a greater speed.
3614 One minor artifact of the BFD solution which you should bear in
3615 mind is the potential for information loss. There are two places where
3616 useful information can be lost using the BFD mechanism: during
3617 conversion and during output. @xref{BFD information loss}.
3620 * BFD outline:: How it works: an outline of BFD
3624 @section How it works: an outline of BFD
3625 @cindex opening object files
3626 @include bfdsumm.texi
3629 @node Reporting Bugs
3630 @chapter Reporting Bugs
3631 @cindex bugs in @code{ld}
3632 @cindex reporting bugs in @code{ld}
3634 Your bug reports play an essential role in making @code{ld} reliable.
3636 Reporting a bug may help you by bringing a solution to your problem, or
3637 it may not. But in any case the principal function of a bug report is
3638 to help the entire community by making the next version of @code{ld}
3639 work better. Bug reports are your contribution to the maintenance of
3642 In order for a bug report to serve its purpose, you must include the
3643 information that enables us to fix the bug.
3646 * Bug Criteria:: Have you found a bug?
3647 * Bug Reporting:: How to report bugs
3651 @section Have you found a bug?
3652 @cindex bug criteria
3654 If you are not sure whether you have found a bug, here are some guidelines:
3657 @cindex fatal signal
3658 @cindex linker crash
3659 @cindex crash of linker
3661 If the linker gets a fatal signal, for any input whatever, that is a
3662 @code{ld} bug. Reliable linkers never crash.
3664 @cindex error on valid input
3666 If @code{ld} produces an error message for valid input, that is a bug.
3668 @cindex invalid input
3670 If @code{ld} does not produce an error message for invalid input, that
3671 may be a bug. In the general case, the linker can not verify that
3672 object files are correct.
3675 If you are an experienced user of linkers, your suggestions for
3676 improvement of @code{ld} are welcome in any case.
3680 @section How to report bugs
3682 @cindex @code{ld} bugs, reporting
3684 A number of companies and individuals offer support for @sc{gnu}
3685 products. If you obtained @code{ld} from a support organization, we
3686 recommend you contact that organization first.
3688 You can find contact information for many support companies and
3689 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
3692 Otherwise, send bug reports for @code{ld} to
3693 @samp{bug-gnu-utils@@gnu.org}.
3695 The fundamental principle of reporting bugs usefully is this:
3696 @strong{report all the facts}. If you are not sure whether to state a
3697 fact or leave it out, state it!
3699 Often people omit facts because they think they know what causes the
3700 problem and assume that some details do not matter. Thus, you might
3701 assume that the name of a symbol you use in an example does not matter.
3702 Well, probably it does not, but one cannot be sure. Perhaps the bug is
3703 a stray memory reference which happens to fetch from the location where
3704 that name is stored in memory; perhaps, if the name were different, the
3705 contents of that location would fool the linker into doing the right
3706 thing despite the bug. Play it safe and give a specific, complete
3707 example. That is the easiest thing for you to do, and the most helpful.
3709 Keep in mind that the purpose of a bug report is to enable us to fix the bug if
3710 it is new to us. Therefore, always write your bug reports on the assumption
3711 that the bug has not been reported previously.
3713 Sometimes people give a few sketchy facts and ask, ``Does this ring a
3714 bell?'' Those bug reports are useless, and we urge everyone to
3715 @emph{refuse to respond to them} except to chide the sender to report
3718 To enable us to fix the bug, you should include all these things:
3722 The version of @code{ld}. @code{ld} announces it if you start it with
3723 the @samp{--version} argument.
3725 Without this, we will not know whether there is any point in looking for
3726 the bug in the current version of @code{ld}.
3729 Any patches you may have applied to the @code{ld} source, including any
3730 patches made to the @code{BFD} library.
3733 The type of machine you are using, and the operating system name and
3737 What compiler (and its version) was used to compile @code{ld}---e.g.
3741 The command arguments you gave the linker to link your example and
3742 observe the bug. To guarantee you will not omit something important,
3743 list them all. A copy of the Makefile (or the output from make) is
3746 If we were to try to guess the arguments, we would probably guess wrong
3747 and then we might not encounter the bug.
3750 A complete input file, or set of input files, that will reproduce the
3751 bug. It is generally most helpful to send the actual object files,
3752 uuencoded if necessary to get them through the mail system. Making them
3753 available for anonymous FTP is not as good, but may be the only
3754 reasonable choice for large object files.
3756 If the source files were assembled using @code{gas} or compiled using
3757 @code{gcc}, then it may be OK to send the source files rather than the
3758 object files. In this case, be sure to say exactly what version of
3759 @code{gas} or @code{gcc} was used to produce the object files. Also say
3760 how @code{gas} or @code{gcc} were configured.
3763 A description of what behavior you observe that you believe is
3764 incorrect. For example, ``It gets a fatal signal.''
3766 Of course, if the bug is that @code{ld} gets a fatal signal, then we
3767 will certainly notice it. But if the bug is incorrect output, we might
3768 not notice unless it is glaringly wrong. You might as well not give us
3769 a chance to make a mistake.
3771 Even if the problem you experience is a fatal signal, you should still
3772 say so explicitly. Suppose something strange is going on, such as, your
3773 copy of @code{ld} is out of synch, or you have encountered a bug in the
3774 C library on your system. (This has happened!) Your copy might crash
3775 and ours would not. If you told us to expect a crash, then when ours
3776 fails to crash, we would know that the bug was not happening for us. If
3777 you had not told us to expect a crash, then we would not be able to draw
3778 any conclusion from our observations.
3781 If you wish to suggest changes to the @code{ld} source, send us context
3782 diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
3783 @samp{-p} option. Always send diffs from the old file to the new file.
3784 If you even discuss something in the @code{ld} source, refer to it by
3785 context, not by line number.
3787 The line numbers in our development sources will not match those in your
3788 sources. Your line numbers would convey no useful information to us.
3791 Here are some things that are not necessary:
3795 A description of the envelope of the bug.
3797 Often people who encounter a bug spend a lot of time investigating
3798 which changes to the input file will make the bug go away and which
3799 changes will not affect it.
3801 This is often time consuming and not very useful, because the way we
3802 will find the bug is by running a single example under the debugger
3803 with breakpoints, not by pure deduction from a series of examples.
3804 We recommend that you save your time for something else.
3806 Of course, if you can find a simpler example to report @emph{instead}
3807 of the original one, that is a convenience for us. Errors in the
3808 output will be easier to spot, running under the debugger will take
3809 less time, and so on.
3811 However, simplification is not vital; if you do not want to do this,
3812 report the bug anyway and send us the entire test case you used.
3815 A patch for the bug.
3817 A patch for the bug does help us if it is a good one. But do not omit
3818 the necessary information, such as the test case, on the assumption that
3819 a patch is all we need. We might see problems with your patch and decide
3820 to fix the problem another way, or we might not understand it at all.
3822 Sometimes with a program as complicated as @code{ld} it is very hard to
3823 construct an example that will make the program follow a certain path
3824 through the code. If you do not send us the example, we will not be
3825 able to construct one, so we will not be able to verify that the bug is
3828 And if we cannot understand what bug you are trying to fix, or why your
3829 patch should be an improvement, we will not install it. A test case will
3830 help us to understand.
3833 A guess about what the bug is or what it depends on.
3835 Such guesses are usually wrong. Even we cannot guess right about such
3836 things without first using the debugger to find the facts.
3840 @appendix MRI Compatible Script Files
3841 @cindex MRI compatibility
3842 To aid users making the transition to @sc{gnu} @code{ld} from the MRI
3843 linker, @code{ld} can use MRI compatible linker scripts as an
3844 alternative to the more general-purpose linker scripting language
3845 described in @ref{Scripts}. MRI compatible linker scripts have a much
3846 simpler command set than the scripting language otherwise used with
3847 @code{ld}. @sc{gnu} @code{ld} supports the most commonly used MRI
3848 linker commands; these commands are described here.
3850 In general, MRI scripts aren't of much use with the @code{a.out} object
3851 file format, since it only has three sections and MRI scripts lack some
3852 features to make use of them.
3854 You can specify a file containing an MRI-compatible script using the
3855 @samp{-c} command-line option.
3857 Each command in an MRI-compatible script occupies its own line; each
3858 command line starts with the keyword that identifies the command (though
3859 blank lines are also allowed for punctuation). If a line of an
3860 MRI-compatible script begins with an unrecognized keyword, @code{ld}
3861 issues a warning message, but continues processing the script.
3863 Lines beginning with @samp{*} are comments.
3865 You can write these commands using all upper-case letters, or all
3866 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
3867 The following list shows only the upper-case form of each command.
3870 @cindex @code{ABSOLUTE} (MRI)
3871 @item ABSOLUTE @var{secname}
3872 @itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
3873 Normally, @code{ld} includes in the output file all sections from all
3874 the input files. However, in an MRI-compatible script, you can use the
3875 @code{ABSOLUTE} command to restrict the sections that will be present in
3876 your output program. If the @code{ABSOLUTE} command is used at all in a
3877 script, then only the sections named explicitly in @code{ABSOLUTE}
3878 commands will appear in the linker output. You can still use other
3879 input sections (whatever you select on the command line, or using
3880 @code{LOAD}) to resolve addresses in the output file.
3882 @cindex @code{ALIAS} (MRI)
3883 @item ALIAS @var{out-secname}, @var{in-secname}
3884 Use this command to place the data from input section @var{in-secname}
3885 in a section called @var{out-secname} in the linker output file.
3887 @var{in-secname} may be an integer.
3889 @cindex @code{ALIGN} (MRI)
3890 @item ALIGN @var{secname} = @var{expression}
3891 Align the section called @var{secname} to @var{expression}. The
3892 @var{expression} should be a power of two.
3894 @cindex @code{BASE} (MRI)
3895 @item BASE @var{expression}
3896 Use the value of @var{expression} as the lowest address (other than
3897 absolute addresses) in the output file.
3899 @cindex @code{CHIP} (MRI)
3900 @item CHIP @var{expression}
3901 @itemx CHIP @var{expression}, @var{expression}
3902 This command does nothing; it is accepted only for compatibility.
3904 @cindex @code{END} (MRI)
3906 This command does nothing whatever; it's only accepted for compatibility.
3908 @cindex @code{FORMAT} (MRI)
3909 @item FORMAT @var{output-format}
3910 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
3911 language, but restricted to one of these output formats:
3915 S-records, if @var{output-format} is @samp{S}
3918 IEEE, if @var{output-format} is @samp{IEEE}
3921 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
3925 @cindex @code{LIST} (MRI)
3926 @item LIST @var{anything}@dots{}
3927 Print (to the standard output file) a link map, as produced by the
3928 @code{ld} command-line option @samp{-M}.
3930 The keyword @code{LIST} may be followed by anything on the
3931 same line, with no change in its effect.
3933 @cindex @code{LOAD} (MRI)
3934 @item LOAD @var{filename}
3935 @itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
3936 Include one or more object file @var{filename} in the link; this has the
3937 same effect as specifying @var{filename} directly on the @code{ld}
3940 @cindex @code{NAME} (MRI)
3941 @item NAME @var{output-name}
3942 @var{output-name} is the name for the program produced by @code{ld}; the
3943 MRI-compatible command @code{NAME} is equivalent to the command-line
3944 option @samp{-o} or the general script language command @code{OUTPUT}.
3946 @cindex @code{ORDER} (MRI)
3947 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
3948 @itemx ORDER @var{secname} @var{secname} @var{secname}
3949 Normally, @code{ld} orders the sections in its output file in the
3950 order in which they first appear in the input files. In an MRI-compatible
3951 script, you can override this ordering with the @code{ORDER} command. The
3952 sections you list with @code{ORDER} will appear first in your output
3953 file, in the order specified.
3955 @cindex @code{PUBLIC} (MRI)
3956 @item PUBLIC @var{name}=@var{expression}
3957 @itemx PUBLIC @var{name},@var{expression}
3958 @itemx PUBLIC @var{name} @var{expression}
3959 Supply a value (@var{expression}) for external symbol
3960 @var{name} used in the linker input files.
3962 @cindex @code{SECT} (MRI)
3963 @item SECT @var{secname}, @var{expression}
3964 @itemx SECT @var{secname}=@var{expression}
3965 @itemx SECT @var{secname} @var{expression}
3966 You can use any of these three forms of the @code{SECT} command to
3967 specify the start address (@var{expression}) for section @var{secname}.
3968 If you have more than one @code{SECT} statement for the same
3969 @var{secname}, only the @emph{first} sets the start address.
3978 % I think something like @colophon should be in texinfo. In the
3980 \long\def\colophon{\hbox to0pt{}\vfill
3981 \centerline{The body of this manual is set in}
3982 \centerline{\fontname\tenrm,}
3983 \centerline{with headings in {\bf\fontname\tenbf}}
3984 \centerline{and examples in {\tt\fontname\tentt}.}
3985 \centerline{{\it\fontname\tenit\/} and}
3986 \centerline{{\sl\fontname\tensl\/}}
3987 \centerline{are used for emphasis.}\vfill}
3989 % Blame: doc@cygnus.com, 28mar91.