ld/ld.1

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