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