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