1: \input texinfo 2: @setfilename ld.info 3: @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 4: @c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 5: @syncodeindex ky cp 6: @c man begin INCLUDE 7: @include configdoc.texi 8: @c (configdoc.texi is generated by the Makefile) 9: @include bfdver.texi 10: @c man end 11: 12: @c @smallbook 13: 14: @macro gcctabopt{body} 15: @code{\body\} 16: @end macro 17: 18: @c man begin NAME 19: @ifset man 20: @c Configure for the generation of man pages 21: @set UsesEnvVars 22: @set GENERIC 23: @set ARM 24: @set H8300 25: @set HPPA 26: @set I960 27: @set M68HC11 28: @set MMIX 29: @set MSP430 30: @set POWERPC 31: @set POWERPC64 32: @set Renesas 33: @set SPU 34: @set TICOFF 35: @set WIN32 36: @set XTENSA 37: @end ifset 38: @c man end 39: 40: @ifinfo 41: @format 42: START-INFO-DIR-ENTRY 43: * Ld: (ld). The GNU linker. 44: END-INFO-DIR-ENTRY 45: @end format 46: @end ifinfo 47: 48: @copying 49: This file documents the @sc{gnu} linker LD 50: @ifset VERSION_PACKAGE 51: @value{VERSION_PACKAGE} 52: @end ifset 53: version @value{VERSION}. 54: 55: Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 56: 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 57: 58: Permission is granted to copy, distribute and/or modify this document 59: under the terms of the GNU Free Documentation License, Version 1.1 60: or any later version published by the Free Software Foundation; 61: with no Invariant Sections, with no Front-Cover Texts, and with no 62: Back-Cover Texts. A copy of the license is included in the 63: section entitled ``GNU Free Documentation License''. 64: @end copying 65: @iftex 66: @finalout 67: @setchapternewpage odd 68: @settitle The GNU linker 69: @titlepage 70: @title The GNU linker 71: @sp 1 72: @subtitle @code{ld} 73: @ifset VERSION_PACKAGE 74: @subtitle @value{VERSION_PACKAGE} 75: @end ifset 76: @subtitle Version @value{VERSION} 77: @author Steve Chamberlain 78: @author Ian Lance Taylor 79: @page 80: 81: @tex 82: {\parskip=0pt 83: \hfill Red Hat Inc\par 84: \hfill nickc\@credhat.com, doc\@redhat.com\par 85: \hfill {\it The GNU linker}\par 86: \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par 87: } 88: \global\parindent=0pt % Steve likes it this way. 89: @end tex 90: 91: @vskip 0pt plus 1filll 92: @c man begin COPYRIGHT 93: Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 94: 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 95: 96: Permission is granted to copy, distribute and/or modify this document 97: under the terms of the GNU Free Documentation License, Version 1.1 98: or any later version published by the Free Software Foundation; 99: with no Invariant Sections, with no Front-Cover Texts, and with no 100: Back-Cover Texts. A copy of the license is included in the 101: section entitled ``GNU Free Documentation License''. 102: @c man end 103: 104: @end titlepage 105: @end iftex 106: @contents 107: @c FIXME: Talk about importance of *order* of args, cmds to linker! 108: 109: @ifnottex 110: @node Top 111: @top LD 112: This file documents the @sc{gnu} linker ld 113: @ifset VERSION_PACKAGE 114: @value{VERSION_PACKAGE} 115: @end ifset 116: version @value{VERSION}. 117: 118: This document is distributed under the terms of the GNU Free 119: Documentation License. A copy of the license is included in the 120: section entitled ``GNU Free Documentation License''. 121: 122: @menu 123: * Overview:: Overview 124: * Invocation:: Invocation 125: * Scripts:: Linker Scripts 126: @ifset GENERIC 127: * Machine Dependent:: Machine Dependent Features 128: @end ifset 129: @ifclear GENERIC 130: @ifset H8300 131: * H8/300:: ld and the H8/300 132: @end ifset 133: @ifset Renesas 134: * Renesas:: ld and other Renesas micros 135: @end ifset 136: @ifset I960 137: * i960:: ld and the Intel 960 family 138: @end ifset 139: @ifset ARM 140: * ARM:: ld and the ARM family 141: @end ifset 142: @ifset HPPA 143: * HPPA ELF32:: ld and HPPA 32-bit ELF 144: @end ifset 145: @ifset M68HC11 146: * M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families 147: @end ifset 148: @ifset POWERPC 149: * PowerPC ELF32:: ld and PowerPC 32-bit ELF Support 150: @end ifset 151: @ifset POWERPC64 152: * PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support 153: @end ifset 154: @ifset SPU 155: * SPU ELF:: ld and SPU ELF Support 156: @end ifset 157: @ifset TICOFF 158: * TI COFF:: ld and the TI COFF 159: @end ifset 160: @ifset WIN32 161: * Win32:: ld and WIN32 (cygwin/mingw) 162: @end ifset 163: @ifset XTENSA 164: * Xtensa:: ld and Xtensa Processors 165: @end ifset 166: @end ifclear 167: @ifclear SingleFormat 168: * BFD:: BFD 169: @end ifclear 170: @c Following blank line required for remaining bug in makeinfo conds/menus 171: 172: * Reporting Bugs:: Reporting Bugs 173: * MRI:: MRI Compatible Script Files 174: * GNU Free Documentation License:: GNU Free Documentation License 175: * LD Index:: LD Index 176: @end menu 177: @end ifnottex 178: 179: @node Overview 180: @chapter Overview 181: 182: @cindex @sc{gnu} linker 183: @cindex what is this? 184: 185: @ifset man 186: @c man begin SYNOPSIS 187: ld [@b{options}] @var{objfile} @dots{} 188: @c man end 189: 190: @c man begin SEEALSO 191: ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and 192: the Info entries for @file{binutils} and 193: @file{ld}. 194: @c man end 195: @end ifset 196: 197: @c man begin DESCRIPTION 198: 199: @command{ld} combines a number of object and archive files, relocates 200: their data and ties up symbol references. Usually the last step in 201: compiling a program is to run @command{ld}. 202: 203: @command{ld} accepts Linker Command Language files written in 204: a superset of AT&T's Link Editor Command Language syntax, 205: to provide explicit and total control over the linking process. 206: 207: @ifset man 208: @c For the man only 209: This man page does not describe the command language; see the 210: @command{ld} entry in @code{info} for full details on the command 211: language and on other aspects of the GNU linker. 212: @end ifset 213: 214: @ifclear SingleFormat 215: This version of @command{ld} uses the general purpose BFD libraries 216: to operate on object files. This allows @command{ld} to read, combine, and 217: write object files in many different formats---for example, COFF or 218: @code{a.out}. Different formats may be linked together to produce any 219: available kind of object file. @xref{BFD}, for more information. 220: @end ifclear 221: 222: Aside from its flexibility, the @sc{gnu} linker is more helpful than other 223: linkers in providing diagnostic information. Many linkers abandon 224: execution immediately upon encountering an error; whenever possible, 225: @command{ld} continues executing, allowing you to identify other errors 226: (or, in some cases, to get an output file in spite of the error). 227: 228: @c man end 229: 230: @node Invocation 231: @chapter Invocation 232: 233: @c man begin DESCRIPTION 234: 235: The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations, 236: and to be as compatible as possible with other linkers. As a result, 237: you have many choices to control its behavior. 238: 239: @c man end 240: 241: @ifset UsesEnvVars 242: @menu 243: * Options:: Command Line Options 244: * Environment:: Environment Variables 245: @end menu 246: 247: @node Options 248: @section Command Line Options 249: @end ifset 250: 251: @cindex command line 252: @cindex options 253: 254: @c man begin OPTIONS 255: 256: The linker supports a plethora of command-line options, but in actual 257: practice few of them are used in any particular context. 258: @cindex standard Unix system 259: For instance, a frequent use of @command{ld} is to link standard Unix 260: object files on a standard, supported Unix system. On such a system, to 261: link a file @code{hello.o}: 262: 263: @smallexample 264: ld -o @var{output} /lib/crt0.o hello.o -lc 265: @end smallexample 266: 267: This tells @command{ld} to produce a file called @var{output} as the 268: result of linking the file @code{/lib/crt0.o} with @code{hello.o} and 269: the library @code{libc.a}, which will come from the standard search 270: directories. (See the discussion of the @samp{-l} option below.) 271: 272: Some of the command-line options to @command{ld} may be specified at any 273: point in the command line. However, options which refer to files, such 274: as @samp{-l} or @samp{-T}, cause the file to be read at the point at 275: which the option appears in the command line, relative to the object 276: files and other file options. Repeating non-file options with a 277: different argument will either have no further effect, or override prior 278: occurrences (those further to the left on the command line) of that 279: option. Options which may be meaningfully specified more than once are 280: noted in the descriptions below. 281: 282: @cindex object files 283: Non-option arguments are object files or archives which are to be linked 284: together. They may follow, precede, or be mixed in with command-line 285: options, except that an object file argument may not be placed between 286: an option and its argument. 287: 288: Usually the linker is invoked with at least one object file, but you can 289: specify other forms of binary input files using @samp{-l}, @samp{-R}, 290: and the script command language. If @emph{no} binary input files at all 291: are specified, the linker does not produce any output, and issues the 292: message @samp{No input files}. 293: 294: If the linker cannot recognize the format of an object file, it will 295: assume that it is a linker script. A script specified in this way 296: augments the main linker script used for the link (either the default 297: linker script or the one specified by using @samp{-T}). This feature 298: permits the linker to link against a file which appears to be an object 299: or an archive, but actually merely defines some symbol values, or uses 300: @code{INPUT} or @code{GROUP} to load other objects. Note that 301: specifying a script in this way merely augments the main linker script; 302: use the @samp{-T} option to replace the default linker script entirely. 303: @xref{Scripts}. 304: 305: For options whose names are a single letter, 306: option arguments must either follow the option letter without intervening 307: whitespace, or be given as separate arguments immediately following the 308: option that requires them. 309: 310: For options whose names are multiple letters, either one dash or two can 311: precede the option name; for example, @samp{-trace-symbol} and 312: @samp{--trace-symbol} are equivalent. Note---there is one exception to 313: this rule. Multiple letter options that start with a lower case 'o' can 314: only be preceded by two dashes. This is to reduce confusion with the 315: @samp{-o} option. So for example @samp{-omagic} sets the output file 316: name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the 317: output. 318: 319: Arguments to multiple-letter options must either be separated from the 320: option name by an equals sign, or be given as separate arguments 321: immediately following the option that requires them. For example, 322: @samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent. 323: Unique abbreviations of the names of multiple-letter options are 324: accepted. 325: 326: Note---if the linker is being invoked indirectly, via a compiler driver 327: (e.g. @samp{gcc}) then all the linker command line options should be 328: prefixed by @samp{-Wl,} (or whatever is appropriate for the particular 329: compiler driver) like this: 330: 331: @smallexample 332: gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup 333: @end smallexample 334: 335: This is important, because otherwise the compiler driver program may 336: silently drop the linker options, resulting in a bad link. 337: 338: Here is a table of the generic command line switches accepted by the GNU 339: linker: 340: 341: @table @gcctabopt 342: @include at-file.texi 343: 344: @kindex -a@var{keyword} 345: @item -a@var{keyword} 346: This option is supported for HP/UX compatibility. The @var{keyword} 347: argument must be one of the strings @samp{archive}, @samp{shared}, or 348: @samp{default}. @samp{-aarchive} is functionally equivalent to 349: @samp{-Bstatic}, and the other two keywords are functionally equivalent 350: to @samp{-Bdynamic}. This option may be used any number of times. 351: 352: @ifset I960 353: @cindex architectures 354: @kindex -A@var{arch} 355: @item -A@var{architecture} 356: @kindex --architecture=@var{arch} 357: @itemx --architecture=@var{architecture} 358: In the current release of @command{ld}, this option is useful only for the 359: Intel 960 family of architectures. In that @command{ld} configuration, the 360: @var{architecture} argument identifies the particular architecture in 361: the 960 family, enabling some safeguards and modifying the 362: archive-library search path. @xref{i960,,@command{ld} and the Intel 960 363: family}, for details. 364: 365: Future releases of @command{ld} may support similar functionality for 366: other architecture families. 367: @end ifset 368: 369: @ifclear SingleFormat 370: @cindex binary input format 371: @kindex -b @var{format} 372: @kindex --format=@var{format} 373: @cindex input format 374: @cindex input format 375: @item -b @var{input-format} 376: @itemx --format=@var{input-format} 377: @command{ld} may be configured to support more than one kind of object 378: file. If your @command{ld} is configured this way, you can use the 379: @samp{-b} option to specify the binary format for input object files 380: that follow this option on the command line. Even when @command{ld} is 381: configured to support alternative object formats, you don't usually need 382: to specify this, as @command{ld} should be configured to expect as a 383: default input format the most usual format on each machine. 384: @var{input-format} is a text string, the name of a particular format 385: supported by the BFD libraries. (You can list the available binary 386: formats with @samp{objdump -i}.) 387: @xref{BFD}. 388: 389: You may want to use this option if you are linking files with an unusual 390: binary format. You can also use @samp{-b} to switch formats explicitly (when 391: linking object files of different formats), by including 392: @samp{-b @var{input-format}} before each group of object files in a 393: particular format. 394: 395: The default format is taken from the environment variable 396: @code{GNUTARGET}. 397: @ifset UsesEnvVars 398: @xref{Environment}. 399: @end ifset 400: You can also define the input format from a script, using the command 401: @code{TARGET}; 402: @ifclear man 403: see @ref{Format Commands}. 404: @end ifclear 405: @end ifclear 406: 407: @kindex -c @var{MRI-cmdfile} 408: @kindex --mri-script=@var{MRI-cmdfile} 409: @cindex compatibility, MRI 410: @item -c @var{MRI-commandfile} 411: @itemx --mri-script=@var{MRI-commandfile} 412: For compatibility with linkers produced by MRI, @command{ld} accepts script 413: files written in an alternate, restricted command language, described in 414: @ifclear man 415: @ref{MRI,,MRI Compatible Script Files}. 416: @end ifclear 417: @ifset man 418: the MRI Compatible Script Files section of GNU ld documentation. 419: @end ifset 420: Introduce MRI script files with 421: the option @samp{-c}; use the @samp{-T} option to run linker 422: scripts written in the general-purpose @command{ld} scripting language. 423: If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories 424: specified by any @samp{-L} options. 425: 426: @cindex common allocation 427: @kindex -d 428: @kindex -dc 429: @kindex -dp 430: @item -d 431: @itemx -dc 432: @itemx -dp 433: These three options are equivalent; multiple forms are supported for 434: compatibility with other linkers. They assign space to common symbols 435: even if a relocatable output file is specified (with @samp{-r}). The 436: script command @code{FORCE_COMMON_ALLOCATION} has the same effect. 437: @xref{Miscellaneous Commands}. 438: 439: @cindex entry point, from command line 440: @kindex -e @var{entry} 441: @kindex --entry=@var{entry} 442: @item -e @var{entry} 443: @itemx --entry=@var{entry} 444: Use @var{entry} as the explicit symbol for beginning execution of your 445: program, rather than the default entry point. If there is no symbol 446: named @var{entry}, the linker will try to parse @var{entry} as a number, 447: and use that as the entry address (the number will be interpreted in 448: base 10; you may use a leading @samp{0x} for base 16, or a leading 449: @samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults 450: and other ways of specifying the entry point. 451: 452: @kindex --exclude-libs 453: @item --exclude-libs @var{lib},@var{lib},... 454: Specifies a list of archive libraries from which symbols should not be automatically 455: exported. The library names may be delimited by commas or colons. Specifying 456: @code{--exclude-libs ALL} excludes symbols in all archive libraries from 457: automatic export. This option is available only for the i386 PE targeted 458: port of the linker and for ELF targeted ports. For i386 PE, symbols 459: explicitly listed in a .def file are still exported, regardless of this 460: option. For ELF targeted ports, symbols affected by this option will 461: be treated as hidden. 462: 463: @cindex dynamic symbol table 464: @kindex -E 465: @kindex --export-dynamic 466: @item -E 467: @itemx --export-dynamic 468: When creating a dynamically linked executable, add all symbols to the 469: dynamic symbol table. The dynamic symbol table is the set of symbols 470: which are visible from dynamic objects at run time. 471: 472: If you do not use this option, the dynamic symbol table will normally 473: contain only those symbols which are referenced by some dynamic object 474: mentioned in the link. 475: 476: If you use @code{dlopen} to load a dynamic object which needs to refer 477: back to the symbols defined by the program, rather than some other 478: dynamic object, then you will probably need to use this option when 479: linking the program itself. 480: 481: You can also use the dynamic list to control what symbols should 482: be added to the dynamic symbol table if the output format supports it. 483: See the description of @samp{--dynamic-list}. 484: 485: @ifclear SingleFormat 486: @cindex big-endian objects 487: @cindex endianness 488: @kindex -EB 489: @item -EB 490: Link big-endian objects. This affects the default output format. 491: 492: @cindex little-endian objects 493: @kindex -EL 494: @item -EL 495: Link little-endian objects. This affects the default output format. 496: @end ifclear 497: 498: @kindex -f 499: @kindex --auxiliary 500: @item -f 501: @itemx --auxiliary @var{name} 502: When creating an ELF shared object, set the internal DT_AUXILIARY field 503: to the specified name. This tells the dynamic linker that the symbol 504: table of the shared object should be used as an auxiliary filter on the 505: symbol table of the shared object @var{name}. 506: 507: If you later link a program against this filter object, then, when you 508: run the program, the dynamic linker will see the DT_AUXILIARY field. If 509: the dynamic linker resolves any symbols from the filter object, it will 510: first check whether there is a definition in the shared object 511: @var{name}. If there is one, it will be used instead of the definition 512: in the filter object. The shared object @var{name} need not exist. 513: Thus the shared object @var{name} may be used to provide an alternative 514: implementation of certain functions, perhaps for debugging or for 515: machine specific performance. 516: 517: This option may be specified more than once. The DT_AUXILIARY entries 518: will be created in the order in which they appear on the command line. 519: 520: @kindex -F 521: @kindex --filter 522: @item -F @var{name} 523: @itemx --filter @var{name} 524: When creating an ELF shared object, set the internal DT_FILTER field to 525: the specified name. This tells the dynamic linker that the symbol table 526: of the shared object which is being created should be used as a filter 527: on the symbol table of the shared object @var{name}. 528: 529: If you later link a program against this filter object, then, when you 530: run the program, the dynamic linker will see the DT_FILTER field. The 531: dynamic linker will resolve symbols according to the symbol table of the 532: filter object as usual, but it will actually link to the definitions 533: found in the shared object @var{name}. Thus the filter object can be 534: used to select a subset of the symbols provided by the object 535: @var{name}. 536: 537: Some older linkers used the @option{-F} option throughout a compilation 538: toolchain for specifying object-file format for both input and output 539: object files. 540: @ifclear SingleFormat 541: The @sc{gnu} linker uses other mechanisms for this purpose: the 542: @option{-b}, @option{--format}, @option{--oformat} options, the 543: @code{TARGET} command in linker scripts, and the @code{GNUTARGET} 544: environment variable. 545: @end ifclear 546: The @sc{gnu} linker will ignore the @option{-F} option when not 547: creating an ELF shared object. 548: 549: @cindex finalization function 550: @kindex -fini 551: @item -fini @var{name} 552: When creating an ELF executable or shared object, call NAME when the 553: executable or shared object is unloaded, by setting DT_FINI to the 554: address of the function. By default, the linker uses @code{_fini} as 555: the function to call. 556: 557: @kindex -g 558: @item -g 559: Ignored. Provided for compatibility with other tools. 560: 561: @kindex -G 562: @kindex --gpsize 563: @cindex object size 564: @item -G@var{value} 565: @itemx --gpsize=@var{value} 566: Set the maximum size of objects to be optimized using the GP register to 567: @var{size}. This is only meaningful for object file formats such as 568: MIPS ECOFF which supports putting large and small objects into different 569: sections. This is ignored for other object file formats. 570: 571: @cindex runtime library name 572: @kindex -h@var{name} 573: @kindex -soname=@var{name} 574: @item -h@var{name} 575: @itemx -soname=@var{name} 576: When creating an ELF shared object, set the internal DT_SONAME field to 577: the specified name. When an executable is linked with a shared object 578: which has a DT_SONAME field, then when the executable is run the dynamic 579: linker will attempt to load the shared object specified by the DT_SONAME 580: field rather than the using the file name given to the linker. 581: 582: @kindex -i 583: @cindex incremental link 584: @item -i 585: Perform an incremental link (same as option @samp{-r}). 586: 587: @cindex initialization function 588: @kindex -init 589: @item -init @var{name} 590: When creating an ELF executable or shared object, call NAME when the 591: executable or shared object is loaded, by setting DT_INIT to the address 592: of the function. By default, the linker uses @code{_init} as the 593: function to call. 594: 595: @cindex archive files, from cmd line 596: @kindex -l@var{namespec} 597: @kindex --library=@var{namespec} 598: @item -l@var{namespec} 599: @itemx --library=@var{namespec} 600: Add the archive or object file specified by @var{namespec} to the 601: list of files to link. This option may be used any number of times. 602: If @var{namespec} is of the form @file{:@var{filename}}, @command{ld} 603: will search the library path for a file called @var{filename}, otherise it 604: will search the library path for a file called @file{lib@var{namespec}.a}. 605: 606: On systems which support shared libraries, @command{ld} may also search for 607: files other than @file{lib@var{namespec}.a}. Specifically, on ELF 608: and SunOS systems, @command{ld} will search a directory for a library 609: called @file{lib@var{namespec}.so} before searching for one called 610: @file{lib@var{namespec}.a}. (By convention, a @code{.so} extension 611: indicates a shared library.) Note that this behavior does not apply 612: to @file{:@var{filename}}, which always specifies a file called 613: @var{filename}. 614: 615: The linker will search an archive only once, at the location where it is 616: specified on the command line. If the archive defines a symbol which 617: was undefined in some object which appeared before the archive on the 618: command line, the linker will include the appropriate file(s) from the 619: archive. However, an undefined symbol in an object appearing later on 620: the command line will not cause the linker to search the archive again. 621: 622: See the @option{-(} option for a way to force the linker to search 623: archives multiple times. 624: 625: You may list the same archive multiple times on the command line. 626: 627: @ifset GENERIC 628: This type of archive searching is standard for Unix linkers. However, 629: if you are using @command{ld} on AIX, note that it is different from the 630: behaviour of the AIX linker. 631: @end ifset 632: 633: @cindex search directory, from cmd line 634: @kindex -L@var{dir} 635: @kindex --library-path=@var{dir} 636: @item -L@var{searchdir} 637: @itemx --library-path=@var{searchdir} 638: Add path @var{searchdir} to the list of paths that @command{ld} will search 639: for archive libraries and @command{ld} control scripts. You may use this 640: option any number of times. The directories are searched in the order 641: in which they are specified on the command line. Directories specified 642: on the command line are searched before the default directories. All 643: @option{-L} options apply to all @option{-l} options, regardless of the 644: order in which the options appear. 645: 646: If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced 647: by the @dfn{sysroot prefix}, a path specified when the linker is configured. 648: 649: @ifset UsesEnvVars 650: The default set of paths searched (without being specified with 651: @samp{-L}) depends on which emulation mode @command{ld} is using, and in 652: some cases also on how it was configured. @xref{Environment}. 653: @end ifset 654: 655: The paths can also be specified in a link script with the 656: @code{SEARCH_DIR} command. Directories specified this way are searched 657: at the point in which the linker script appears in the command line. 658: 659: @cindex emulation 660: @kindex -m @var{emulation} 661: @item -m@var{emulation} 662: Emulate the @var{emulation} linker. You can list the available 663: emulations with the @samp{--verbose} or @samp{-V} options. 664: 665: If the @samp{-m} option is not used, the emulation is taken from the 666: @code{LDEMULATION} environment variable, if that is defined. 667: 668: Otherwise, the default emulation depends upon how the linker was 669: configured. 670: 671: @cindex link map 672: @kindex -M 673: @kindex --print-map 674: @item -M 675: @itemx --print-map 676: Print a link map to the standard output. A link map provides 677: information about the link, including the following: 678: 679: @itemize @bullet 680: @item 681: Where object files are mapped into memory. 682: @item 683: How common symbols are allocated. 684: @item 685: All archive members included in the link, with a mention of the symbol 686: which caused the archive member to be brought in. 687: @item 688: The values assigned to symbols. 689: 690: Note - symbols whose values are computed by an expression which 691: involves a reference to a previous value of the same symbol may not 692: have correct result displayed in the link map. This is because the 693: linker discards intermediate results and only retains the final value 694: of an expression. Under such circumstances the linker will display 695: the final value enclosed by square brackets. Thus for example a 696: linker script containing: 697: 698: @smallexample 699: foo = 1 700: foo = foo * 4 701: foo = foo + 8 702: @end smallexample 703: 704: will produce the following output in the link map if the @option{-M} 705: option is used: 706: 707: @smallexample 708: 0x00000001 foo = 0x1 709: [0x0000000c] foo = (foo * 0x4) 710: [0x0000000c] foo = (foo + 0x8) 711: @end smallexample 712: 713: See @ref{Expressions} for more information about expressions in linker 714: scripts. 715: @end itemize 716: 717: @kindex -n 718: @cindex read-only text 719: @cindex NMAGIC 720: @kindex --nmagic 721: @item -n 722: @itemx --nmagic 723: Turn off page alignment of sections, and mark the output as 724: @code{NMAGIC} if possible. 725: 726: @kindex -N 727: @kindex --omagic 728: @cindex read/write from cmd line 729: @cindex OMAGIC 730: @item -N 731: @itemx --omagic 732: Set the text and data sections to be readable and writable. Also, do 733: not page-align the data segment, and disable linking against shared 734: libraries. If the output format supports Unix style magic numbers, 735: mark the output as @code{OMAGIC}. Note: Although a writable text section 736: is allowed for PE-COFF targets, it does not conform to the format 737: specification published by Microsoft. 738: 739: @kindex --no-omagic 740: @cindex OMAGIC 741: @item --no-omagic 742: This option negates most of the effects of the @option{-N} option. It 743: sets the text section to be read-only, and forces the data segment to 744: be page-aligned. Note - this option does not enable linking against 745: shared libraries. Use @option{-Bdynamic} for this. 746: 747: @kindex -o @var{output} 748: @kindex --output=@var{output} 749: @cindex naming the output file 750: @item -o @var{output} 751: @itemx --output=@var{output} 752: Use @var{output} as the name for the program produced by @command{ld}; if this 753: option is not specified, the name @file{a.out} is used by default. The 754: script command @code{OUTPUT} can also specify the output file name. 755: 756: @kindex -O @var{level} 757: @cindex generating optimized output 758: @item -O @var{level} 759: If @var{level} is a numeric values greater than zero @command{ld} optimizes 760: the output. This might take significantly longer and therefore probably 761: should only be enabled for the final binary. At the moment this 762: option only affects ELF shared library generation. Future releases of 763: the linker may make more use of this option. Also currently there is 764: no difference in the linker's behaviour for different non-zero values 765: of this option. Again this may change with future releases. 766: 767: @kindex -q 768: @kindex --emit-relocs 769: @cindex retain relocations in final executable 770: @item -q 771: @itemx --emit-relocs 772: Leave relocation sections and contents in fully linked executables. 773: Post link analysis and optimization tools may need this information in