ld/ld.1

   1 .\" Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation
   2 .\" See section COPYING for conditions for redistribution
   3 .TH ld 1 "17 August 1992" "cygnus support" "GNU Development Tools"
   4 .de BP
   5 .sp
   6 .ti \-.2i
   7 \(**
   8 ..
   9
  10 .SH NAME
  11 ld \- the GNU linker
  12
  13 .SH SYNOPSIS
  14 .hy 0
  15 .na
  16 .TP
  17 .B ld
  18 .RB "[\|" \-o "
  19 .I output\c
  20 \&\|] \c
  21 .I objfile\c
  22 \&.\|.\|.
  23 .br
  24 .RB "[\|" \-A\c
  25 .I architecture\c
  26 \&\|]
  27 .RB "[\|" "\-b\ "\c
  28 .I input-format\c
  29 \&\|]
  30 .RB "[\|" \-Bstatic "\|]"
  31 .RB "[\|" \-Bdynamic "\|]"
  32 .RB "[\|" \-Bsymbolic "\|]"
  33 .RB "[\|" "\-c\ "\c
  34 .I commandfile\c
  35 \&\|]
  36 .RB "[\|" \-\-cref "\|]"
  37 .RB "[\|" \-d | \-dc | \-dp\c
  38 \|]
  39 .br
  40 .RB "[\|" "\-defsym\ "\c
  41 .I symbol\c
  42 \&=\c
  43 .I expression\c
  44 \&\|]
  45 .RB "[\|" \-\-demangle "\|]"
  46 .RB "[\|" \-\-no\-demangle "\|]"
  47 .RB "[\|" "\-e\ "\c
  48 .I entry\c
  49 \&\|]
  50 .RB "[\|" \-embedded\-relocs "\|]"
  51 .RB "[\|" \-E "\|]"
  52 .RB "[\|" \-export\-dynamic "\|]"
  53 .RB "[\|" "\-f\ "\c
  54 .I name\c
  55 \&\|]
  56 .RB "[\|" "\-\-auxiliary\ "\c
  57 .I name\c
  58 \&\|]
  59 .RB "[\|" "\-F\ "\c
  60 .I name\c
  61 \&\|]
  62 .RB "[\|" "\-\-filter\ "\c
  63 .I name\c
  64 \&\|]
  65 .RB "[\|" "\-format\ "\c
  66 .I input-format\c
  67 \&\|]
  68 .RB "[\|" \-g "\|]"
  69 .RB "[\|" \-G
  70 .I size\c
  71 \&\|]
  72 .RB "[\|" "\-h\ "\c
  73 .I name\c
  74 \&\|]
  75 .RB "[\|" "\-soname\ "\c
  76 .I name\c
  77 \&\|]
  78 .RB "[\|" \-\-help "\|]"
  79 .RB "[\|" \-i "\|]"
  80 .RB "[\|" \-l\c
  81 .I ar\c
  82 \&\|]
  83 .RB "[\|" \-L\c
  84 .I searchdir\c
  85 \&\|]
  86 .RB "[\|" \-M "\|]"
  87 .RB "[\|" \-Map
  88 .I mapfile\c
  89 \&\|]
  90 .RB "[\|" \-m
  91 .I emulation\c
  92 \&\|]
  93 .RB "[\|" \-n | \-N "\|]"
  94 .RB "[\|" \-noinhibit-exec "\|]"
  95 .RB "[\|" \-no\-keep\-memory "\|]"
  96 .RB "[\|" \-no\-warn\-mismatch "\|]"
  97 .RB "[\|" \-O\c
  98 .I level\c
  99 \&\|]
 100 .RB "[\|" "\-oformat\ "\c
 101 .I output-format\c
 102 \&\|]
 103 .RB "[\|" "\-R\ "\c
 104 .I filename\c
 105 \&\|]
 106 .RB "[\|" \-relax "\|]"
 107 .RB "[\|" \-r | \-Ur "\|]"
 108 .RB "[\|" "\-rpath\ "\c
 109 .I directory\c
 110 \&\|]
 111 .RB "[\|" "\-rpath\-link\ "\c
 112 .I directory\c
 113 \&\|]
 114 .RB "[\|" \-S "\|]"
 115 .RB "[\|" \-s "\|]"
 116 .RB "[\|" \-shared "\|]"
 117 .RB "[\|" \-sort\-common "\|]"
 118 .RB "[\|" "\-split\-by\-reloc\ "\c
 119 .I count\c
 120 \&\|]
 121 .RB "[\|" \-split\-by\-file "\|]"
 122 .RB "[\|" "\-T\ "\c
 123 .I commandfile\c
 124 \&\|]
 125 .RB "[\|" "\-\-section\-start\ "\c
 126 .I sectionname\c
 127 \&=\c
 128 .I sectionorg\c
 129 \&\|]
 130 .RB "[\|" "\-Ttext\ "\c
 131 .I textorg\c
 132 \&\|]
 133 .RB "[\|" "\-Tdata\ "\c
 134 .I dataorg\c
 135 \&\|]
 136 .RB "[\|" "\-Tbss\ "\c
 137 .I bssorg\c
 138 \&\|]
 139 .RB "[\|" \-t "\|]"
 140 .RB "[\|" "\-u\ "\c
 141 .I sym\c
 142 \&]
 143 .RB "[\|" \-V "\|]"
 144 .RB "[\|" \-v "\|]"
 145 .RB "[\|" \-\-verbose "\|]"
 146 .RB "[\|" \-\-version "\|]"
 147 .RB "[\|" \-warn\-common "\|]"
 148 .RB "[\|" \-warn\-constructors "\|]"
 149 .RB "[\|" \-warn\-multiple\-gp "\|]"
 150 .RB "[\|" \-warn\-once "\|]"
 151 .RB "[\|" \-warn\-section\-align "\|]"
 152 .RB "[\|" \-\-whole\-archive "\|]"
 153 .RB "[\|" \-\-no\-whole\-archive "\|]"
 154 .RB "[\|" "\-\-wrap\ "\c
 155 .I symbol\c
 156 \&\|]
 157 .RB "[\|" \-X "\|]"
 158 .RB "[\|" \-x "\|]"
 159 .ad b
 160 .hy 1
 161 .SH DESCRIPTION
 162 \c
 163 .B ld\c
 164 \& combines a number of object and archive files, relocates
 165 their data and ties up symbol references. Often the last step in
 166 building a new compiled program to run is a call to \c
 167 .B ld\c
 168 \&.
 169
 170 \c
 171 .B ld\c
 172 \& accepts Linker Command Language files
 173 to provide explicit and total control over the linking process.
 174 This man page does not describe the command language; see the `\|\c
 175 .B ld\c
 176 \|' entry in `\|\c
 177 .B info\c
 178 \|', or the manual
 179 .I
 180 ld: the GNU linker
 181 \&, for full details on the command language and on other aspects of
 182 the GNU linker.
 183
 184 This version of \c
 185 .B ld\c
 186 \& uses the general purpose BFD libraries
 187 to operate on object files. This allows \c
 188 .B ld\c
 189 \& to read, combine, and
 190 write object files in many different formats\(em\&for example, COFF or
 191 \c
 192 .B a.out\c
 193 \&.  Different formats may be linked together to produce any
 194 available kind of object file.  You can use `\|\c
 195 .B objdump \-i\c
 196 \|' to get a list of formats supported on various architectures; see
 197 .BR objdump ( 1 ).
 198
 199 Aside from its flexibility, the GNU linker is more helpful than other
 200 linkers in providing diagnostic information.  Many linkers abandon
 201 execution immediately upon encountering an error; whenever possible,
 202 \c
 203 .B ld\c
 204 \& continues executing, allowing you to identify other errors
 205 (or, in some cases, to get an output file in spite of the error).
 206
 207 The GNU linker \c
 208 .B ld\c
 209 \& is meant to cover a broad range of situations,
 210 and to be as compatible as possible with other linkers.  As a result,
 211 you have many choices to control its behavior through the command line,
 212 and through environment variables.
 213
 214 .SH OPTIONS
 215 The plethora of command-line options may seem intimidating, but in
 216 actual practice few of them are used in any particular context.
 217 For instance, a frequent use of \c
 218 .B ld\c
 219 \& is to link standard Unix
 220 object files on a standard, supported Unix system.  On such a system, to
 221 link a file \c
 222 .B hello.o\c
 223 \&:
 224 .sp
 225 .br
 226 $\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
 227 .br
 228 .sp
 229 This tells \c
 230 .B ld\c
 231 \& to produce a file called \c
 232 .B output\c
 233 \& as the
 234 result of linking the file \c
 235 .B /lib/crt0.o\c
 236 \& with \c
 237 .B hello.o\c
 238 \& and
 239 the library \c
 240 .B libc.a\c
 241 \& which will come from the standard search
 242 directories.
 243
 244 The command-line options to \c
 245 .B ld\c
 246 \& may be specified in any order, and
 247 may be repeated at will.  For the most part, repeating an option with a
 248 different argument will either have no further effect, or override prior
 249 occurrences (those further to the left on the command line) of an
 250 option.
 251
 252 The exceptions\(em\&which may meaningfully be used more than once\(em\&are
 253 \c
 254 .B \-A\c
 255 \&, \c
 256 .B \-b\c
 257 \& (or its synonym \c
 258 .B \-format\c
 259 \&), \c
 260 .B \-defsym\c
 261 \&, \c
 262 .B \-\-section\-start\c
 263 \&, \c
 264 .B \-L\c
 265 \&, \c
 266 .B \-l\c
 267 \&, \c
 268 .B \-R\c
 269 \&, and \c
 270 .B \-u\c
 271 \&.
 272
 273 The list of object files to be linked together, shown as \c
 274 .I objfile\c
 275 \&,
 276 may follow, precede, or be mixed in with command-line options; save that
 277 an \c
 278 .I objfile\c
 279 \& argument may not be placed between an option flag and
 280 its argument.
 281
 282 Usually the linker is invoked with at least one object file, but other
 283 forms of binary input files can also be specified with \c
 284 .B \-l\c
 285 \&,
 286 \c
 287 .B \-R\c
 288 \&, and the script command language.  If \c
 289 .I no\c
 290 \& binary input
 291 files at all are specified, the linker does not produce any output, and
 292 issues the message `\|\c
 293 .B No input files\c
 294 \|'.
 295
 296 Option arguments must either follow the option letter without intervening
 297 whitespace, or be given as separate arguments immediately following the
 298 option that requires them.
 299
 300 .TP
 301 .BI "-A" "architecture"
 302 In the current release of \c
 303 .B ld\c
 304 \&, this option is useful only for the
 305 Intel 960 family of architectures.  In that \c
 306 .B ld\c
 307 \& configuration, the
 308 \c
 309 .I architecture\c
 310 \& argument is one of the two-letter names identifying
 311 members of the 960 family; the option specifies the desired output
 312 target, and warns of any incompatible instructions in the input files.
 313 It also modifies the linker's search strategy for archive libraries, to
 314 support the use of libraries specific to each particular
 315 architecture, by including in the search loop names suffixed with the
 316 string identifying the architecture.
 317
 318 For example, if your \c
 319 .B ld\c
 320 \& command line included `\|\c
 321 .B \-ACA\c
 322 \|' as
 323 well as `\|\c
 324 .B \-ltry\c
 325 \|', the linker would look (in its built-in search
 326 paths, and in any paths you specify with \c
 327 .B \-L\c
 328 \&) for a library with
 329 the names
 330 .sp
 331 .br
 332 try
 333 .br
 334 libtry.a
 335 .br
 336 tryca
 337 .br
 338 libtryca.a
 339 .br
 340 .sp
 341
 342 The first two possibilities would be considered in any event; the last
 343 two are due to the use of `\|\c
 344 .B \-ACA\c
 345 \|'.
 346
 347 Future releases of \c
 348 .B ld\c
 349 \& may support similar functionality for
 350 other architecture families.
 351
 352 You can meaningfully use \c
 353 .B \-A\c
 354 \& more than once on a command line, if
 355 an architecture family allows combination of target architectures; each
 356 use will add another pair of name variants to search for when \c
 357 .B \-l
 358 specifies a library.
 359
 360 .TP
 361 .BI "\-b " "input-format"
 362 Specify the binary format for input object files that follow this option
 363 on the command line.  You don't usually need to specify this, as
 364 \c
 365 .B ld\c
 366 \& is configured to expect as a default input format the most
 367 usual format on each machine.  \c
 368 .I input-format\c
 369 \& is a text string, the
 370 name of a particular format supported by the BFD libraries.
 371 \c
 372 .B \-format \c
 373 .I input-format\c
 374 \&\c
 375 \& has the same effect, as does the script command
 376 .BR TARGET .
 377
 378 You may want to use this option if you are linking files with an unusual
 379 binary format.  You can also use \c
 380 .B \-b\c
 381 \& to switch formats explicitly (when
 382 linking object files of different formats), by including
 383 \c
 384 .B \-b \c
 385 .I input-format\c
 386 \&\c
 387 \& before each group of object files in a
 388 particular format.
 389
 390 The default format is taken from the environment variable
 391 .B GNUTARGET\c
 392 \&.  You can also define the input
 393 format from a script, using the command \c
 394 .B TARGET\c
 395 \&.
 396
 397 .TP
 398 .B \-Bstatic
 399 Do not link against shared libraries.  This is only meaningful on
 400 platforms for which shared libraries are supported.
 401
 402 .TP
 403 .B \-Bdynamic
 404 Link against dynamic libraries.  This is only meaningful on platforms
 405 for which shared libraries are supported.  This option is normally the
 406 default on such platforms.
 407
 408 .TP
 409 .B \-Bsymbolic
 410 When creating a shared library, bind references to global symbols to
 411 the definition within the shared library, if any.  Normally, it is
 412 possible for a program linked against a shared library to override the
 413 definition within the shared library.  This option is only meaningful
 414 on ELF platforms which support shared libraries.
 415
 416 .TP
 417 .BI "\-c " "commandfile"
 418 Directs \c
 419 .B ld\c
 420 \& to read link commands from the file
 421 \c
 422 .I commandfile\c
 423 \&.  These commands will completely override \c
 424 .B ld\c
 425 \&'s
 426 default link format (rather than adding to it); \c
 427 .I commandfile\c
 428 \& must
 429 specify everything necessary to describe the target format.
 430
 431
 432 You may also include a script of link commands directly in the command
 433 line by bracketing it between `\|\c
 434 .B {\c
 435 \|' and `\|\c
 436 .B }\c
 437 \|' characters.
 438
 439 .TP
 440 .B \-\-cref
 441 Output a cross reference table.  If a linker map file is being
 442 generated, the cross reference table is printed to the map file.
 443 Otherwise, it is printed on the standard output.
 444
 445 .TP
 446 .B \-d
 447 .TP
 448 .B \-dc
 449 .TP
 450 .B \-dp
 451 These three options are equivalent; multiple forms are supported for
 452 compatibility with other linkers.  Use any of them to make \c
 453 .B ld
 454 assign space to common symbols even if a relocatable output file is
 455 specified (\c
 456 .B \-r\c
 457 \&).  The script command
 458 \c
 459 .B FORCE_COMMON_ALLOCATION\c
 460 \& has the same effect.
 461
 462 .TP
 463 .BI "-defsym " "symbol" "\fR=\fP" expression
 464 Create a global symbol in the output file, containing the absolute
 465 address given by \c
 466 .I expression\c
 467 \&.  You may use this option as many
 468 times as necessary to define multiple symbols in the command line.  A
 469 limited form of arithmetic is supported for the \c
 470 .I expression\c
 471 \& in this
 472 context: you may give a hexadecimal constant or the name of an existing
 473 symbol, or use \c
 474 .B +\c
 475 \& and \c
 476 .B \-\c
 477 \& to add or subtract hexadecimal
 478 constants or symbols.  If you need more elaborate expressions, consider
 479 using the linker command language from a script.
 480
 481 .TP
 482 .B \-\-demangle
 483 .TP
 484 .B \-\-no\-demangle
 485 These options control whether to demangle symbol names in error
 486 messages and other output.  When the linker is told to demangle, it
 487 tries to present symbol names in a readable fashion: it strips leading
 488 underscores if they are used by the object file format, and converts
 489 C++ mangled symbol names into user readable names.  The linker will
 490 demangle by default unless the environment variable
 491 .B COLLECT_NO_DEMANGLE
 492 is set.  These options may be used to override the default.
 493
 494 .TP
 495 .BI "-e " "entry"\c
 496 \&
 497 Use \c
 498 .I entry\c
 499 \& as the explicit symbol for beginning execution of your
 500 program, rather than the default entry point.  See the `\|\c
 501 .B ld\c
 502 \|' entry in `\|\c
 503 .B info\c
 504 \|' for a
 505 discussion of defaults and other ways of specifying the
 506 entry point.
 507
 508 .TP
 509 .B \-embedded\-relocs
 510 This option is only meaningful when linking MIPS embedded PIC code,
 511 generated by the
 512 .B \-membedded\-pic
 513 option to the GNU compiler and assembler.  It causes the linker to
 514 create a table which may be used at runtime to relocate any data which
 515 was statically initialized to pointer values.  See the code in
 516 testsuite/ld-empic for details.
 517
 518 .TP
 519 .B \-E
 520 .TP
 521 .B \-export\-dynamic
 522 When creating an ELF file, add all symbols to the dynamic symbol table.
 523 Normally, the dynamic symbol table contains only symbols which are used
 524 by a dynamic object.  This option is needed for some uses of
 525 .I dlopen.
 526
 527 .TP
 528 .BI "-f " "name"
 529 .TP
 530 .BI "--auxiliary " "name"
 531 When creating an ELF shared object, set the internal DT_AUXILIARY field
 532 to the specified name.  This tells the dynamic linker that the symbol
 533 table of the shared object should be used as an auxiliary filter on the
 534 symbol table of the shared object
 535 .I name.
 536
 537 .TP
 538 .BI "-F " "name"
 539 .TP
 540 .BI "--filter " "name"
 541 When creating an ELF shared object, set the internal DT_FILTER field to
 542 the specified name.  This tells the dynamic linker that the symbol table
 543 of the shared object should be used as a filter on the symbol table of
 544 the shared object
 545 .I name.
 546
 547 .TP
 548 .BI "\-format " "input\-format"
 549 Synonym for \c
 550 .B \-b\c
 551 \& \c
 552 .I input\-format\c
 553 \&.
 554
 555 .TP
 556 .B \-g
 557 Accepted, but ignored; provided for compatibility with other tools.
 558
 559 .TP
 560 .BI "\-G " "size"\c
 561 Set the maximum size of objects to be optimized using the GP register
 562 to
 563 .I size
 564 under MIPS ECOFF.  Ignored for other object file formats.
 565
 566 .TP
 567 .BI "-h " "name"
 568 .TP
 569 .BI "-soname " "name"
 570 When creating an ELF shared object, set the internal DT_SONAME field to
 571 the specified name.  When an executable is linked with a shared object
 572 which has a DT_SONAME field, then when the executable is run the dynamic
 573 linker will attempt to load the shared object specified by the DT_SONAME
 574 field rather than the using the file name given to the linker.
 575
 576 .TP
 577 .B \-\-help
 578 Print a summary of the command-line options on the standard output and exit.
 579 This option and
 580 .B \-\-version
 581 begin with two dashes instead of one
 582 for compatibility with other GNU programs.  The other options start with
 583 only one dash for compatibility with other linkers.
 584
 585 .TP
 586 .B \-i
 587 Perform an incremental link (same as option \c
 588 .B \-r\c
 589 \&).
 590
 591 .TP
 592 .BI "\-l" "ar"\c
 593 \&
 594 Add an archive file \c
 595 .I ar\c
 596 \& to the list of files to link.  This
 597 option may be used any number of times.  \c
 598 .B ld\c
 599 \& will search its
 600 path-list for occurrences of \c
 601 .B lib\c
 602 .I ar\c
 603 \&.a\c
 604 \& for every \c
 605 .I ar
 606 specified.
 607
 608 .TP
 609 .BI "\-L" "searchdir"
 610 This command adds path \c
 611 .I searchdir\c
 612 \& to the list of paths that
 613 \c
 614 .B ld\c
 615 \& will search for archive libraries.  You may use this option
 616 any number of times.
 617
 618 The default set of paths searched (without being specified with
 619 \c
 620 .B \-L\c
 621 \&) depends on what emulation mode \c
 622 .B ld\c
 623 \& is using, and in
 624 some cases also on how it was configured.    The
 625 paths can also be specified in a link script with the \c
 626 .B SEARCH_DIR
 627 command.
 628
 629 .TP
 630 .B \-M
 631 Print (to the standard output file) a link map\(em\&diagnostic information
 632 about where symbols are mapped by \c
 633 .B ld\c
 634 \&, and information on global
 635 common storage allocation.
 636
 637 .TP
 638 .BI "\-Map " "mapfile"\c
 639 Print to the file
 640 .I mapfile
 641 a link map\(em\&diagnostic information
 642 about where symbols are mapped by \c
 643 .B ld\c
 644 \&, and information on global
 645 common storage allocation.
 646
 647 .TP
 648 .BI "\-m " "emulation"\c
 649 Emulate the
 650 .I emulation
 651 linker.  You can list the available emulations with the
 652 .I \-\-verbose
 653 or
 654 .I \-V
 655 options.  This option overrides the compiled-in default, which is the
 656 system for which you configured
 657 .BR ld .
 658
 659 .TP
 660 .B \-N
 661 specifies readable and writable \c
 662 .B text\c
 663 \& and \c
 664 .B data\c
 665 \& sections. If
 666 the output format supports Unix style magic numbers, the output is
 667 marked as \c
 668 .B OMAGIC\c
 669 \&.
 670
 671 When you use the `\|\c
 672 .B \-N\c
 673 \&\|' option, the linker does not page-align the
 674 data segment.
 675
 676 .TP
 677 .B \-n
 678 sets the text segment to be read only, and \c
 679 .B NMAGIC\c
 680 \& is written
 681 if possible.
 682
 683 .TP
 684 .B \-noinhibit\-exec
 685 Normally, the linker will not produce an output file if it encounters
 686 errors during the link process.  With this flag, you can specify that
 687 you wish the output file retained even after non-fatal errors.
 688
 689 .TP
 690 .B \-no\-keep\-memory
 691 The linker normally optimizes for speed over memory usage by caching
 692 the symbol tables of input files in memory.  This option tells the
 693 linker to instead optimize for memory usage, by rereading the symbol
 694 tables as necessary.  This may be required if the linker runs out of
 695 memory space while linking a large executable.
 696
 697 .TP
 698 .B \-no\-warn\-mismatch
 699 Normally the linker will give an error if you try to link together
 700 input files that are mismatched for some reason, perhaps because they
 701 have been compiled for different processors or for different
 702 endiannesses.  This option tells the linker that it should silently
 703 permit such possible errors.  This option should only be used with
 704 care, in cases when you have taken some special action that ensures
 705 that the linker errors are inappropriate.
 706
 707 .TP
 708 .BI "\-o " "output"
 709 .I output\c
 710 \& is a name for the program produced by \c
 711 .B ld\c
 712 \&; if this
 713 option is not specified, the name `\|\c
 714 .B a.out\c
 715 \|' is used by default.  The
 716 script command \c
 717 .B OUTPUT\c
 718 \& can also specify the output file name.
 719
 720 .TP
 721 .BI "\-O" "level"
 722 Generate optimized output files.  This might use significantly more
 723 time and therefore probably should be enabled only for generating the
 724 final binary.
 725 \c
 726 .I level\c
 727 \& is supposed to be a numeric value.  Any value greater than zero enables
 728 the optimizations.
 729
 730 .TP
 731 .BI "\-oformat " "output\-format"
 732 Specify the binary format for the output object file.
 733 You don't usually need to specify this, as
 734 \c
 735 .B ld\c
 736 \& is configured to produce as a default output format the most
 737 usual format on each machine.  \c
 738 .I output-format\c
 739 \& is a text string, the
 740 name of a particular format supported by the BFD libraries.
 741 The script command
 742 .B OUTPUT_FORMAT
 743 can also specify the output format, but this option overrides it.
 744
 745 .TP
 746 .BI "\-R " "filename"
 747 Read symbol names and their addresses from \c
 748 .I filename\c
 749 \&, but do not
 750 relocate it or include it in the output.  This allows your output file
 751 to refer symbolically to absolute locations of memory defined in other
 752 programs.
 753
 754 .TP
 755 .B \-relax
 756 An option with machine dependent effects.  Currently this option is only
 757 supported on the H8/300.
 758
 759 On some platforms, use this option to perform global optimizations that
 760 become possible when the linker resolves addressing in your program, such
 761 as relaxing address modes and synthesizing new instructions in the
 762 output object file.
 763
 764 On platforms where this is not supported, `\|\c
 765 .B \-relax\c
 766 \&\|' is accepted, but has no effect.
 767
 768 .TP
 769 .B \-r
 770 Generates relocatable output\(em\&i.e., generate an output file that can in
 771 turn serve as input to \c
 772 .B ld\c
 773 \&.  This is often called \c
 774 .I partial
 775 linking\c
 776 \&.  As a side effect, in environments that support standard Unix
 777 magic numbers, this option also sets the output file's magic number to
 778 \c
 779 .B OMAGIC\c
 780 \&.
 781 If this option is not specified, an absolute file is produced.  When
 782 linking C++ programs, this option \c
 783 .I will not\c
 784 \& resolve references to
 785 constructors; \c
 786 .B \-Ur\c
 787 \& is an alternative.
 788
 789 This option does the same as \c
 790 .B \-i\c
 791 \&.
 792
 793 .TP
 794 .B \-rpath\ \fIdirectory
 795 Add a directory to the runtime library search path.  This is used when
 796 linking an ELF executable with shared objects.  All
 797 .B \-rpath
 798 arguments are concatenated and passed to the runtime linker, which uses
 799 them to locate shared objects at runtime.  The
 800 .B \-rpath
 801 option is also used when locating shared objects which are needed by
 802 shared objects explicitly included in the link; see the description of
 803 the
 804 .B \-rpath\-link
 805 option.  If
 806 .B \-rpath
 807 is not used when linking an ELF executable, the contents of the
 808 environment variable
 809 .B LD_RUN_PATH
 810 will be used if it is defined.
 811
 812 The
 813 .B \-rpath
 814 option may also be used on SunOS.  By default, on SunOS, the linker
 815 will form a runtime search path out of all the
 816 .B \-L
 817 options it is given.  If a
 818 .B \-rpath
 819 option is used, the runtime search path will be formed exclusively
 820 using the
 821 .B \-rpath
 822 options, ignoring
 823 the
 824 .B \-L
 825 options.  This can be useful when using gcc, which adds many
 826 .B \-L
 827 options which may be on NFS mounted filesystems.
 828
 829 .TP
 830 .B \-rpath\-link\ \fIdirectory
 831 When using ELF or SunOS, one shared library may require another.  This
 832 happens when an
 833 .B ld\ \-shared
 834 link includes a shared library as one of the input files.
 835
 836 When the linker encounters such a dependency when doing a non-shared,
 837 non-relocateable link, it will automatically try to locate the required
 838 shared library and include it in the link, if it is not included
 839 explicitly.  In such a case, the
 840 .B \-rpath\-link
 841 option specifies the first set of directories to search.  The
 842 .B \-rpath\-link
 843 option may specify a sequence of directory names either by specifying
 844 a list of names separated by colons, or by appearing multiple times.
 845
 846 If the required shared library is not found, the linker will issue a
 847 warning and continue with the link.
 848
 849 .TP
 850 .B \-S
 851 Omits debugger symbol information (but not all symbols) from the output file.
 852
 853 .TP
 854 .B \-s
 855 Omits all symbol information from the output file.
 856
 857 .TP
 858 .B \-shared
 859 Create a shared library.  This is currently only supported on ELF and
 860 SunOS platforms (on SunOS it is not required, as the linker will
 861 automatically create a shared library when there are undefined symbols
 862 and the
 863 .B \-e
 864 option is not used).
 865
 866 .TP
 867 .B \-sort\-common
 868 Normally, when
 869 .B ld
 870 places the global common symbols in the appropriate output sections,
 871 it sorts them by size.  First come all the one byte symbols, then all
 872 the two bytes, then all the four bytes, and then everything else.
 873 This is to prevent gaps between symbols due to
 874 alignment constraints.  This option disables that sorting.
 875
 876 .TP
 877 .B \-split\-by\-reloc\ \fIcount
 878 Trys to creates extra sections in the output file so that no single
 879 output section in the file contains more than
 880 .I count
 881 relocations.
 882 This is useful when generating huge relocatable for downloading into
 883 certain real time kernels with the COFF object file format; since COFF
 884 cannot represent more than 65535 relocations in a single section.
 885 Note that this will fail to work with object file formats which do not
 886 support arbitrary sections.  The linker will not split up individual
 887 input sections for redistribution, so if a single input section
 888 contains more than
 889 .I count
 890 relocations one output section will contain that many relocations.
 891
 892 .TP
 893 .B \-split\-by\-file
 894 Similar to
 895 .B \-split\-by\-reloc
 896 but creates a new output section for each input file.
 897
 898 .TP
 899 .BI "--section-start " "sectionname" "\fR=\fP"org
 900 Locate a section in the output file at the absolute
 901 address given by \c
 902 .I org\c
 903 \&.  \c
 904 \c
 905 .I org\c
 906 \& must be a hexadecimal integer.
 907 You may use this option as many
 908 times as necessary to locate multiple sections in the command
 909 line.  If you need more elaborate expressions, consider
 910 using the linker command language from a script.
 911
 912 .TP
 913 .BI "\-Tbss " "org"\c
 914 .TP
 915 .BI "\-Tdata " "org"\c
 916 .TP
 917 .BI "\-Ttext " "org"\c
 918 Use \c
 919 .I org\c
 920 \& as the starting address for\(em\&respectively\(em\&the
 921 \c
 922 .B bss\c
 923 \&, \c
 924 .B data\c
 925 \&, or the \c
 926 .B text\c
 927 \& segment of the output file.
 928 \c
 929 .I org\c
 930 \& must be a hexadecimal integer.
 931
 932 .TP
 933 .BI "\-T " "commandfile"
 934 Equivalent to \c
 935 .B \-c \c
 936 .I commandfile\c
 937 \&\c
 938 \&; supported for compatibility with
 939 other tools.
 940
 941 .TP
 942 .B \-t
 943 Prints names of input files as \c
 944 .B ld\c
 945 \& processes them.
 946
 947 .TP
 948 .BI "\-u " "sym"
 949 Forces \c
 950 .I sym\c
 951 \& to be entered in the output file as an undefined symbol.
 952 This may, for example, trigger linking of additional modules from
 953 standard libraries.  \c
 954 .B \-u\c
 955 \& may be repeated with different option
 956 arguments to enter additional undefined symbols.
 957
 958 .TP
 959 .B \-Ur
 960 For anything other than C++ programs, this option is equivalent to
 961 \c
 962 .B \-r\c
 963 \&: it generates relocatable output\(em\&i.e., an output file that can in
 964 turn serve as input to \c
 965 .B ld\c
 966 \&.  When linking C++ programs, \c
 967 .B \-Ur
 968 .I will\c
 969 \& resolve references to constructors, unlike \c
 970 .B \-r\c
 971 \&.
 972
 973 .TP
 974 .B \-\-verbose
 975 Display the version number for \c
 976 .B ld
 977 and list the supported emulations.
 978 Display which input files can and can not be opened.
 979
 980 .TP
 981 .B \-v, \-V
 982 Display the version number for \c
 983 .B ld\c
 984 \&.
 985 The
 986 .B \-V
 987 option also lists the supported emulations.
 988
 989 .TP
 990 .B \-\-version
 991 Display the version number for \c
 992 .B ld
 993 and exit.
 994
 995 .TP
 996 .B \-warn\-common
 997 Warn when a common symbol is combined with another common symbol or with
 998 a symbol definition.  Unix linkers allow this somewhat sloppy practice,
 999 but linkers on some other operating systems do not.  This option allows
1000 you to find potential problems from combining global symbols.
1001
1002 .TP
1003 .B \-warn\-constructors
1004 Warn if any global constructors are used.  This is only useful for a
1005 few object file formats.  For formats like COFF or ELF, the linker can
1006 not detect the use of global constructors.
1007
1008 .TP
1009 .B \-warn\-multiple\-gp
1010 Warn if the output file requires multiple global-pointer values.  This
1011 option is only meaningful for certain processors, such as the Alpha.
1012
1013 .TP
1014 .B \-warn\-once
1015 Only warn once for each undefined symbol, rather than once per module
1016 which refers to it.
1017
1018 .TP
1019 .B \-warn\-section\-align
1020 Warn if the address of an output section is changed because of
1021 alignment.  Typically, the alignment will be set by an input section.
1022 The address will only be changed if it not explicitly specified; that
1023 is, if the SECTIONS command does not specify a start address for the
1024 section.
1025
1026 .TP
1027 .B \-\-whole\-archive
1028 For each archive mentioned on the command line after the
1029 .B \-\-whole\-archive
1030 option, include every object file in the archive in the link, rather
1031 than searching the archive for the required object files.  This is
1032 normally used to turn an archive file into a shared library, forcing
1033 every object to be included in the resulting shared library.
1034
1035 .TP
1036 .B \-\-no\-whole\-archive
1037 Turn off the effect of the
1038 .B \-\-whole\-archive
1039 option for archives which appear later on the command line.
1040
1041 .TP
1042 .BI "--wrap " "symbol"
1043 Use a wrapper function for
1044 .I symbol.
1045 Any undefined reference to
1046 .I symbol
1047 will be resolved to
1048 .BI "__wrap_" "symbol".
1049 Any undefined reference to
1050 .BI "__real_" "symbol"
1051 will be resolved to
1052 .I symbol.
1053
1054 .TP
1055 .B \-X
1056 Delete all temporary local symbols.  For most targets, this is all local
1057 symbols whose names begin with `\|\c
1058 .B L\c
1059 \|'.
1060
1061 .TP
1062 .B \-x
1063 Delete all local symbols.
1064
1065 .PP
1066
1067 .SH ENVIRONMENT
1068 \c
1069 You can change the behavior of
1070 .B ld\c
1071 \& with the environment variable \c
1072 .B GNUTARGET\c
1073 \&.
1074
1075 \c
1076 .B GNUTARGET\c
1077 \& determines the input-file object format if you don't
1078 use \c
1079 .B \-b\c
1080 \& (or its synonym \c
1081 .B \-format\c
1082 \&).  Its value should be one
1083 of the BFD names for an input format.  If there is no
1084 \c
1085 .B GNUTARGET\c
1086 \& in the environment, \c
1087 .B ld\c
1088 \& uses the natural format
1089 of the host. If \c
1090 .B GNUTARGET\c
1091 \& is set to \c
1092 .B default\c
1093 \& then BFD attempts to discover the
1094 input format by examining binary input files; this method often
1095 succeeds, but there are potential ambiguities, since there is no method
1096 of ensuring that the magic number used to flag object-file formats is
1097 unique.  However, the configuration procedure for BFD on each system
1098 places the conventional format for that system first in the search-list,
1099 so ambiguities are resolved in favor of convention.
1100
1101 .PP
1102
1103 .SH "SEE ALSO"
1104
1105 .BR objdump ( 1 )
1106 .br
1107 .br
1108 .RB "`\|" ld "\|' and `\|" binutils "\|'"
1109 entries in
1110 .B info\c
1111 .br
1112 .I
1113 ld: the GNU linker\c
1114 , Steve Chamberlain and Roland Pesch;
1115 .I
1116 The GNU Binary Utilities\c
1117 , Roland H. Pesch.
1118
1119 .SH COPYING
1120 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
1121 .PP
1122 Permission is granted to make and distribute verbatim copies of
1123 this manual provided the copyright notice and this permission notice
1124 are preserved on all copies.
1125 .PP
1126 Permission is granted to copy and distribute modified versions of this
1127 manual under the conditions for verbatim copying, provided that the
1128 entire resulting derived work is distributed under the terms of a
1129 permission notice identical to this one.
1130 .PP
1131 Permission is granted to copy and distribute translations of this
1132 manual into another language, under the above conditions for modified
1133 versions, except that this permission notice may be included in
1134 translations approved by the Free Software Foundation instead of in
1135 the original English.