ld/ld.1

   1 .\" Copyright (c) 1991, 1992 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 "[\|" "\-c\ "\c
  32 .I commandfile\c
  33 \&\|]
  34 .RB "[\|" \-d | \-dc | \-dp\c
  35 \|]
  36 .br
  37 .RB "[\|" "\-defsym\ "\c
  38 .I symbol\c
  39 \& = \c
  40 .I expression\c
  41 \&\|]
  42 .RB "[\|" "\-e\ "\c
  43 .I entry\c
  44 \&\|]
  45 .RB "[\|" \-embedded\-relocs "\|]"
  46 .RB "[\|" \-F "\|]"
  47 .RB "[\|" "\-F\ "\c
  48 .I format\c
  49 \&\|]
  50 .RB "[\|" "\-format\ "\c
  51 .I input-format\c
  52 \&\|]
  53 .RB "[\|" \-g "\|]"
  54 .RB "[\|" \-G\c
  55 .I size\c
  56 \&\|]
  57 .RB "[\|" \-\-help "\|]"
  58 .RB "[\|" \-i "\|]"
  59 .RB "[\|" \-l\c
  60 .I ar\c
  61 \&\|]
  62 .RB "[\|" \-L\c
  63 .I searchdir\c
  64 \&\|]
  65 .RB "[\|" \-M "\|]"
  66 .RB "[\|" \-Map\c
  67 .I mapfile\c
  68 \&\|]
  69 .RB "[\|" \-m\c
  70 .I emulation\c
  71 \&\|]
  72 .RB "[\|" \-n | \-N "\|]"
  73 .RB "[\|" \-noinhibit-exec "\|]"
  74 .RB "[\|" "\-oformat\ "\c
  75 .I output-format\c
  76 \&\|]
  77 .RB "[\|" "\-R\ "\c
  78 .I filename\c
  79 \&\|]
  80 .RB "[\|" \-relax "\|]"
  81 .RB "[\|" \-r | \-Ur "\|]"
  82 .RB "[\|" \-S "\|]"
  83 .RB "[\|" \-s "\|]"
  84 .RB "[\|" \-sort\-common "\|]"
  85 .RB "[\|" \-split\-by\-reloc\ "\c
  86 .I count\c
  87 \&\|]
  88 .RB "[\|" \-split\-by\-file "\|]"
  89 .RB "[\|" "\-T\ "\c
  90 .I commandfile\c
  91 \&\|]
  92 .RB "[\|" "\-Ttext\ "\c
  93 .I textorg\c
  94 \&\|]
  95 .RB "[\|" "\-Tdata\ "\c
  96 .I dataorg\c
  97 \&\|]
  98 .RB "[\|" "\-Tbss\ "\c
  99 .I bssorg\c
 100 \&\|]
 101 .RB "[\|" \-t "\|]"
 102 .RB "[\|" "\-u\ "\c
 103 .I sym\c
 104 \&]
 105 .RB "[\|" \-V "\|]"
 106 .RB "[\|" \-v "\|]"
 107 .RB "[\|" \-\-verbose "\|]"
 108 .RB "[\|" \-\-version "\|]"
 109 .RB "[\|" \-warn\-common "\|]"
 110 .RB "[\|" \-warn\-once "\|]"
 111 .RB "[\|" \-\-whole\-archive "\|]"
 112 .RB "[\|" \-X "\|]"
 113 .RB "[\|" \-x "\|]"
 114 .ad b
 115 .hy 1
 116 .SH DESCRIPTION
 117 \c
 118 .B ld\c
 119 \& combines a number of object and archive files, relocates
 120 their data and ties up symbol references. Often the last step in
 121 building a new compiled program to run is a call to \c
 122 .B ld\c
 123 \&.
 124
 125 \c
 126 .B ld\c
 127 \& accepts Linker Command Language files
 128 to provide explicit and total control over the linking process.
 129 This man page does not describe the command language; see the `\|\c
 130 .B ld\c
 131 \|' entry in `\|\c
 132 .B info\c
 133 \|', or the manual
 134 .I
 135 ld: the GNU linker
 136 \&, for full details on the command language and on other aspects of
 137 the GNU linker.
 138
 139 This version of \c
 140 .B ld\c
 141 \& uses the general purpose BFD libraries
 142 to operate on object files. This allows \c
 143 .B ld\c
 144 \& to read, combine, and
 145 write object files in many different formats\(em\&for example, COFF or
 146 \c
 147 .B a.out\c
 148 \&.  Different formats may be linked together to produce any
 149 available kind of object file.  You can use `\|\c
 150 .B objdump \-i\c
 151 \|' to get a list of formats supported on various architectures; see
 152 .BR objdump ( 1 ).
 153
 154 Aside from its flexibility, the GNU linker is more helpful than other
 155 linkers in providing diagnostic information.  Many linkers abandon
 156 execution immediately upon encountering an error; whenever possible,
 157 \c
 158 .B ld\c
 159 \& continues executing, allowing you to identify other errors
 160 (or, in some cases, to get an output file in spite of the error).
 161
 162 The GNU linker \c
 163 .B ld\c
 164 \& is meant to cover a broad range of situations,
 165 and to be as compatible as possible with other linkers.  As a result,
 166 you have many choices to control its behavior through the command line,
 167 and through environment variables.
 168
 169 .SH OPTIONS
 170 The plethora of command-line options may seem intimidating, but in
 171 actual practice few of them are used in any particular context.
 172 For instance, a frequent use of \c
 173 .B ld\c
 174 \& is to link standard Unix
 175 object files on a standard, supported Unix system.  On such a system, to
 176 link a file \c
 177 .B hello.o\c
 178 \&:
 179 .sp
 180 .br
 181 $\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
 182 .br
 183 .sp
 184 This tells \c
 185 .B ld\c
 186 \& to produce a file called \c
 187 .B output\c
 188 \& as the
 189 result of linking the file \c
 190 .B /lib/crt0.o\c
 191 \& with \c
 192 .B hello.o\c
 193 \& and
 194 the library \c
 195 .B libc.a\c
 196 \& which will come from the standard search
 197 directories.
 198
 199 The command-line options to \c
 200 .B ld\c
 201 \& may be specified in any order, and
 202 may be repeated at will.  For the most part, repeating an option with a
 203 different argument will either have no further effect, or override prior
 204 occurrences (those further to the left on the command line) of an
 205 option.
 206
 207 The exceptions\(em\&which may meaningfully be used more than once\(em\&are
 208 \c
 209 .B \-A\c
 210 \&, \c
 211 .B \-b\c
 212 \& (or its synonym \c
 213 .B \-format\c
 214 \&), \c
 215 .B \-defsym\c
 216 \&,
 217 \c
 218 .B \-L\c
 219 \&, \c
 220 .B \-l\c
 221 \&, \c
 222 .B \-R\c
 223 \&, and \c
 224 .B \-u\c
 225 \&.
 226
 227 The list of object files to be linked together, shown as \c
 228 .I objfile\c
 229 \&,
 230 may follow, precede, or be mixed in with command-line options; save that
 231 an \c
 232 .I objfile\c
 233 \& argument may not be placed between an option flag and
 234 its argument.
 235
 236 Usually the linker is invoked with at least one object file, but other
 237 forms of binary input files can also be specified with \c
 238 .B \-l\c
 239 \&,
 240 \c
 241 .B \-R\c
 242 \&, and the script command language.  If \c
 243 .I no\c
 244 \& binary input
 245 files at all are specified, the linker does not produce any output, and
 246 issues the message `\|\c
 247 .B No input files\c
 248 \|'.
 249
 250 Option arguments must either follow the option letter without intervening
 251 whitespace, or be given as separate arguments immediately following the
 252 option that requires them.
 253
 254 .TP
 255 .BI "-A" "architecture"\c
 256 \&
 257 In the current release of \c
 258 .B ld\c
 259 \&, this option is useful only for the
 260 Intel 960 family of architectures.  In that \c
 261 .B ld\c
 262 \& configuration, the
 263 \c
 264 .I architecture\c
 265 \& argument is one of the two-letter names identifying
 266 members of the 960 family; the option specifies the desired output
 267 target, and warns of any incompatible instructions in the input files.
 268 It also modifies the linker's search strategy for archive libraries, to
 269 support the use of libraries specific to each particular
 270 architecture, by including in the search loop names suffixed with the
 271 string identifying the architecture.
 272
 273 For example, if your \c
 274 .B ld\c
 275 \& command line included `\|\c
 276 .B \-ACA\c
 277 \|' as
 278 well as `\|\c
 279 .B \-ltry\c
 280 \|', the linker would look (in its built-in search
 281 paths, and in any paths you specify with \c
 282 .B \-L\c
 283 \&) for a library with
 284 the names
 285 .sp
 286 .br
 287 try
 288 .br
 289 libtry.a
 290 .br
 291 tryca
 292 .br
 293 libtryca.a
 294 .br
 295 .sp
 296
 297 The first two possibilities would be considered in any event; the last
 298 two are due to the use of `\|\c
 299 .B \-ACA\c
 300 \|'.
 301
 302 Future releases of \c
 303 .B ld\c
 304 \& may support similar functionality for
 305 other architecture families.
 306
 307 You can meaningfully use \c
 308 .B \-A\c
 309 \& more than once on a command line, if
 310 an architecture family allows combination of target architectures; each
 311 use will add another pair of name variants to search for when \c
 312 .B \-l\c
 313 \&
 314 specifies a library.
 315
 316 .TP
 317 .BI "\-b " "input-format"\c
 318 \&
 319 Specify the binary format for input object files that follow this option
 320 on the command line.  You don't usually need to specify this, as
 321 \c
 322 .B ld\c
 323 \& is configured to expect as a default input format the most
 324 usual format on each machine.  \c
 325 .I input-format\c
 326 \& is a text string, the
 327 name of a particular format supported by the BFD libraries.
 328 \c
 329 .B \-format \c
 330 .I input-format\c
 331 \&\c
 332 \& has the same effect, as does the script command
 333 .BR TARGET .
 334
 335 You may want to use this option if you are linking files with an unusual
 336 binary format.  You can also use \c
 337 .B \-b\c
 338 \& to switch formats explicitly (when
 339 linking object files of different formats), by including
 340 \c
 341 .B \-b \c
 342 .I input-format\c
 343 \&\c
 344 \& before each group of object files in a
 345 particular format.
 346
 347 The default format is taken from the environment variable
 348 .B GNUTARGET\c
 349 \&.  You can also define the input
 350 format from a script, using the command \c
 351 .B TARGET\c
 352 \&.
 353
 354 .TP
 355 .B \-Bstatic
 356 This flag is accepted for command-line compatibility with the SunOS linker,
 357 but has no effect on \c
 358 .B ld\c
 359 \&.
 360
 361 .TP
 362 .BI "\-c " "commandfile"\c
 363 \&
 364 Directs \c
 365 .B ld\c
 366 \& to read link commands from the file
 367 \c
 368 .I commandfile\c
 369 \&.  These commands will completely override \c
 370 .B ld\c
 371 \&'s
 372 default link format (rather than adding to it); \c
 373 .I commandfile\c
 374 \& must
 375 specify everything necessary to describe the target format.
 376
 377
 378 You may also include a script of link commands directly in the command
 379 line by bracketing it between `\|\c
 380 .B {\c
 381 \|' and `\|\c
 382 .B }\c
 383 \|' characters.
 384
 385 .TP
 386 .B \-d
 387 .TP
 388 .B \-dc
 389 .TP
 390 .B \-dp
 391 These three options are equivalent; multiple forms are supported for
 392 compatibility with other linkers.  Use any of them to make \c
 393 .B ld\c
 394 \&
 395 assign space to common symbols even if a relocatable output file is
 396 specified (\c
 397 .B \-r\c
 398 \&).  The script command
 399 \c
 400 .B FORCE_COMMON_ALLOCATION\c
 401 \& has the same effect.
 402
 403 .TP
 404 .BI "-defsym " "symbol"\c
 405 \& = \c
 406 .I expression\c
 407 \&
 408 Create a global symbol in the output file, containing the absolute
 409 address given by \c
 410 .I expression\c
 411 \&.  You may use this option as many
 412 times as necessary to define multiple symbols in the command line.  A
 413 limited form of arithmetic is supported for the \c
 414 .I expression\c
 415 \& in this
 416 context: you may give a hexadecimal constant or the name of an existing
 417 symbol, or use \c
 418 .B +\c
 419 \& and \c
 420 .B \-\c
 421 \& to add or subtract hexadecimal
 422 constants or symbols.  If you need more elaborate expressions, consider
 423 using the linker command language from a script.
 424
 425 .TP
 426 .BI "-e " "entry"\c
 427 \&
 428 Use \c
 429 .I entry\c
 430 \& as the explicit symbol for beginning execution of your
 431 program, rather than the default entry point.  for a
 432 discussion of defaults and other ways of specifying the
 433 entry point.
 434
 435 .TP
 436 .B \-embedded\-relocs
 437 This option is only meaningful when linking MIPS embedded PIC code,
 438 generated by the
 439 .B \-membedded\-pic
 440 option to the GNU compiler and assembler.  It causes the linker to
 441 create a table which may be used at runtime to relocate any data which
 442 was statically initialized to pointer values.  See the code in
 443 testsuite/ld-empic for details.
 444
 445 .TP
 446 .B \-F
 447 .TP
 448 .BI "-F" "format"\c
 449 \&
 450 Some older linkers used this option throughout a compilation toolchain
 451 for specifying object-file format for both input and output object
 452 files.  \c
 453 .B ld\c
 454 \&'s mechanisms (the \c
 455 .B \-b\c
 456 \& or \c
 457 .B \-format\c
 458 \& options
 459 for input files, the \c
 460 .B TARGET\c
 461 \& command in linker scripts for output
 462 files, the \c
 463 .B GNUTARGET\c
 464 \& environment variable) are more flexible, but
 465 but it accepts (and ignores) the \c
 466 .B \-F\c
 467 \& option flag for compatibility
 468 with scripts written to call the old linker.
 469
 470 .TP
 471 .BI "\-format " "input\-format"\c
 472 \&
 473 Synonym for \c
 474 .B \-b\c
 475 \& \c
 476 .I input\-format\c
 477 \&.
 478
 479 .TP
 480 .B \-g
 481 Accepted, but ignored; provided for compatibility with other tools.
 482
 483 .TP
 484 .BI "\-G " "size"\c
 485 Set the maximum size of objects to be optimized using the GP register
 486 to
 487 .I size
 488 under MIPS ECOFF.  Ignored for other object file formats.
 489
 490 .TP
 491 .B \-\-help
 492 Print a summary of the command-line options on the standard output and exit.
 493 This option and
 494 .B \-\-version
 495 begin with two dashes instead of one
 496 for compatibility with other GNU programs.  The other options start with
 497 only one dash for compatibility with other linkers.
 498
 499 .TP
 500 .B \-i
 501 Perform an incremental link (same as option \c
 502 .B \-r\c
 503 \&).
 504
 505 .TP
 506 .BI "\-l" "ar"\c
 507 \&
 508 Add an archive file \c
 509 .I ar\c
 510 \& to the list of files to link.  This
 511 option may be used any number of times.  \c
 512 .B ld\c
 513 \& will search its
 514 path-list for occurrences of \c
 515 .B lib\c
 516 .I ar\c
 517 \&.a\c
 518 \& for every \c
 519 .I ar\c
 520 \&
 521 specified.
 522
 523 .TP
 524 .BI "\-L" "searchdir"\c
 525 \&
 526 This command adds path \c
 527 .I searchdir\c
 528 \& to the list of paths that
 529 \c
 530 .B ld\c
 531 \& will search for archive libraries.  You may use this option
 532 any number of times.
 533
 534 The default set of paths searched (without being specified with
 535 \c
 536 .B \-L\c
 537 \&) depends on what emulation mode \c
 538 .B ld\c
 539 \& is using, and in
 540 some cases also on how it was configured.    The
 541 paths can also be specified in a link script with the \c
 542 .B SEARCH_DIR\c
 543 \&
 544 command.
 545
 546 .TP
 547 .B \-M
 548 Print (to the standard output file) a link map\(em\&diagnostic information
 549 about where symbols are mapped by \c
 550 .B ld\c
 551 \&, and information on global
 552 common storage allocation.
 553
 554 .TP
 555 .BI "\-Map " "mapfile"\c
 556 Print to the file
 557 .I mapfile
 558 a link map\(em\&diagnostic information
 559 about where symbols are mapped by \c
 560 .B ld\c
 561 \&, and information on global
 562 common storage allocation.
 563
 564 .TP
 565 .BI "\-m " "emulation"\c
 566 Emulate the
 567 .I emulation
 568 linker.  You can list the available emulations with the
 569 .I \-\-verbose
 570 or
 571 .I \-V
 572 options.  This option overrides the compiled-in default, which is the
 573 system for which you configured
 574 .BR ld .
 575
 576 .TP
 577 .B \-N
 578 specifies readable and writable \c
 579 .B text\c
 580 \& and \c
 581 .B data\c
 582 \& sections. If
 583 the output format supports Unix style magic numbers, the output is
 584 marked as \c
 585 .B OMAGIC\c
 586 \&.
 587
 588 When you use the `\|\c
 589 .B \-N\c
 590 \&\|' option, the linker does not page-align the
 591 data segment.
 592
 593 .TP
 594 .B \-n
 595 sets the text segment to be read only, and \c
 596 .B NMAGIC\c
 597 \& is written
 598 if possible.
 599
 600 .TP
 601 .B \-noinhibit\-exec
 602 Normally, the linker will not produce an output file if it encounters
 603 errors during the link process.  With this flag, you can specify that
 604 you wish the output file retained even after non-fatal errors.
 605
 606 .TP
 607 .BI "\-o " "output"\c
 608 \&
 609 .I output\c
 610 \&
 611 \c
 612 .I output\c
 613 \& is a name for the program produced by \c
 614 .B ld\c
 615 \&; if this
 616 option is not specified, the name `\|\c
 617 .B a.out\c
 618 \|' is used by default.  The
 619 script command \c
 620 .B OUTPUT\c
 621 \& can also specify the output file name.
 622
 623 .TP
 624 .BI "\-oformat " "output\-format"\c
 625 \&
 626 Specify the binary format for the output object file.
 627 You don't usually need to specify this, as
 628 \c
 629 .B ld\c
 630 \& is configured to produce as a default output format the most
 631 usual format on each machine.  \c
 632 .I output-format\c
 633 \& is a text string, the
 634 name of a particular format supported by the BFD libraries.
 635 The script command
 636 .B OUTPUT_FORMAT
 637 can also specify the output format, but this option overrides it.
 638
 639 .TP
 640 .BI "\-R " "filename"\c
 641 \&
 642 .I file\c
 643 \&
 644 Read symbol names and their addresses from \c
 645 .I filename\c
 646 \&, but do not
 647 relocate it or include it in the output.  This allows your output file
 648 to refer symbolically to absolute locations of memory defined in other
 649 programs.
 650
 651 .TP
 652 .B \-relax
 653 An option with machine dependent effects.  Currently this option is only
 654 supported on the H8/300.
 655
 656 On some platforms, use this option to perform global optimizations that
 657 become possible when the linker resolves addressing in your program, such
 658 as relaxing address modes and synthesizing new instructions in the
 659 output object file.
 660
 661 On platforms where this is not supported, `\|\c
 662 .B \-relax\c
 663 \&\|' is accepted, but has no effect.
 664
 665 .TP
 666 .B \-r
 667 Generates relocatable output\(em\&i.e., generate an output file that can in
 668 turn serve as input to \c
 669 .B ld\c
 670 \&.  This is often called \c
 671 .I partial
 672 linking\c
 673 \&.  As a side effect, in environments that support standard Unix
 674 magic numbers, this option also sets the output file's magic number to
 675 \c
 676 .B OMAGIC\c
 677 \&.
 678 If this option is not specified, an absolute file is produced.  When
 679 linking C++ programs, this option \c
 680 .I will not\c
 681 \& resolve references to
 682 constructors; \c
 683 .B \-Ur\c
 684 \& is an alternative.
 685
 686 This option does the same as \c
 687 .B \-i\c
 688 \&.
 689
 690 .TP
 691 .B \-S
 692 Omits debugger symbol information (but not all symbols) from the output file.
 693
 694 .TP
 695 .B \-s
 696 Omits all symbol information from the output file.
 697
 698 .TP
 699 .B \-sort\-common
 700 Normally, when
 701 .B ld
 702 places the global common symbols in the appropriate output sections,
 703 it sorts them by size.  First come all the one byte symbols, then all
 704 the two bytes, then all the four bytes, and then everything else.
 705 This is to prevent gaps between symbols due to
 706 alignment constraints.  This option disables that sorting.
 707
 708 .TP
 709 .B \-split\-by\-reloc\ \fIcount
 710 Trys to creates extra sections in the output file so that no single
 711 output section in the file contains more than
 712 .I count
 713 relocations.
 714 This is useful when generating huge relocatable for downloading into
 715 certain real time kernels with the COFF object file format; since COFF
 716 cannot represent more than 65535 relocations in a single section.
 717 Note that this will fail to work with object file formats which do not
 718 support arbitrary sections.  The linker will not split up individual
 719 input sections for redistribution, so if a single input section
 720 contains more than
 721 .I count
 722 relocations one output section will contain that many relocations.
 723
 724 .TP
 725 .B \-split\-by\-file
 726 Similar to
 727 .B \-split\-by\-reloc
 728 but creates a new output section for each input file.
 729
 730 .TP
 731 .BI "\-Tbss " "org"\c
 732 .TP
 733 .BI "\-Tdata " "org"\c
 734 .TP
 735 .BI "\-Ttext " "org"\c
 736 Use \c
 737 .I org\c
 738 \& as the starting address for\(em\&respectively\(em\&the
 739 \c
 740 .B bss\c
 741 \&, \c
 742 .B data\c
 743 \&, or the \c
 744 .B text\c
 745 \& segment of the output file.
 746 \c
 747 .I textorg\c
 748 \& must be a hexadecimal integer.
 749
 750 .TP
 751 .BI "\-T " "commandfile"\c
 752 \&
 753 .TP
 754 .BI "\-T" "commandfile"\c
 755 Equivalent to \c
 756 .B \-c \c
 757 .I commandfile\c
 758 \&\c
 759 \&; supported for compatibility with
 760 other tools.
 761
 762 .TP
 763 .B \-t
 764 Prints names of input files as \c
 765 .B ld\c
 766 \& processes them.
 767
 768 .TP
 769 .BI "\-u " "sym"
 770 Forces \c
 771 .I sym\c
 772 \& to be entered in the output file as an undefined symbol.
 773 This may, for example, trigger linking of additional modules from
 774 standard libraries.  \c
 775 .B \-u\c
 776 \& may be repeated with different option
 777 arguments to enter additional undefined symbols.
 778
 779 .TP
 780 .B \-Ur
 781 For anything other than C++ programs, this option is equivalent to
 782 \c
 783 .B \-r\c
 784 \&: it generates relocatable output\(em\&i.e., an output file that can in
 785 turn serve as input to \c
 786 .B ld\c
 787 \&.  When linking C++ programs, \c
 788 .B \-Ur\c
 789 \&
 790 \c
 791 .I will\c
 792 \& resolve references to constructors, unlike \c
 793 .B \-r\c
 794 \&.
 795
 796 .TP
 797 .B \-\-verbose
 798 Display the version number for \c
 799 .B ld
 800 and list the supported emulations.
 801 Display which input files can and can not be opened.
 802
 803 .TP
 804 .B \-v, \-V
 805 Display the version number for \c
 806 .B ld\c
 807 \&.
 808 The
 809 .B \-V
 810 option also lists the supported emulations.
 811
 812 .TP
 813 .B \-\-version
 814 Display the version number for \c
 815 .B ld
 816 and exit.
 817
 818 .TP
 819 .B \-warn\-common
 820 Warn when a common symbol is combined with another common symbol or with
 821 a symbol definition.  Unix linkers allow this somewhat sloppy practice,
 822 but linkers on some other operating systems do not.  This option allows
 823 you to find potential problems from combining global symbols.
 824
 825 .TP
 826 .B \-warn\-once
 827 Only warn once for each undefined symbol, rather than once per module
 828 which refers to it.
 829
 830 .TP
 831 .B \-\-whole\-archive
 832 For each archive mentioned on the command line, include every object
 833 file in the archive in the link, rather than searching the archive for
 834 the required object files.  This is normally used to turn an archive
 835 file into a shared library, forcing every object to be included in the
 836 resulting shared library.
 837
 838 .TP
 839 .B \-X
 840 Delete all temporary local symbols.  For most targets, this is all local
 841 symbols whose names begin with `\|\c
 842 .B L\c
 843 \|'.
 844
 845 .TP
 846 .B \-x
 847 Delete all local symbols.
 848
 849 .PP
 850
 851 .SH ENVIRONMENT
 852 \c
 853 You can change the behavior of
 854 .B ld\c
 855 \& with the environment variable \c
 856 .B GNUTARGET\c
 857 \&.
 858
 859 \c
 860 .B GNUTARGET\c
 861 \& determines the input-file object format if you don't
 862 use \c
 863 .B \-b\c
 864 \& (or its synonym \c
 865 .B \-format\c
 866 \&).  Its value should be one
 867 of the BFD names for an input format.  If there is no
 868 \c
 869 .B GNUTARGET\c
 870 \& in the environment, \c
 871 .B ld\c
 872 \& uses the natural format
 873 of the host. If \c
 874 .B GNUTARGET\c
 875 \& is set to \c
 876 .B default\c
 877 \& then BFD attempts to discover the
 878 input format by examining binary input files; this method often
 879 succeeds, but there are potential ambiguities, since there is no method
 880 of ensuring that the magic number used to flag object-file formats is
 881 unique.  However, the configuration procedure for BFD on each system
 882 places the conventional format for that system first in the search-list,
 883 so ambiguities are resolved in favor of convention.
 884
 885 .PP
 886
 887 .SH "SEE ALSO"
 888
 889 .BR objdump ( 1 )
 890 .br
 891 .br
 892 .RB "`\|" ld "\|' and `\|" binutils "\|'"
 893 entries in
 894 .B info\c
 895 .br
 896 .I
 897 ld: the GNU linker\c
 898 , Steve Chamberlain and Roland Pesch;
 899 .I
 900 The GNU Binary Utilities\c
 901 , Roland H. Pesch.
 902
 903 .SH COPYING
 904 Copyright (c) 1991, 1992 Free Software Foundation, Inc.
 905 .PP
 906 Permission is granted to make and distribute verbatim copies of
 907 this manual provided the copyright notice and this permission notice
 908 are preserved on all copies.
 909 .PP
 910 Permission is granted to copy and distribute modified versions of this
 911 manual under the conditions for verbatim copying, provided that the
 912 entire resulting derived work is distributed under the terms of a
 913 permission notice identical to this one.
 914 .PP
 915 Permission is granted to copy and distribute translations of this
 916 manual into another language, under the above conditions for modified
 917 versions, except that this permission notice may be included in
 918 translations approved by the Free Software Foundation instead of in
 919 the original English.