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