1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14

     2 .\"

     3 .\" Standard preamble:

     4 .\" ========================================================================

     5 .de Sh \" Subsection heading

     6 .br

     7 .if t .Sp

     8 .ne 5

     9 .PP

    10 \fB\\$1\fR

    11 .PP

    12 ..

    13 .de Sp \" Vertical space (when we can't use .PP)

    14 .if t .sp .5v

    15 .if n .sp

    16 ..

    17 .de Vb \" Begin verbatim text

    18 .ft CW

    19 .nf

    20 .ne \\$1

    21 ..

    22 .de Ve \" End verbatim text

    23 .ft R

    24 .fi

    25 ..

    26 .\" Set up some character translations and predefined strings.  \*(-- will

    27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

    28 .\" double quote, and \*(R" will give a right double quote.  | will give a

    29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to

    30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'

    31 .\" expand to `' in nroff, nothing in troff, for use with C<>.

    32 .tr \(*W-|\(bv\*(Tr

    33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

    34 .ie n \{\

    35 .    ds -- \(*W-

    36 .    ds PI pi

    37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch

    38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch

    39 .    ds L" ""

    40 .    ds R" ""

    41 .    ds C` ""

    42 .    ds C' ""

    43 'br\}

    44 .el\{\

    45 .    ds -- \|\(em\|

    46 .    ds PI \(*p

    47 .    ds L" ``

    48 .    ds R" ''

    49 'br\}

    50 .\"

    51 .\" If the F register is turned on, we'll generate index entries on stderr for

    52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index

    53 .\" entries marked with X<> in POD.  Of course, you'll have to process the

    54 .\" output yourself in some meaningful fashion.

    55 .if \nF \{\

    56 .    de IX

    57 .    tm Index:\\$1\t\\n%\t"\\$2"

    58 ..

    59 .    nr % 0

    60 .    rr F

    61 .\}

    62 .\"

    63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes

    64 .\" way too many mistakes in technical documents.

    65 .hy 0

    66 .\"

    67 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

    68 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.

    69 .    \" fudge factors for nroff and troff

    70 .if n \{\

    71 .    ds #H 0

    72 .    ds #V .8m

    73 .    ds #F .3m

    74 .    ds #[ \f1

    75 .    ds #] \fP

    76 .\}

    77 .if t \{\

    78 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)

    79 .    ds #V .6m

    80 .    ds #F 0

    81 .    ds #[ \&

    82 .    ds #] \&

    83 .\}

    84 .    \" simple accents for nroff and troff

    85 .if n \{\

    86 .    ds ' \&

    87 .    ds ` \&

    88 .    ds ^ \&

    89 .    ds , \&

    90 .    ds ~ ~

    91 .    ds /

    92 .\}

    93 .if t \{\

    94 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"

    95 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'

    96 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'

    97 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'

    98 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'

    99 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'

   100 .\}

   101 .    \" troff and (daisy-wheel) nroff accents

   102 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'

   103 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'

   104 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]

   105 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'

   106 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'

   107 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]

   108 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]

   109 .ds ae a\h'-(\w'a'u*4/10)'e

   110 .ds Ae A\h'-(\w'A'u*4/10)'E

   111 .    \" corrections for vroff

   112 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'

   113 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'

   114 .    \" for low resolution devices (crt and lpr)

   115 .if \n(.H>23 .if \n(.V>19 \

   116 \{\

   117 .    ds : e

   118 .    ds 8 ss

   119 .    ds o a

   120 .    ds d- d\h'-1'\(ga

   121 .    ds D- D\h'-1'\(hy

   122 .    ds th \o'bp'

   123 .    ds Th \o'LP'

   124 .    ds ae ae

   125 .    ds Ae AE

   126 .\}

   127 .rm #[ #] #H #V #F C

   128 .\" ========================================================================

   129 .\"

   130 .IX Title "LD 1"

   131 .TH LD 1 "2008-01-09" "binutils-2.18.50" "GNU Development Tools"

   132 .SH "NAME"

   133 ld \- The GNU linker

   134 .SH "SYNOPSIS"

   135 .IX Header "SYNOPSIS"

   136 ld [\fBoptions\fR] \fIobjfile\fR ...

   137 .SH "DESCRIPTION"

   138 .IX Header "DESCRIPTION"

   139 \&\fBld\fR combines a number of object and archive files, relocates

   140 their data and ties up symbol references. Usually the last step in

   141 compiling a program is to run \fBld\fR.

   142 .PP

   143 \&\fBld\fR accepts Linker Command Language files written in

   144 a superset of \s-1AT&T\s0's Link Editor Command Language syntax,

   145 to provide explicit and total control over the linking process.

   146 .PP

   147 This man page does not describe the command language; see the

   148 \&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command

   149 language and on other aspects of the \s-1GNU\s0 linker.

   150 .PP

   151 This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries

   152 to operate on object files. This allows \fBld\fR to read, combine, and

   153 write object files in many different formats\-\-\-for example, \s-1COFF\s0 or

   154 \&\f(CW\*(C`a.out\*(C'\fR.  Different formats may be linked together to produce any

   155 available kind of object file.  

   156 .PP

   157 Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other

   158 linkers in providing diagnostic information.  Many linkers abandon

   159 execution immediately upon encountering an error; whenever possible,

   160 \&\fBld\fR continues executing, allowing you to identify other errors

   161 (or, in some cases, to get an output file in spite of the error).

   162 .PP

   163 The \s-1GNU\s0 linker \fBld\fR is meant to cover a broad range of situations,

   164 and to be as compatible as possible with other linkers.  As a result,

   165 you have many choices to control its behavior.

   166 .SH "OPTIONS"

   167 .IX Header "OPTIONS"

   168 The linker supports a plethora of command-line options, but in actual

   169 practice few of them are used in any particular context.

   170 For instance, a frequent use of \fBld\fR is to link standard Unix

   171 object files on a standard, supported Unix system.  On such a system, to

   172 link a file \f(CW\*(C`hello.o\*(C'\fR:

   173 .PP

   174 .Vb 1

   175 \&        ld -o <output> /lib/crt0.o hello.o -lc

   176 .Ve

   177 .PP

   178 This tells \fBld\fR to produce a file called \fIoutput\fR as the

   179 result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and

   180 the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search

   181 directories.  (See the discussion of the \fB\-l\fR option below.)

   182 .PP

   183 Some of the command-line options to \fBld\fR may be specified at any

   184 point in the command line.  However, options which refer to files, such

   185 as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at

   186 which the option appears in the command line, relative to the object

   187 files and other file options.  Repeating non-file options with a

   188 different argument will either have no further effect, or override prior

   189 occurrences (those further to the left on the command line) of that

   190 option.  Options which may be meaningfully specified more than once are

   191 noted in the descriptions below.

   192 .PP

   193 Non-option arguments are object files or archives which are to be linked

   194 together.  They may follow, precede, or be mixed in with command-line

   195 options, except that an object file argument may not be placed between

   196 an option and its argument.

   197 .PP

   198 Usually the linker is invoked with at least one object file, but you can

   199 specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR,

   200 and the script command language.  If \fIno\fR binary input files at all

   201 are specified, the linker does not produce any output, and issues the

   202 message \fBNo input files\fR.

   203 .PP

   204 If the linker cannot recognize the format of an object file, it will

   205 assume that it is a linker script.  A script specified in this way

   206 augments the main linker script used for the link (either the default

   207 linker script or the one specified by using \fB\-T\fR).  This feature

   208 permits the linker to link against a file which appears to be an object

   209 or an archive, but actually merely defines some symbol values, or uses

   210 \&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects.  Note that

   211 specifying a script in this way merely augments the main linker script;

   212 use the \fB\-T\fR option to replace the default linker script entirely.

   213 .PP

   214 For options whose names are a single letter,

   215 option arguments must either follow the option letter without intervening

   216 whitespace, or be given as separate arguments immediately following the

   217 option that requires them.

   218 .PP

   219 For options whose names are multiple letters, either one dash or two can

   220 precede the option name; for example, \fB\-trace\-symbol\fR and

   221 \&\fB\-\-trace\-symbol\fR are equivalent.  Note\-\-\-there is one exception to

   222 this rule.  Multiple letter options that start with a lower case 'o' can

   223 only be preceded by two dashes.  This is to reduce confusion with the

   224 \&\fB\-o\fR option.  So for example \fB\-omagic\fR sets the output file

   225 name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the \s-1NMAGIC\s0 flag on the

   226 output.

   227 .PP

   228 Arguments to multiple-letter options must either be separated from the

   229 option name by an equals sign, or be given as separate arguments

   230 immediately following the option that requires them.  For example,

   231 \&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent.

   232 Unique abbreviations of the names of multiple-letter options are

   233 accepted.

   234 .PP

   235 Note\-\-\-if the linker is being invoked indirectly, via a compiler driver

   236 (e.g. \fBgcc\fR) then all the linker command line options should be

   237 prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular

   238 compiler driver) like this:

   239 .PP

   240 .Vb 1

   241 \&          gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup

   242 .Ve

   243 .PP

   244 This is important, because otherwise the compiler driver program may

   245 silently drop the linker options, resulting in a bad link.

   246 .PP

   247 Here is a table of the generic command line switches accepted by the \s-1GNU\s0

   248 linker:

   249 .IP "\fB@\fR\fIfile\fR" 4

   250 .IX Item "@file"

   251 Read command-line options from \fIfile\fR.  The options read are

   252 inserted in place of the original @\fIfile\fR option.  If \fIfile\fR

   253 does not exist, or cannot be read, then the option will be treated

   254 literally, and not removed.  

   255 .Sp

   256 Options in \fIfile\fR are separated by whitespace.  A whitespace

   257 character may be included in an option by surrounding the entire

   258 option in either single or double quotes.  Any character (including a

   259 backslash) may be included by prefixing the character to be included

   260 with a backslash.  The \fIfile\fR may itself contain additional

   261 @\fIfile\fR options; any such options will be processed recursively.

   262 .IP "\fB\-a\fR\fIkeyword\fR" 4

   263 .IX Item "-akeyword"

   264 This option is supported for \s-1HP/UX\s0 compatibility.  The \fIkeyword\fR

   265 argument must be one of the strings \fBarchive\fR, \fBshared\fR, or

   266 \&\fBdefault\fR.  \fB\-aarchive\fR is functionally equivalent to

   267 \&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent

   268 to \fB\-Bdynamic\fR.  This option may be used any number of times.

   269 .IP "\fB\-A\fR\fIarchitecture\fR" 4

   270 .IX Item "-Aarchitecture"

   271 .PD 0

   272 .IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4

   273 .IX Item "--architecture=architecture"

   274 .PD

   275 In the current release of \fBld\fR, this option is useful only for the

   276 Intel 960 family of architectures.  In that \fBld\fR configuration, the

   277 \&\fIarchitecture\fR argument identifies the particular architecture in

   278 the 960 family, enabling some safeguards and modifying the

   279 archive-library search path.  

   280 .Sp

   281 Future releases of \fBld\fR may support similar functionality for

   282 other architecture families.

   283 .IP "\fB\-b\fR \fIinput-format\fR" 4

   284 .IX Item "-b input-format"

   285 .PD 0

   286 .IP "\fB\-\-format=\fR\fIinput-format\fR" 4

   287 .IX Item "--format=input-format"

   288 .PD

   289 \&\fBld\fR may be configured to support more than one kind of object

   290 file.  If your \fBld\fR is configured this way, you can use the

   291 \&\fB\-b\fR option to specify the binary format for input object files

   292 that follow this option on the command line.  Even when \fBld\fR is

   293 configured to support alternative object formats, you don't usually need

   294 to specify this, as \fBld\fR should be configured to expect as a

   295 default input format the most usual format on each machine.

   296 \&\fIinput-format\fR is a text string, the name of a particular format

   297 supported by the \s-1BFD\s0 libraries.  (You can list the available binary

   298 formats with \fBobjdump \-i\fR.)

   299 .Sp

   300 You may want to use this option if you are linking files with an unusual

   301 binary format.  You can also use \fB\-b\fR to switch formats explicitly (when

   302 linking object files of different formats), by including

   303 \&\fB\-b\fR \fIinput-format\fR before each group of object files in a

   304 particular format.

   305 .Sp

   306 The default format is taken from the environment variable

   307 \&\f(CW\*(C`GNUTARGET\*(C'\fR.

   308 .Sp

   309 You can also define the input format from a script, using the command

   310 \&\f(CW\*(C`TARGET\*(C'\fR;

   311 .IP "\fB\-c\fR \fIMRI-commandfile\fR" 4

   312 .IX Item "-c MRI-commandfile"

   313 .PD 0

   314 .IP "\fB\-\-mri\-script=\fR\fIMRI-commandfile\fR" 4

   315 .IX Item "--mri-script=MRI-commandfile"

   316 .PD

   317 For compatibility with linkers produced by \s-1MRI\s0, \fBld\fR accepts script

   318 files written in an alternate, restricted command language, described in

   319 the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.

   320 Introduce \s-1MRI\s0 script files with

   321 the option \fB\-c\fR; use the \fB\-T\fR option to run linker

   322 scripts written in the general-purpose \fBld\fR scripting language.

   323 If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories

   324 specified by any \fB\-L\fR options.

   325 .IP "\fB\-d\fR" 4

   326 .IX Item "-d"

   327 .PD 0

   328 .IP "\fB\-dc\fR" 4

   329 .IX Item "-dc"

   330 .IP "\fB\-dp\fR" 4

   331 .IX Item "-dp"

   332 .PD

   333 These three options are equivalent; multiple forms are supported for

   334 compatibility with other linkers.  They assign space to common symbols

   335 even if a relocatable output file is specified (with \fB\-r\fR).  The

   336 script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.

   337 .IP "\fB\-e\fR \fIentry\fR" 4

   338 .IX Item "-e entry"

   339 .PD 0

   340 .IP "\fB\-\-entry=\fR\fIentry\fR" 4

   341 .IX Item "--entry=entry"

   342 .PD

   343 Use \fIentry\fR as the explicit symbol for beginning execution of your

   344 program, rather than the default entry point.  If there is no symbol

   345 named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,

   346 and use that as the entry address (the number will be interpreted in

   347 base 10; you may use a leading \fB0x\fR for base 16, or a leading

   348 \&\fB0\fR for base 8).  

   349 .IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4

   350 .IX Item "--exclude-libs lib,lib,..."

   351 Specifies a list of archive libraries from which symbols should not be automatically

   352 exported. The library names may be delimited by commas or colons.  Specifying

   353 \&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from

   354 automatic export.  This option is available only for the i386 \s-1PE\s0 targeted

   355 port of the linker and for \s-1ELF\s0 targeted ports.  For i386 \s-1PE\s0, symbols

   356 explicitly listed in a .def file are still exported, regardless of this

   357 option.  For \s-1ELF\s0 targeted ports, symbols affected by this option will

   358 be treated as hidden.

   359 .IP "\fB\-E\fR" 4

   360 .IX Item "-E"

   361 .PD 0

   362 .IP "\fB\-\-export\-dynamic\fR" 4

   363 .IX Item "--export-dynamic"

   364 .PD

   365 When creating a dynamically linked executable, add all symbols to the

   366 dynamic symbol table.  The dynamic symbol table is the set of symbols

   367 which are visible from dynamic objects at run time.

   368 .Sp

   369 If you do not use this option, the dynamic symbol table will normally

   370 contain only those symbols which are referenced by some dynamic object

   371 mentioned in the link.

   372 .Sp

   373 If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer

   374 back to the symbols defined by the program, rather than some other

   375 dynamic object, then you will probably need to use this option when

   376 linking the program itself.

   377 .Sp

   378 You can also use the dynamic list to control what symbols should

   379 be added to the dynamic symbol table if the output format supports it.

   380 See the description of \fB\-\-dynamic\-list\fR.

   381 .IP "\fB\-EB\fR" 4

   382 .IX Item "-EB"

   383 Link big-endian objects.  This affects the default output format.

   384 .IP "\fB\-EL\fR" 4

   385 .IX Item "-EL"

   386 Link little-endian objects.  This affects the default output format.

   387 .IP "\fB\-f\fR" 4

   388 .IX Item "-f"

   389 .PD 0

   390 .IP "\fB\-\-auxiliary\fR \fIname\fR" 4

   391 .IX Item "--auxiliary name"

   392 .PD

   393 When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field

   394 to the specified name.  This tells the dynamic linker that the symbol

   395 table of the shared object should be used as an auxiliary filter on the

   396 symbol table of the shared object \fIname\fR.

   397 .Sp

   398 If you later link a program against this filter object, then, when you

   399 run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field.  If

   400 the dynamic linker resolves any symbols from the filter object, it will

   401 first check whether there is a definition in the shared object

   402 \&\fIname\fR.  If there is one, it will be used instead of the definition

   403 in the filter object.  The shared object \fIname\fR need not exist.

   404 Thus the shared object \fIname\fR may be used to provide an alternative

   405 implementation of certain functions, perhaps for debugging or for

   406 machine specific performance.

   407 .Sp

   408 This option may be specified more than once.  The \s-1DT_AUXILIARY\s0 entries

   409 will be created in the order in which they appear on the command line.

   410 .IP "\fB\-F\fR \fIname\fR" 4

   411 .IX Item "-F name"

   412 .PD 0

   413 .IP "\fB\-\-filter\fR \fIname\fR" 4

   414 .IX Item "--filter name"

   415 .PD

   416 When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to

   417 the specified name.  This tells the dynamic linker that the symbol table

   418 of the shared object which is being created should be used as a filter

   419 on the symbol table of the shared object \fIname\fR.

   420 .Sp

   421 If you later link a program against this filter object, then, when you

   422 run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field.  The

   423 dynamic linker will resolve symbols according to the symbol table of the

   424 filter object as usual, but it will actually link to the definitions

   425 found in the shared object \fIname\fR.  Thus the filter object can be

   426 used to select a subset of the symbols provided by the object

   427 \&\fIname\fR.

   428 .Sp

   429 Some older linkers used the \fB\-F\fR option throughout a compilation

   430 toolchain for specifying object-file format for both input and output

   431 object files.

   432 The \s-1GNU\s0 linker uses other mechanisms for this purpose: the

   433 \&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the

   434 \&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR

   435 environment variable.

   436 The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not

   437 creating an \s-1ELF\s0 shared object.

   438 .IP "\fB\-fini\fR \fIname\fR" 4

   439 .IX Item "-fini name"

   440 When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the

   441 executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the

   442 address of the function.  By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as

   443 the function to call.

   444 .IP "\fB\-g\fR" 4

   445 .IX Item "-g"

   446 Ignored.  Provided for compatibility with other tools.

   447 .IP "\fB\-G\fR\fIvalue\fR" 4

   448 .IX Item "-Gvalue"

   449 .PD 0

   450 .IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4

   451 .IX Item "--gpsize=value"

   452 .PD

   453 Set the maximum size of objects to be optimized using the \s-1GP\s0 register to

   454 \&\fIsize\fR.  This is only meaningful for object file formats such as

   455 \&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different

   456 sections.  This is ignored for other object file formats.

   457 .IP "\fB\-h\fR\fIname\fR" 4

   458 .IX Item "-hname"

   459 .PD 0

   460 .IP "\fB\-soname=\fR\fIname\fR" 4

   461 .IX Item "-soname=name"

   462 .PD

   463 When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to

   464 the specified name.  When an executable is linked with a shared object

   465 which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic

   466 linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0

   467 field rather than the using the file name given to the linker.

   468 .IP "\fB\-i\fR" 4

   469 .IX Item "-i"

   470 Perform an incremental link (same as option \fB\-r\fR).

   471 .IP "\fB\-init\fR \fIname\fR" 4

   472 .IX Item "-init name"

   473 When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the

   474 executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address

   475 of the function.  By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the

   476 function to call.

   477 .IP "\fB\-l\fR\fInamespec\fR" 4

   478 .IX Item "-lnamespec"

   479 .PD 0

   480 .IP "\fB\-\-library=\fR\fInamespec\fR" 4

   481 .IX Item "--library=namespec"

   482 .PD

   483 Add the archive or object file specified by \fInamespec\fR to the

   484 list of files to link.  This option may be used any number of times.

   485 If \fInamespec\fR is of the form \fI:\fIfilename\fI\fR, \fBld\fR

   486 will search the library path for a file called \fIfilename\fR, otherise it

   487 will search the library path for a file called \fIlib\fInamespec\fI.a\fR.

   488 .Sp

   489 On systems which support shared libraries, \fBld\fR may also search for

   490 files other than \fIlib\fInamespec\fI.a\fR.  Specifically, on \s-1ELF\s0

   491 and SunOS systems, \fBld\fR will search a directory for a library

   492 called \fIlib\fInamespec\fI.so\fR before searching for one called

   493 \&\fIlib\fInamespec\fI.a\fR.  (By convention, a \f(CW\*(C`.so\*(C'\fR extension

   494 indicates a shared library.)  Note that this behavior does not apply

   495 to \fI:\fIfilename\fI\fR, which always specifies a file called

   496 \&\fIfilename\fR.

   497 .Sp

   498 The linker will search an archive only once, at the location where it is

   499 specified on the command line.  If the archive defines a symbol which

   500 was undefined in some object which appeared before the archive on the

   501 command line, the linker will include the appropriate file(s) from the

   502 archive.  However, an undefined symbol in an object appearing later on

   503 the command line will not cause the linker to search the archive again.

   504 .Sp

   505 See the \fB\-(\fR option for a way to force the linker to search

   506 archives multiple times.

   507 .Sp

   508 You may list the same archive multiple times on the command line.

   509 .Sp

   510 This type of archive searching is standard for Unix linkers.  However,

   511 if you are using \fBld\fR on \s-1AIX\s0, note that it is different from the

   512 behaviour of the \s-1AIX\s0 linker.

   513 .IP "\fB\-L\fR\fIsearchdir\fR" 4

   514 .IX Item "-Lsearchdir"

   515 .PD 0

   516 .IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4

   517 .IX Item "--library-path=searchdir"

   518 .PD

   519 Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search

   520 for archive libraries and \fBld\fR control scripts.  You may use this

   521 option any number of times.  The directories are searched in the order

   522 in which they are specified on the command line.  Directories specified

   523 on the command line are searched before the default directories.  All

   524 \&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the

   525 order in which the options appear.

   526 .Sp

   527 If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced

   528 by the \fIsysroot prefix\fR, a path specified when the linker is configured.

   529 .Sp

   530 The default set of paths searched (without being specified with

   531 \&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in

   532 some cases also on how it was configured.  

   533 .Sp

   534 The paths can also be specified in a link script with the

   535 \&\f(CW\*(C`SEARCH_DIR\*(C'\fR command.  Directories specified this way are searched

   536 at the point in which the linker script appears in the command line.

   537 .IP "\fB\-m\fR\fIemulation\fR" 4

   538 .IX Item "-memulation"

   539 Emulate the \fIemulation\fR linker.  You can list the available

   540 emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.

   541 .Sp

   542 If the \fB\-m\fR option is not used, the emulation is taken from the

   543 \&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.

   544 .Sp

   545 Otherwise, the default emulation depends upon how the linker was

   546 configured.

   547 .IP "\fB\-M\fR" 4

   548 .IX Item "-M"

   549 .PD 0

   550 .IP "\fB\-\-print\-map\fR" 4

   551 .IX Item "--print-map"

   552 .PD

   553 Print a link map to the standard output.  A link map provides

   554 information about the link, including the following:

   555 .RS 4

   556 .IP "*" 4

   557 Where object files are mapped into memory.

   558 .IP "*" 4

   559 How common symbols are allocated.

   560 .IP "*" 4

   561 All archive members included in the link, with a mention of the symbol

   562 which caused the archive member to be brought in.

   563 .IP "*" 4

   564 The values assigned to symbols.

   565 .Sp

   566 Note \- symbols whose values are computed by an expression which

   567 involves a reference to a previous value of the same symbol may not

   568 have correct result displayed in the link map.  This is because the

   569 linker discards intermediate results and only retains the final value

   570 of an expression.  Under such circumstances the linker will display

   571 the final value enclosed by square brackets.  Thus for example a

   572 linker script containing:

   573 .Sp

   574 .Vb 3

   575 \&           foo = 1

   576 \&           foo = foo * 4

   577 \&           foo = foo + 8

   578 .Ve

   579 .Sp

   580 will produce the following output in the link map if the \fB\-M\fR

   581 option is used:

   582 .Sp

   583 .Vb 3

   584 \&           0x00000001                foo = 0x1

   585 \&           [0x0000000c]                foo = (foo * 0x4)

   586 \&           [0x0000000c]                foo = (foo + 0x8)

   587 .Ve

   588 .Sp

   589 See \fBExpressions\fR for more information about expressions in linker

   590 scripts.

   591 .RE

   592 .RS 4

   593 .RE

   594 .IP "\fB\-n\fR" 4

   595 .IX Item "-n"

   596 .PD 0

   597 .IP "\fB\-\-nmagic\fR" 4

   598 .IX Item "--nmagic"

   599 .PD

   600 Turn off page alignment of sections, and mark the output as

   601 \&\f(CW\*(C`NMAGIC\*(C'\fR if possible.

   602 .IP "\fB\-N\fR" 4

   603 .IX Item "-N"

   604 .PD 0

   605 .IP "\fB\-\-omagic\fR" 4

   606 .IX Item "--omagic"

   607 .PD

   608 Set the text and data sections to be readable and writable.  Also, do

   609 not page-align the data segment, and disable linking against shared

   610 libraries.  If the output format supports Unix style magic numbers,

   611 mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section

   612 is allowed for PE-COFF targets, it does not conform to the format

   613 specification published by Microsoft.

   614 .IP "\fB\-\-no\-omagic\fR" 4

   615 .IX Item "--no-omagic"

   616 This option negates most of the effects of the \fB\-N\fR option.  It

   617 sets the text section to be read\-only, and forces the data segment to

   618 be page\-aligned.  Note \- this option does not enable linking against

   619 shared libraries.  Use \fB\-Bdynamic\fR for this.

   620 .IP "\fB\-o\fR \fIoutput\fR" 4

   621 .IX Item "-o output"

   622 .PD 0

   623 .IP "\fB\-\-output=\fR\fIoutput\fR" 4

   624 .IX Item "--output=output"

   625 .PD

   626 Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this

   627 option is not specified, the name \fIa.out\fR is used by default.  The

   628 script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.

   629 .IP "\fB\-O\fR \fIlevel\fR" 4

   630 .IX Item "-O level"

   631 If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes

   632 the output.  This might take significantly longer and therefore probably

   633 should only be enabled for the final binary.  At the moment this

   634 option only affects \s-1ELF\s0 shared library generation.  Future releases of

   635 the linker may make more use of this option.  Also currently there is

   636 no difference in the linker's behaviour for different non-zero values

   637 of this option.  Again this may change with future releases.

   638 .IP "\fB\-q\fR" 4

   639 .IX Item "-q"

   640 .PD 0

   641 .IP "\fB\-\-emit\-relocs\fR" 4

   642 .IX Item "--emit-relocs"

   643 .PD

   644 Leave relocation sections and contents in fully linked executables.

   645 Post link analysis and optimization tools may need this information in

   646 order to perform correct modifications of executables.  This results

   647 in larger executables.

   648 .Sp

   649 This option is currently only supported on \s-1ELF\s0 platforms.

   650 .IP "\fB\-\-force\-dynamic\fR" 4

   651 .IX Item "--force-dynamic"

   652 Force the output file to have dynamic sections.  This option is specific

   653 to VxWorks targets.

   654 .IP "\fB\-r\fR" 4

   655 .IX Item "-r"

   656 .PD 0

   657 .IP "\fB\-\-relocatable\fR" 4

   658 .IX Item "--relocatable"

   659 .PD

   660 Generate relocatable output\-\-\-i.e., generate an output file that can in

   661 turn serve as input to \fBld\fR.  This is often called \fIpartial

   662 linking\fR.  As a side effect, in environments that support standard Unix

   663 magic numbers, this option also sets the output file's magic number to

   664 \&\f(CW\*(C`OMAGIC\*(C'\fR.

   665 If this option is not specified, an absolute file is produced.  When

   666 linking \*(C+ programs, this option \fIwill not\fR resolve references to

   667 constructors; to do that, use \fB\-Ur\fR.

   668 .Sp

   669 When an input file does not have the same format as the output file,

   670 partial linking is only supported if that input file does not contain any

   671 relocations.  Different output formats can have further restrictions; for

   672 example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking

   673 with input files in other formats at all.

   674 .Sp

   675 This option does the same thing as \fB\-i\fR.

   676 .IP "\fB\-R\fR \fIfilename\fR" 4

   677 .IX Item "-R filename"

   678 .PD 0

   679 .IP "\fB\-\-just\-symbols=\fR\fIfilename\fR" 4

   680 .IX Item "--just-symbols=filename"

   681 .PD

   682 Read symbol names and their addresses from \fIfilename\fR, but do not

   683 relocate it or include it in the output.  This allows your output file

   684 to refer symbolically to absolute locations of memory defined in other

   685 programs.  You may use this option more than once.

   686 .Sp

   687 For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is

   688 followed by a directory name, rather than a file name, it is treated as

   689 the \fB\-rpath\fR option.

   690 .IP "\fB\-s\fR" 4

   691 .IX Item "-s"

   692 .PD 0

   693 .IP "\fB\-\-strip\-all\fR" 4

   694 .IX Item "--strip-all"

   695 .PD

   696 Omit all symbol information from the output file.

   697 .IP "\fB\-S\fR" 4

   698 .IX Item "-S"

   699 .PD 0

   700 .IP "\fB\-\-strip\-debug\fR" 4

   701 .IX Item "--strip-debug"

   702 .PD

   703 Omit debugger symbol information (but not all symbols) from the output file.

   704 .IP "\fB\-t\fR" 4

   705 .IX Item "-t"

   706 .PD 0

   707 .IP "\fB\-\-trace\fR" 4

   708 .IX Item "--trace"

   709 .PD

   710 Print the names of the input files as \fBld\fR processes them.

   711 .IP "\fB\-T\fR \fIscriptfile\fR" 4

   712 .IX Item "-T scriptfile"

   713 .PD 0

   714 .IP "\fB\-\-script=\fR\fIscriptfile\fR" 4

   715 .IX Item "--script=scriptfile"

   716 .PD

   717 Use \fIscriptfile\fR as the linker script.  This script replaces

   718 \&\fBld\fR's default linker script (rather than adding to it), so

   719 \&\fIcommandfile\fR must specify everything necessary to describe the

   720 output file.    If \fIscriptfile\fR does not exist in

   721 the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories

   722 specified by any preceding \fB\-L\fR options.  Multiple \fB\-T\fR

   723 options accumulate.

   724 .IP "\fB\-dT\fR \fIscriptfile\fR" 4

   725 .IX Item "-dT scriptfile"

   726 .PD 0

   727 .IP "\fB\-\-default\-script=\fR\fIscriptfile\fR" 4

   728 .IX Item "--default-script=scriptfile"

   729 .PD

   730 Use \fIscriptfile\fR as the default linker script.  

   731 .Sp

   732 This option is similar to the \fB\-\-script\fR option except that

   733 processing of the script is delayed until after the rest of the

   734 command line has been processed.  This allows options placed after the

   735 \&\fB\-\-default\-script\fR option on the command line to affect the

   736 behaviour of the linker script, which can be important when the linker

   737 command line cannot be directly controlled by the user.  (eg because

   738 the command line is being constructed by another tool, such as

   739 \&\fBgcc\fR).

   740 .IP "\fB\-u\fR \fIsymbol\fR" 4

   741 .IX Item "-u symbol"

   742 .PD 0

   743 .IP "\fB\-\-undefined=\fR\fIsymbol\fR" 4

   744 .IX Item "--undefined=symbol"

   745 .PD

   746 Force \fIsymbol\fR to be entered in the output file as an undefined

   747 symbol.  Doing this may, for example, trigger linking of additional

   748 modules from standard libraries.  \fB\-u\fR may be repeated with

   749 different option arguments to enter additional undefined symbols.  This

   750 option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command.

   751 .IP "\fB\-Ur\fR" 4

   752 .IX Item "-Ur"

   753 For anything other than \*(C+ programs, this option is equivalent to

   754 \&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in

   755 turn serve as input to \fBld\fR.  When linking \*(C+ programs, \fB\-Ur\fR

   756 \&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR.

   757 It does not work to use \fB\-Ur\fR on files that were themselves linked

   758 with \fB\-Ur\fR; once the constructor table has been built, it cannot

   759 be added to.  Use \fB\-Ur\fR only for the last partial link, and

   760 \&\fB\-r\fR for the others.

   761 .IP "\fB\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4

   762 .IX Item "--unique[=SECTION]"

   763 Creates a separate output section for every input section matching

   764 \&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is

   765 missing, for every orphan input section.  An orphan section is one not

   766 specifically mentioned in a linker script.  You may use this option

   767 multiple times on the command line;  It prevents the normal merging of

   768 input sections with the same name, overriding output section assignments

   769 in a linker script.

   770 .IP "\fB\-v\fR" 4

   771 .IX Item "-v"

   772 .PD 0

   773 .IP "\fB\-\-version\fR" 4

   774 .IX Item "--version"

   775 .IP "\fB\-V\fR" 4

   776 .IX Item "-V"

   777 .PD

   778 Display the version number for \fBld\fR.  The \fB\-V\fR option also

   779 lists the supported emulations.

   780 .IP "\fB\-x\fR" 4

   781 .IX Item "-x"

   782 .PD 0

   783 .IP "\fB\-\-discard\-all\fR" 4

   784 .IX Item "--discard-all"

   785 .PD

   786 Delete all local symbols.

   787 .IP "\fB\-X\fR" 4

   788 .IX Item "-X"

   789 .PD 0

   790 .IP "\fB\-\-discard\-locals\fR" 4

   791 .IX Item "--discard-locals"

   792 .PD

   793 Delete all temporary local symbols.  (These symbols start with

   794 system-specific local label prefixes, typically \fB.L\fR for \s-1ELF\s0 systems

   795 or \fBL\fR for traditional a.out systems.)

   796 .IP "\fB\-y\fR \fIsymbol\fR" 4

   797 .IX Item "-y symbol"

   798 .PD 0

   799 .IP "\fB\-\-trace\-symbol=\fR\fIsymbol\fR" 4

   800 .IX Item "--trace-symbol=symbol"

   801 .PD

   802 Print the name of each linked file in which \fIsymbol\fR appears.  This

   803 option may be given any number of times.  On many systems it is necessary

   804 to prepend an underscore.

   805 .Sp

   806 This option is useful when you have an undefined symbol in your link but

   807 don't know where the reference is coming from.

   808 .IP "\fB\-Y\fR \fIpath\fR" 4

   809 .IX Item "-Y path"

   810 Add \fIpath\fR to the default library search path.  This option exists

   811 for Solaris compatibility.

   812 .IP "\fB\-z\fR \fIkeyword\fR" 4

   813 .IX Item "-z keyword"

   814 The recognized keywords are:

   815 .RS 4

   816 .IP "\fBcombreloc\fR" 4

   817 .IX Item "combreloc"

   818 Combines multiple reloc sections and sorts them to make dynamic symbol

   819 lookup caching possible.

   820 .IP "\fBdefs\fR" 4

   821 .IX Item "defs"

   822 Disallows undefined symbols in object files.  Undefined symbols in

   823 shared libraries are still allowed.

   824 .IP "\fBexecstack\fR" 4

   825 .IX Item "execstack"

   826 Marks the object as requiring executable stack.

   827 .IP "\fBinitfirst\fR" 4

   828 .IX Item "initfirst"

   829 This option is only meaningful when building a shared object.

   830 It marks the object so that its runtime initialization will occur

   831 before the runtime initialization of any other objects brought into

   832 the process at the same time.  Similarly the runtime finalization of

   833 the object will occur after the runtime finalization of any other

   834 objects.

   835 .IP "\fBinterpose\fR" 4

   836 .IX Item "interpose"

   837 Marks the object that its symbol table interposes before all symbols

   838 but the primary executable.

   839 .IP "\fBlazy\fR" 4

   840 .IX Item "lazy"

   841 When generating an executable or shared library, mark it to tell the

   842 dynamic linker to defer function call resolution to the point when

   843 the function is called (lazy binding), rather than at load time.

   844 Lazy binding is the default.

   845 .IP "\fBloadfltr\fR" 4

   846 .IX Item "loadfltr"

   847 Marks  the object that its filters be processed immediately at

   848 runtime.

   849 .IP "\fBmuldefs\fR" 4

   850 .IX Item "muldefs"

   851 Allows multiple definitions.

   852 .IP "\fBnocombreloc\fR" 4

   853 .IX Item "nocombreloc"

   854 Disables multiple reloc sections combining.

   855 .IP "\fBnocopyreloc\fR" 4

   856 .IX Item "nocopyreloc"

   857 Disables production of copy relocs.

   858 .IP "\fBnodefaultlib\fR" 4

   859 .IX Item "nodefaultlib"

   860 Marks the object that the search for dependencies of this object will

   861 ignore any default library search paths.

   862 .IP "\fBnodelete\fR" 4

   863 .IX Item "nodelete"

   864 Marks the object shouldn't be unloaded at runtime.

   865 .IP "\fBnodlopen\fR" 4

   866 .IX Item "nodlopen"

   867 Marks the object not available to \f(CW\*(C`dlopen\*(C'\fR.

   868 .IP "\fBnodump\fR" 4

   869 .IX Item "nodump"

   870 Marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR.

   871 .IP "\fBnoexecstack\fR" 4

   872 .IX Item "noexecstack"

   873 Marks the object as not requiring executable stack.

   874 .IP "\fBnorelro\fR" 4

   875 .IX Item "norelro"

   876 Don't create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object.

   877 .IP "\fBnow\fR" 4

   878 .IX Item "now"

   879 When generating an executable or shared library, mark it to tell the

   880 dynamic linker to resolve all symbols when the program is started, or

   881 when the shared library is linked to using dlopen, instead of

   882 deferring function call resolution to the point when the function is

   883 first called.

   884 .IP "\fBorigin\fR" 4

   885 .IX Item "origin"

   886 Marks the object may contain \f(CW$ORIGIN\fR.

   887 .IP "\fBrelro\fR" 4

   888 .IX Item "relro"

   889 Create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object.

   890 .IP "\fBmax\-page\-size=\fR\fIvalue\fR" 4

   891 .IX Item "max-page-size=value"

   892 Set the emulation maximum page size to \fIvalue\fR.

   893 .IP "\fBcommon\-page\-size=\fR\fIvalue\fR" 4

   894 .IX Item "common-page-size=value"

   895 Set the emulation common page size to \fIvalue\fR.

   896 .RE

   897 .RS 4

   898 .Sp

   899 Other keywords are ignored for Solaris compatibility.

   900 .RE

   901 .IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4

   902 .IX Item "-( archives -)"

   903 .PD 0

   904 .IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4

   905 .IX Item "--start-group archives --end-group"

   906 .PD

   907 The \fIarchives\fR should be a list of archive files.  They may be

   908 either explicit file names, or \fB\-l\fR options.

   909 .Sp

   910 The specified archives are searched repeatedly until no new undefined

   911 references are created.  Normally, an archive is searched only once in

   912 the order that it is specified on the command line.  If a symbol in that

   913 archive is needed to resolve an undefined symbol referred to by an

   914 object in an archive that appears later on the command line, the linker

   915 would not be able to resolve that reference.  By grouping the archives,

   916 they all be searched repeatedly until all possible references are

   917 resolved.

   918 .Sp

   919 Using this option has a significant performance cost.  It is best to use

   920 it only when there are unavoidable circular references between two or

   921 more archives.

   922 .IP "\fB\-\-accept\-unknown\-input\-arch\fR" 4

   923 .IX Item "--accept-unknown-input-arch"

   924 .PD 0

   925 .IP "\fB\-\-no\-accept\-unknown\-input\-arch\fR" 4

   926 .IX Item "--no-accept-unknown-input-arch"

   927 .PD

   928 Tells the linker to accept input files whose architecture cannot be

   929 recognised.  The assumption is that the user knows what they are doing

   930 and deliberately wants to link in these unknown input files.  This was

   931 the default behaviour of the linker, before release 2.14.  The default

   932 behaviour from release 2.14 onwards is to reject such input files, and

   933 so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to

   934 restore the old behaviour.

   935 .IP "\fB\-\-as\-needed\fR" 4

   936 .IX Item "--as-needed"

   937 .PD 0

   938 .IP "\fB\-\-no\-as\-needed\fR" 4

   939 .IX Item "--no-as-needed"

   940 .PD

   941 This option affects \s-1ELF\s0 \s-1DT_NEEDED\s0 tags for dynamic libraries mentioned

   942 on the command line after the \fB\-\-as\-needed\fR option.  Normally,

   943 the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned

   944 on the command line, regardless of whether the library is actually

   945 needed.  \fB\-\-as\-needed\fR causes \s-1DT_NEEDED\s0 tags to only be emitted

   946 for libraries that satisfy some symbol reference from regular objects

   947 which is undefined at the point that the library was linked.

   948 \&\fB\-\-no\-as\-needed\fR restores the default behaviour.

   949 .IP "\fB\-\-add\-needed\fR" 4

   950 .IX Item "--add-needed"

   951 .PD 0

   952 .IP "\fB\-\-no\-add\-needed\fR" 4

   953 .IX Item "--no-add-needed"

   954 .PD

   955 This option affects the treatment of dynamic libraries from \s-1ELF\s0

   956 \&\s-1DT_NEEDED\s0 tags in dynamic libraries mentioned on the command line after

   957 the \fB\-\-no\-add\-needed\fR option.  Normally, the linker will add

   958 a \s-1DT_NEEDED\s0 tag for each dynamic library from \s-1DT_NEEDED\s0 tags.

   959 \&\fB\-\-no\-add\-needed\fR causes \s-1DT_NEEDED\s0 tags will never be emitted

   960 for those libraries from \s-1DT_NEEDED\s0 tags. \fB\-\-add\-needed\fR restores

   961 the default behaviour.

   962 .IP "\fB\-assert\fR \fIkeyword\fR" 4

   963 .IX Item "-assert keyword"

   964 This option is ignored for SunOS compatibility.

   965 .IP "\fB\-Bdynamic\fR" 4

   966 .IX Item "-Bdynamic"

   967 .PD 0

   968 .IP "\fB\-dy\fR" 4

   969 .IX Item "-dy"

   970 .IP "\fB\-call_shared\fR" 4

   971 .IX Item "-call_shared"

   972 .PD

   973 Link against dynamic libraries.  This is only meaningful on platforms

   974 for which shared libraries are supported.  This option is normally the

   975 default on such platforms.  The different variants of this option are

   976 for compatibility with various systems.  You may use this option

   977 multiple times on the command line: it affects library searching for

   978 \&\fB\-l\fR options which follow it.

   979 .IP "\fB\-Bgroup\fR" 4

   980 .IX Item "-Bgroup"

   981 Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR entry in the dynamic

   982 section.  This causes the runtime linker to handle lookups in this

   983 object and its dependencies to be performed only inside the group.

   984 \&\fB\-\-unresolved\-symbols=report\-all\fR is implied.  This option is

   985 only meaningful on \s-1ELF\s0 platforms which support shared libraries.

   986 .IP "\fB\-Bstatic\fR" 4

   987 .IX Item "-Bstatic"

   988 .PD 0

   989 .IP "\fB\-dn\fR" 4

   990 .IX Item "-dn"

   991 .IP "\fB\-non_shared\fR" 4

   992 .IX Item "-non_shared"

   993 .IP "\fB\-static\fR" 4

   994 .IX Item "-static"

   995 .PD

   996 Do not link against shared libraries.  This is only meaningful on

   997 platforms for which shared libraries are supported.  The different

   998 variants of this option are for compatibility with various systems.  You

   999 may use this option multiple times on the command line: it affects

  1000 library searching for \fB\-l\fR options which follow it.  This

  1001 option also implies \fB\-\-unresolved\-symbols=report\-all\fR.  This

  1002 option can be used with \fB\-shared\fR.  Doing so means that a

  1003 shared library is being created but that all of the library's external

  1004 references must be resolved by pulling in entries from static

  1005 libraries.

  1006 .IP "\fB\-Bsymbolic\fR" 4

  1007 .IX Item "-Bsymbolic"

  1008 When creating a shared library, bind references to global symbols to the

  1009 definition within the shared library, if any.  Normally, it is possible

  1010 for a program linked against a shared library to override the definition

  1011 within the shared library.  This option is only meaningful on \s-1ELF\s0

  1012 platforms which support shared libraries.

  1013 .IP "\fB\-Bsymbolic\-functions\fR" 4

  1014 .IX Item "-Bsymbolic-functions"

  1015 When creating a shared library, bind references to global function

  1016 symbols to the definition within the shared library, if any.

  1017 This option is only meaningful on \s-1ELF\s0 platforms which support shared

  1018 libraries.

  1019 .IP "\fB\-\-dynamic\-list=\fR\fIdynamic-list-file\fR" 4

  1020 .IX Item "--dynamic-list=dynamic-list-file"

  1021 Specify the name of a dynamic list file to the linker.  This is

  1022 typically used when creating shared libraries to specify a list of

  1023 global symbols whose references shouldn't be bound to the definition

  1024 within the shared library, or creating dynamically linked executables

  1025 to specify a list of symbols which should be added to the symbol table

  1026 in the executable.  This option is only meaningful on \s-1ELF\s0 platforms

  1027 which support shared libraries.

  1028 .Sp

  1029 The format of the dynamic list is the same as the version node without

  1030 scope and node name.  See \fB\s-1VERSION\s0\fR for more information.

  1031 .IP "\fB\-\-dynamic\-list\-data\fR" 4

  1032 .IX Item "--dynamic-list-data"

  1033 Include all global data symbols to the dynamic list.

  1034 .IP "\fB\-\-dynamic\-list\-cpp\-new\fR" 4

  1035 .IX Item "--dynamic-list-cpp-new"

  1036 Provide the builtin dynamic list for \*(C+ operator new and delete.  It

  1037 is mainly useful for building shared libstdc++.

  1038 .IP "\fB\-\-dynamic\-list\-cpp\-typeinfo\fR" 4

  1039 .IX Item "--dynamic-list-cpp-typeinfo"

  1040 Provide the builtin dynamic list for \*(C+ runtime type identification.

  1041 .IP "\fB\-\-check\-sections\fR" 4

  1042 .IX Item "--check-sections"

  1043 .PD 0

  1044 .IP "\fB\-\-no\-check\-sections\fR" 4

  1045 .IX Item "--no-check-sections"

  1046 .PD

  1047 Asks the linker \fInot\fR to check section addresses after they have

  1048 been assigned to see if there are any overlaps.  Normally the linker will

  1049 perform this check, and if it finds any overlaps it will produce

  1050 suitable error messages.  The linker does know about, and does make

  1051 allowances for sections in overlays.  The default behaviour can be

  1052 restored by using the command line switch \fB\-\-check\-sections\fR.

  1053 .IP "\fB\-\-cref\fR" 4

  1054 .IX Item "--cref"

  1055 Output a cross reference table.  If a linker map file is being

  1056 generated, the cross reference table is printed to the map file.

  1057 Otherwise, it is printed on the standard output.

  1058 .Sp

  1059 The format of the table is intentionally simple, so that it may be

  1060 easily processed by a script if necessary.  The symbols are printed out,

  1061 sorted by name.  For each symbol, a list of file names is given.  If the

  1062 symbol is defined, the first file listed is the location of the

  1063 definition.  The remaining files contain references to the symbol.

  1064 .IP "\fB\-\-no\-define\-common\fR" 4

  1065 .IX Item "--no-define-common"

  1066 This option inhibits the assignment of addresses to common symbols.

  1067 The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect.

  1068 .Sp

  1069 The \fB\-\-no\-define\-common\fR option allows decoupling

  1070 the decision to assign addresses to Common symbols from the choice

  1071 of the output file type; otherwise a non-Relocatable output type

  1072 forces assigning addresses to Common symbols.

  1073 Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced

  1074 from a shared library to be assigned addresses only in the main program.

  1075 This eliminates the unused duplicate space in the shared library,

  1076 and also prevents any possible confusion over resolving to the wrong

  1077 duplicate when there are many dynamic modules with specialized search

  1078 paths for runtime symbol resolution.

  1079 .IP "\fB\-\-defsym\fR \fIsymbol\fR\fB=\fR\fIexpression\fR" 4

  1080 .IX Item "--defsym symbol=expression"

  1081 Create a global symbol in the output file, containing the absolute

  1082 address given by \fIexpression\fR.  You may use this option as many

  1083 times as necessary to define multiple symbols in the command line.  A

  1084 limited form of arithmetic is supported for the \fIexpression\fR in this

  1085 context: you may give a hexadecimal constant or the name of an existing

  1086 symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal

  1087 constants or symbols.  If you need more elaborate expressions, consider

  1088 using the linker command language from a script.  \fINote:\fR there should be no white

  1089 space between \fIsymbol\fR, the equals sign ("\fB=\fR"), and

  1090 \&\fIexpression\fR.

  1091 .IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4

  1092 .IX Item "--demangle[=style]"

  1093 .PD 0

  1094 .IP "\fB\-\-no\-demangle\fR" 4

  1095 .IX Item "--no-demangle"

  1096 .PD

  1097 These options control whether to demangle symbol names in error messages

  1098 and other output.  When the linker is told to demangle, it tries to

  1099 present symbol names in a readable fashion: it strips leading

  1100 underscores if they are used by the object file format, and converts \*(C+

  1101 mangled symbol names into user readable names.  Different compilers have

  1102 different mangling styles.  The optional demangling style argument can be used

  1103 to choose an appropriate demangling style for your compiler.  The linker will

  1104 demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR

  1105 is set.  These options may be used to override the default.

  1106 .IP "\fB\-\-dynamic\-linker\fR \fIfile\fR" 4

  1107 .IX Item "--dynamic-linker file"

  1108 Set the name of the dynamic linker.  This is only meaningful when

  1109 generating dynamically linked \s-1ELF\s0 executables.  The default dynamic

  1110 linker is normally correct; don't use this unless you know what you are

  1111 doing.

  1112 .IP "\fB\-\-fatal\-warnings\fR" 4

  1113 .IX Item "--fatal-warnings"

  1114 Treat all warnings as errors.

  1115 .IP "\fB\-\-force\-exe\-suffix\fR" 4

  1116 .IX Item "--force-exe-suffix"

  1117 Make sure that an output file has a .exe suffix.

  1118 .Sp

  1119 If a successfully built fully linked output file does not have a

  1120 \&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy

  1121 the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This

  1122 option is useful when using unmodified Unix makefiles on a Microsoft

  1123 Windows host, since some versions of Windows won't run an image unless

  1124 it ends in a \f(CW\*(C`.exe\*(C'\fR suffix.

  1125 .IP "\fB\-\-gc\-sections\fR" 4

  1126 .IX Item "--gc-sections"

  1127 .PD 0

  1128 .IP "\fB\-\-no\-gc\-sections\fR" 4

  1129 .IX Item "--no-gc-sections"

  1130 .PD

  1131 Enable garbage collection of unused input sections.  It is ignored on

  1132 targets that do not support this option.  This option is not compatible

  1133 with \fB\-r\fR or \fB\-\-emit\-relocs\fR. The default behaviour (of not

  1134 performing this garbage collection) can be restored by specifying

  1135 \&\fB\-\-no\-gc\-sections\fR on the command line.