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