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